Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
stored_file Class Reference

Class representing local files stored in a sha1 file pool. More...

Public Member Functions

 __construct (file_storage $fs, stdClass $file_record, $deprecated=null)
 Constructor, this constructor should be called ONLY from the file_storage class!
 
 __sleep ()
 Magic method, called during serialization.
 
 __wakeup ()
 Magic method, called during unserialization.
 
 add_to_curl_request (&$curlrequest, $key)
 adds this file path to a curl request (POST only)
 
 archive_file (file_archive $filearch, $archivepath)
 Add file/directory into archive.
 
 compare_to_path ($path)
 Check whether the supplied file is the same as this file.
 
 compare_to_string ($content)
 Check whether the supplied content is the same as this file.
 
 copy_content_to ($pathname)
 Copy content of file to given pathname.
 
 copy_content_to_temp ($dir='files', $fileprefix='tempup_')
 Copy content of file to temporary folder and returns file path.
 
 delete ()
 Delete file from files table.
 
 delete_reference ()
 Unlink the stored file from the referenced file.
 
 extract_to_pathname (file_packer $packer, $pathname, file_progress $progress=null)
 Extract file to given file path (real OS filesystem), existing files are overwritten.
 
 extract_to_storage (file_packer $packer, $contextid, $component, $filearea, $itemid, $pathbase, $userid=null, file_progress $progress=null)
 Extract file to given file path (real OS filesystem), existing files are overwritten.
 
 generate_image_thumbnail ($width, $height)
 Generates a thumbnail for this stored_file.
 
 get_author ()
 Returns the author name of the file.
 
 get_component ()
 Returns component name - this is the owner of the areas, nothing else is allowed to read or modify the files directly!!
 
 get_content ()
 Returns file content as string.
 
 get_content_file_handle ($type=self::FILE_HANDLE_FOPEN)
 Returns file handle - read only mode, no writing allowed into pool files!
 
 get_contenthash ()
 Returns sha1 hash of file content.
 
 get_contextid ()
 Returns context id of the file.
 
 get_filearea ()
 Returns file area name, this divides files of one component into groups with different access control.
 
 get_filename ()
 Returns file name or '.
 
 get_filepath ()
 Returns file path - starts and ends with /, are not allowed.
 
 get_filesize ()
 Returns the size of file in bytes.
 
 get_id ()
 Returns file id.
 
 get_imageinfo ()
 Returns information about image, information is determined from the file content.
 
 get_itemid ()
 Returns returns item id of file.
 
 get_license ()
 Returns the license type of the file, it is a short name referred from license table.
 
 get_mimetype ()
 Returns mime type of file.
 
 get_parent_directory ()
 Returns parent directory, creates missing parents if needed.
 
 get_pathnamehash ()
 Returns sha1 hash of all file path components sha1("contextid/component/filearea/itemid/dir/dir/filename.ext").
 
 get_psr_stream ()
 Get a read-only PSR-7 stream for this file.
 
 get_reference ()
 Returns file reference.
 
 get_reference_details ()
 Get human readable file reference information.
 
 get_referencefileid ()
 get reference file id
 
 get_referencelastsync ()
 Get reference last sync time.
 
 get_referencelifetime ()
 Function stored_file\get_referencelifetime() is deprecated as reference life time is no longer stored in DB or returned by repository.
 
 get_repository_id ()
 Returns repository id.
 
 get_repository_type ()
 Returns repository type.
 
 get_sortorder ()
 Returns the sort order of file.
 
 get_source ()
 Returns the source of the file, usually it is a url.
 
 get_status ()
 Returns file status flag.
 
 get_timecreated ()
 Returns unix timestamp of file creation date.
 
 get_timemodified ()
 Returns unix timestamp of last file modification.
 
 get_total_content_size (file_packer $packer)
 Returns the total size (in bytes) of the contents of an archive.
 
 get_userid ()
 Returns id of user who created the file.
 
 import_external_file_contents ($maxbytes=0)
 Imports the contents of an external file into moodle filepool.
 
 is_controlled_link ()
 Whether or not this is a controlled link.
 
 is_directory ()
 Is this a directory?
 
 is_external_file ()
 Whether or not this is a external resource.
 
 is_valid_image ()
 Verifies the file is a valid web image - gif, png and jpeg only.
 
 list_files (file_packer $packer)
 List contents of archive.
 
 readfile ()
 Dumps file content to page.
 
 rename ($filepath, $filename)
 Rename filename.
 
 replace_content_with (stored_file $storedfile)
 Function stored_file\replace_content_with() is deprecated.
 
 replace_file_with (stored_file $newfile)
 Replaces the fields that might have changed when file was overriden in filepicker: reference, contenthash, filesize, userid.
 
 resize_image ($width, $height)
 Generate a resized image for this stored_file.
 
 rotate_image ()
 Generate a rotated image for this stored_file based on exif information.
 
 send_file ($lifetime, $filter, $forcedownload, $options)
 Send file references.
 
 send_relative_file ($relativepath)
 Gets a file relative to this file in the repository and sends it to the browser.
 
 set_author ($author)
 Set author.
 
 set_filesize ($filesize)
 Function stored_file\set_filesize() is deprecated.
 
 set_license ($license)
 Set license.
 
 set_missingsource ()
 Sets the error status for a file that could not be synchronised.
 
 set_sortorder ($sortorder)
 Set file sort order.
 
 set_source ($source)
 Set license.
 
 set_synchronised_content_from_file ($path)
 Set synchronised content from file.
 
 set_synchronised_content_from_string ($content)
 Set synchronised content from content.
 
 set_synchronized ($contenthash, $filesize, $status=0, $timemodified=null)
 Called after reference-file has been synchronized with the repository.
 
 set_timemodified ($timemodified)
 set timemodified
 
 sync_external_file ()
 Synchronize file if it is a reference and needs synchronizing.
 

Public Attributes

int const FILE_HANDLE_FOPEN = 0
 Indicates a file handle of the type returned by fopen.
 
int const FILE_HANDLE_GZOPEN = 1
 Indicates a file handle of the type returned by gzopen.
 

Protected Member Functions

 update ($dataobject)
 Update some file record fields NOTE: Must remain protected.
 

Detailed Description

Class representing local files stored in a sha1 file pool.

Since Moodle 2.0 file contents are stored in sha1 pool and all other file information is stored in new "files" database table.

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
Since
Moodle 2.0

Constructor & Destructor Documentation

◆ __construct()

stored_file::__construct ( file_storage $fs,
stdClass $file_record,
$deprecated = null )

Constructor, this constructor should be called ONLY from the file_storage class!

Parameters
file_storage$fsfile storage instance
stdClass$file_recorddescription of file
string$deprecated

Member Function Documentation

◆ __sleep()

stored_file::__sleep ( )

Magic method, called during serialization.

Return values
array

◆ add_to_curl_request()

stored_file::add_to_curl_request ( & $curlrequest,
$key )

adds this file path to a curl request (POST only)

Parameters
curl$curlrequestthe curl request object
string$keywhat key to use in the POST request
Return values
void

◆ archive_file()

stored_file::archive_file ( file_archive $filearch,
$archivepath )

Add file/directory into archive.

Parameters
file_archive$filearchfile archive instance
string$archivepathpathname in archive
Return values
boolsuccess

◆ compare_to_path()

stored_file::compare_to_path ( $path)

Check whether the supplied file is the same as this file.

Parameters
string$pathThe path to the file on disk
Return values
boolean

◆ compare_to_string()

stored_file::compare_to_string ( $content)

Check whether the supplied content is the same as this file.

Parameters
string$contentThe file content
Return values
boolean

◆ copy_content_to()

stored_file::copy_content_to ( $pathname)

Copy content of file to given pathname.

Parameters
string$pathnamereal path to the new file
Return values
boolsuccess

◆ copy_content_to_temp()

stored_file::copy_content_to_temp ( $dir = 'files',
$fileprefix = 'tempup_' )

Copy content of file to temporary folder and returns file path.

Parameters
string$dirname of the temporary directory
string$fileprefixprefix of temporary file.
Return values
string|boolpath of temporary file or false.

◆ delete()

stored_file::delete ( )

Delete file from files table.

The content of files stored in sha1 pool is reclaimed later - the occupied disk space is reclaimed much later.

Return values
boolalways true or exception if error occurred

◆ delete_reference()

stored_file::delete_reference ( )

Unlink the stored file from the referenced file.

This methods destroys the link to the record in files_reference table. This effectively turns the stored file from being an alias to a plain copy. However, the caller has to make sure that the actual file's content has beed synced prior to calling this method.

◆ extract_to_pathname()

stored_file::extract_to_pathname ( file_packer $packer,
$pathname,
file_progress $progress = null )

Extract file to given file path (real OS filesystem), existing files are overwritten.

Parameters
file_packer$packerfile packer instance
string$pathnametarget directory
file_progress$progressProgress indicator callback or null if not required
Return values
array|boollist of processed files; false if error

◆ extract_to_storage()

stored_file::extract_to_storage ( file_packer $packer,
$contextid,
$component,
$filearea,
$itemid,
$pathbase,
$userid = null,
file_progress $progress = null )

Extract file to given file path (real OS filesystem), existing files are overwritten.

Parameters
file_packer$packerfile packer instance
int$contextidcontext ID
string$componentcomponent
string$fileareafile area
int$itemiditem ID
string$pathbasepath base
int$useriduser ID
file_progress$progressProgress indicator callback or null if not required
Return values
array|boollist of processed files; false if error

◆ generate_image_thumbnail()

stored_file::generate_image_thumbnail ( $width,
$height )

Generates a thumbnail for this stored_file.

If the GD library has at least version 2 and PNG support is available, the returned data is the content of a transparent PNG file containing the thumbnail. Otherwise, the function returns contents of a JPEG file with black background containing the thumbnail.

Parameters
int$widththe width of the requested thumbnail
int$heightthe height of the requested thumbnail
Return values
string|boolfalse if a problem occurs, the thumbnail image data otherwise

◆ get_author()

stored_file::get_author ( )

Returns the author name of the file.

Return values
string

◆ get_component()

stored_file::get_component ( )

Returns component name - this is the owner of the areas, nothing else is allowed to read or modify the files directly!!

Return values
string

◆ get_content()

stored_file::get_content ( )

Returns file content as string.

Return values
stringcontent

◆ get_content_file_handle()

stored_file::get_content_file_handle ( $type = self::FILE_HANDLE_FOPEN)

Returns file handle - read only mode, no writing allowed into pool files!

When you want to modify a file, create a new file and delete the old one.

Parameters
int$typeType of file handle (FILE_HANDLE_xx constant)
Return values
resourcefile handle

◆ get_contenthash()

stored_file::get_contenthash ( )

Returns sha1 hash of file content.

Return values
string

◆ get_contextid()

stored_file::get_contextid ( )

Returns context id of the file.

Return values
intcontext id

◆ get_filearea()

stored_file::get_filearea ( )

Returns file area name, this divides files of one component into groups with different access control.

All files in one area have the same access control.

Return values
string

◆ get_filename()

stored_file::get_filename ( )

Returns file name or '.

' in case of directories.

Return values
string

◆ get_filepath()

stored_file::get_filepath ( )

Returns file path - starts and ends with /, are not allowed.

Return values
string

◆ get_filesize()

stored_file::get_filesize ( )

Returns the size of file in bytes.

Return values
intbytes

◆ get_id()

stored_file::get_id ( )

Returns file id.

Return values
int

◆ get_imageinfo()

stored_file::get_imageinfo ( )

Returns information about image, information is determined from the file content.

Return values
mixedarray with width, height and mimetype; false if not an image

◆ get_itemid()

stored_file::get_itemid ( )

Returns returns item id of file.

Return values
int

◆ get_license()

stored_file::get_license ( )

Returns the license type of the file, it is a short name referred from license table.

Return values
string

◆ get_mimetype()

stored_file::get_mimetype ( )

Returns mime type of file.

Return values
string

◆ get_parent_directory()

stored_file::get_parent_directory ( )

Returns parent directory, creates missing parents if needed.

Return values
stored_file

◆ get_pathnamehash()

stored_file::get_pathnamehash ( )

Returns sha1 hash of all file path components sha1("contextid/component/filearea/itemid/dir/dir/filename.ext").

Return values
string

◆ get_psr_stream()

stored_file::get_psr_stream ( )

Get a read-only PSR-7 stream for this file.

Note: This stream is read-only. If you want to modify the file, create a new file and delete the old one. The File API creates immutable files.

Return values
StreamInterface

◆ get_reference()

stored_file::get_reference ( )

Returns file reference.

Return values
string

◆ get_reference_details()

stored_file::get_reference_details ( )

Get human readable file reference information.

Return values
string

◆ get_referencefileid()

stored_file::get_referencefileid ( )

get reference file id

Return values
int

◆ get_referencelastsync()

stored_file::get_referencelastsync ( )

Get reference last sync time.

Return values
int

◆ get_referencelifetime()

stored_file::get_referencelifetime ( )

Function stored_file\get_referencelifetime() is deprecated as reference life time is no longer stored in DB or returned by repository.

Each repository should decide by itself when to synchronise the references.

Deprecated
since Moodle 2.6 MDL-42016 - please do not use this function any more.
See also
repository\sync_reference()

◆ get_repository_id()

stored_file::get_repository_id ( )

Returns repository id.

Return values
int|null

◆ get_repository_type()

stored_file::get_repository_type ( )

Returns repository type.

Return values
mixedstr|null the repository type or null if is not an external file
Since
Moodle 3.3

◆ get_sortorder()

stored_file::get_sortorder ( )

Returns the sort order of file.

Return values
int

◆ get_source()

stored_file::get_source ( )

Returns the source of the file, usually it is a url.

Return values
string

◆ get_status()

stored_file::get_status ( )

Returns file status flag.

Return values
int0 means file OK, anything else is a problem and file can not be used

◆ get_timecreated()

stored_file::get_timecreated ( )

Returns unix timestamp of file creation date.

Return values
int

◆ get_timemodified()

stored_file::get_timemodified ( )

Returns unix timestamp of last file modification.

Return values
int

◆ get_total_content_size()

stored_file::get_total_content_size ( file_packer $packer)

Returns the total size (in bytes) of the contents of an archive.

Parameters
file_packer$packerfile packer instance
Return values
int|nulltotal size in bytes

◆ get_userid()

stored_file::get_userid ( )

Returns id of user who created the file.

Return values
int

◆ import_external_file_contents()

stored_file::import_external_file_contents ( $maxbytes = 0)

Imports the contents of an external file into moodle filepool.

Exceptions
moodle_exceptionif file could not be downloaded or is too big
Parameters
int$maxbytesthrow an exception if file size is bigger than $maxbytes (0 means no limit)

◆ is_controlled_link()

stored_file::is_controlled_link ( )

Whether or not this is a controlled link.

Note that repositories cannot support FILE_REFERENCE and FILE_CONTROLLED_LINK.

Return values
bool

◆ is_directory()

stored_file::is_directory ( )

Is this a directory?

Directories are only emulated, internally they are stored as empty files with a "." instead of name - this means empty directory contains exactly one empty file with name dot.

Return values
booltrue means directory, false means file

◆ is_external_file()

stored_file::is_external_file ( )

Whether or not this is a external resource.

Return values
bool

◆ is_valid_image()

stored_file::is_valid_image ( )

Verifies the file is a valid web image - gif, png and jpeg only.

It should be ok to serve this image from server without any other security workarounds.

Return values
booltrue if file ok

◆ list_files()

stored_file::list_files ( file_packer $packer)

List contents of archive.

Parameters
file_packer$packerfile packer instance
Return values
arrayof file infos

◆ rename()

stored_file::rename ( $filepath,
$filename )

Rename filename.

Parameters
string$filepathfile path
string$filenamefile name

◆ replace_content_with()

stored_file::replace_content_with ( stored_file $storedfile)

Function stored_file\replace_content_with() is deprecated.

Please use stored_file\replace_file_with()

Deprecated
since Moodle 2.6 MDL-42016 - please do not use this function any more.
See also
stored_file\replace_file_with()

◆ replace_file_with()

stored_file::replace_file_with ( stored_file $newfile)

Replaces the fields that might have changed when file was overriden in filepicker: reference, contenthash, filesize, userid.

Note that field 'source' must be updated separately because it has different format for draft and non-draft areas and this function will usually be used to replace non-draft area file with draft area file.

Parameters
stored_file$newfile
Exceptions
coding_exception

◆ resize_image()

stored_file::resize_image ( $width,
$height )

Generate a resized image for this stored_file.

Parameters
int | null$widthThe desired width, or null to only use the height.
int | null$heightThe desired height, or null to only use the width.
Return values
string|falseFalse when a problem occurs, else the image data.

◆ rotate_image()

stored_file::rotate_image ( )

Generate a rotated image for this stored_file based on exif information.

Return values
array|falseFalse when a problem occurs, else the image data and image size.
Since
Moodle 3.8

◆ send_file()

stored_file::send_file ( $lifetime,
$filter,
$forcedownload,
$options )

Send file references.

Parameters
int$lifetimeNumber of seconds before the file should expire from caches (default 24 hours)
int$filter0 (default)=no filtering, 1=all files, 2=html files only
bool$forcedownloadIf true (default false), forces download of file rather than view in browser/plugin
array$optionsadditional options affecting the file serving

◆ send_relative_file()

stored_file::send_relative_file ( $relativepath)

Gets a file relative to this file in the repository and sends it to the browser.

Checks the function repository\supports_relative_file() to make sure it can be used.

Parameters
string$relativepaththe relative path to the file we are trying to access

◆ set_author()

stored_file::set_author ( $author)

Set author.

Parameters
string$author

◆ set_filesize()

stored_file::set_filesize ( $filesize)

Function stored_file\set_filesize() is deprecated.

Please use stored_file\replace_file_with

Deprecated
since Moodle 2.6 MDL-42016 - please do not use this function any more.
See also
stored_file\replace_file_with()

◆ set_license()

stored_file::set_license ( $license)

Set license.

Parameters
string$licenselicense

◆ set_sortorder()

stored_file::set_sortorder ( $sortorder)

Set file sort order.

Parameters
int$sortorder
Return values
int

◆ set_source()

stored_file::set_source ( $source)

Set license.

Parameters
string$licenselicense

◆ set_synchronised_content_from_file()

stored_file::set_synchronised_content_from_file ( $path)

Set synchronised content from file.

Parameters
string$pathPath to the file.

◆ set_synchronised_content_from_string()

stored_file::set_synchronised_content_from_string ( $content)

Set synchronised content from content.

Parameters
string$contentFile content.

◆ set_synchronized()

stored_file::set_synchronized ( $contenthash,
$filesize,
$status = 0,
$timemodified = null )

Called after reference-file has been synchronized with the repository.

We update contenthash, filesize and status in files table if changed and we always update lastsync in files_reference table

Parameters
null | string$contenthashif set to null contenthash is not changed
int$filesizenew size of the file
int$statusnew status of the file (0 means OK, 666 - source missing)
int$timemodifiedlast time modified of the source, if known

◆ set_timemodified()

stored_file::set_timemodified ( $timemodified)

set timemodified

Parameters
int$timemodified

◆ sync_external_file()

stored_file::sync_external_file ( )

Synchronize file if it is a reference and needs synchronizing.

Updates contenthash and filesize

◆ update()

stored_file::update ( $dataobject)
protected

Update some file record fields NOTE: Must remain protected.

Parameters
stdClass$dataobject

The documentation for this class was generated from the following file: