Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
Public Member Functions | Public Attributes | Protected Member Functions | List of all members
stored_file Class Reference

Public Member Functions

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

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. More...
 

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_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: