Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

Definition of a class stored_file.

Copyright: 2008 Petr Skoda {@link http://skodak.org}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1214 lines (42 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

stored_file:: (72 methods):
  __construct()
  __sleep()
  __wakeup()
  is_external_file()
  is_controlled_link()
  update()
  rename()
  replace_content_with()
  replace_file_with()
  delete_reference()
  is_directory()
  delete()
  add_to_curl_request()
  get_content_file_handle()
  get_psr_stream()
  readfile()
  get_content()
  copy_content_to()
  copy_content_to_temp()
  list_files()
  get_total_content_size()
  extract_to_pathname()
  extract_to_storage()
  archive_file()
  get_imageinfo()
  is_valid_image()
  get_parent_directory()
  set_synchronised_content_from_file()
  set_synchronised_content_from_string()
  sync_external_file()
  get_contextid()
  get_component()
  get_filearea()
  get_itemid()
  get_filepath()
  get_filename()
  get_userid()
  get_filesize()
  set_filesize()
  get_mimetype()
  get_timecreated()
  get_timemodified()
  set_timemodified()
  get_status()
  get_id()
  get_contenthash()
  get_pathnamehash()
  get_license()
  set_license()
  get_author()
  set_author()
  get_source()
  set_source()
  get_sortorder()
  set_sortorder()
  get_repository_id()
  get_repository_type()
  get_referencefileid()
  get_referencelastsync()
  get_referencelifetime()
  get_reference()
  get_reference_details()
  set_synchronized()
  set_missingsource()
  send_file()
  import_external_file_contents()
  send_relative_file()
  generate_image_thumbnail()
  resize_image()
  compare_to_path()
  compare_to_string()
  rotate_image()


Class: stored_file  - X-Ref

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.

__construct(file_storage $fs, stdClass $file_record, $deprecated = null)   X-Ref
Constructor, this constructor should be called ONLY from the file_storage class!

param: file_storage $fs file  storage instance
param: stdClass $file_record description of file
param: string $deprecated

__sleep()   X-Ref
Magic method, called during serialization.

return: array

__wakeup()   X-Ref
Magic method, called during unserialization.


is_external_file()   X-Ref
Whether or not this is a external resource

return: bool

is_controlled_link()   X-Ref
Whether or not this is a controlled link. Note that repositories cannot support FILE_REFERENCE and FILE_CONTROLLED_LINK.

return: bool

update($dataobject)   X-Ref
Update some file record fields
NOTE: Must remain protected

param: stdClass $dataobject

rename($filepath, $filename)   X-Ref
Rename filename

param: string $filepath file path
param: string $filename file name

replace_content_with(stored_file $storedfile)   X-Ref
Function stored_file::replace_content_with() is deprecated. Please use stored_file::replace_file_with()


replace_file_with(stored_file $newfile)   X-Ref
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.

param: stored_file $newfile

delete_reference()   X-Ref
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.

is_directory()   X-Ref
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: bool true means directory, false means file

delete()   X-Ref
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: bool always true or exception if error occurred

add_to_curl_request(&$curlrequest, $key)   X-Ref
adds this file path to a curl request (POST only)

param: curl $curlrequest the curl request object
param: string $key what key to use in the POST request
return: void

get_content_file_handle($type = self::FILE_HANDLE_FOPEN)   X-Ref
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.

param: int $type Type of file handle (FILE_HANDLE_xx constant)
return: resource file handle

get_psr_stream()   X-Ref
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: StreamInterface

readfile()   X-Ref
Dumps file content to page.


get_content()   X-Ref
Returns file content as string.

return: string content

copy_content_to($pathname)   X-Ref
Copy content of file to given pathname.

param: string $pathname real path to the new file
return: bool success

copy_content_to_temp($dir = 'files', $fileprefix = 'tempup_')   X-Ref
Copy content of file to temporary folder and returns file path

param: string $dir name of the temporary directory
param: string $fileprefix prefix of temporary file.
return: string|bool path of temporary file or false.

list_files(file_packer $packer)   X-Ref
List contents of archive.

param: file_packer $packer file packer instance
return: array of file infos

get_total_content_size(file_packer $packer)   X-Ref
Returns the total size (in bytes) of the contents of an archive.

param: file_packer $packer file packer instance
return: int|null total size in bytes

extract_to_pathname(file_packer $packer, $pathname,file_progress $progress = null)   X-Ref
Extract file to given file path (real OS filesystem), existing files are overwritten.

param: file_packer $packer file packer instance
param: string $pathname target directory
param: file_progress $progress Progress indicator callback or null if not required
return: array|bool list of processed files; false if error

extract_to_storage(file_packer $packer, $contextid,$component, $filearea, $itemid, $pathbase, $userid = null, file_progress $progress = null)   X-Ref
Extract file to given file path (real OS filesystem), existing files are overwritten.

param: file_packer $packer file packer instance
param: int $contextid context ID
param: string $component component
param: string $filearea file area
param: int $itemid item ID
param: string $pathbase path base
param: int $userid user ID
param: file_progress $progress Progress indicator callback or null if not required
return: array|bool list of processed files; false if error

archive_file(file_archive $filearch, $archivepath)   X-Ref
Add file/directory into archive.

param: file_archive $filearch file archive instance
param: string $archivepath pathname in archive
return: bool success

get_imageinfo()   X-Ref
Returns information about image,
information is determined from the file content

return: mixed array with width, height and mimetype; false if not an image

is_valid_image()   X-Ref
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: bool true if file ok

get_parent_directory()   X-Ref
Returns parent directory, creates missing parents if needed.

return: stored_file

set_synchronised_content_from_file($path)   X-Ref
Set synchronised content from file.

param: string $path Path to the file.

set_synchronised_content_from_string($content)   X-Ref
Set synchronised content from content.

param: string $content File content.

sync_external_file()   X-Ref
Synchronize file if it is a reference and needs synchronizing

Updates contenthash and filesize

get_contextid()   X-Ref
Returns context id of the file

return: int context id

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

return: string

get_filearea()   X-Ref
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: string

get_itemid()   X-Ref
Returns returns item id of file.

return: int

get_filepath()   X-Ref
Returns file path - starts and ends with /, \ are not allowed.

return: string

get_filename()   X-Ref
Returns file name or '.' in case of directories.

return: string

get_userid()   X-Ref
Returns id of user who created the file.

return: int

get_filesize()   X-Ref
Returns the size of file in bytes.

return: int bytes

set_filesize($filesize)   X-Ref
Function stored_file::set_filesize() is deprecated. Please use stored_file::replace_file_with


get_mimetype()   X-Ref
Returns mime type of file.

return: string

get_timecreated()   X-Ref
Returns unix timestamp of file creation date.

return: int

get_timemodified()   X-Ref
Returns unix timestamp of last file modification.

return: int

set_timemodified($timemodified)   X-Ref
set timemodified

param: int $timemodified

get_status()   X-Ref
Returns file status flag.

return: int 0 means file OK, anything else is a problem and file can not be used

get_id()   X-Ref
Returns file id.

return: int

get_contenthash()   X-Ref
Returns sha1 hash of file content.

return: string

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

return: string

get_license()   X-Ref
Returns the license type of the file, it is a short name referred from license table.

return: string

set_license($license)   X-Ref
Set license

param: string $license license

get_author()   X-Ref
Returns the author name of the file.

return: string

set_author($author)   X-Ref
Set author

param: string $author

get_source()   X-Ref
Returns the source of the file, usually it is a url.

return: string

set_source($source)   X-Ref
Set license

param: string $license license

get_sortorder()   X-Ref
Returns the sort order of file

return: int

set_sortorder($sortorder)   X-Ref
Set file sort order

param: int $sortorder
return: int

get_repository_id()   X-Ref
Returns repository id

return: int|null

get_repository_type()   X-Ref
Returns repository type.

return: mixed str|null the repository type or null if is not an external file

get_referencefileid()   X-Ref
get reference file id

return: int

get_referencelastsync()   X-Ref
Get reference last sync time

return: int

get_referencelifetime()   X-Ref
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.


get_reference()   X-Ref
Returns file reference

return: string

get_reference_details()   X-Ref
Get human readable file reference information

return: string

set_synchronized($contenthash, $filesize, $status = 0, $timemodified = null)   X-Ref
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

param: null|string $contenthash if set to null contenthash is not changed
param: int $filesize new size of the file
param: int $status new status of the file (0 means OK, 666 - source missing)
param: int $timemodified last time modified of the source, if known

set_missingsource()   X-Ref
Sets the error status for a file that could not be synchronised


send_file($lifetime, $filter, $forcedownload, $options)   X-Ref
Send file references

param: int $lifetime Number of seconds before the file should expire from caches (default 24 hours)
param: int $filter 0 (default)=no filtering, 1=all files, 2=html files only
param: bool $forcedownload If true (default false), forces download of file rather than view in browser/plugin
param: array $options additional options affecting the file serving

import_external_file_contents($maxbytes = 0)   X-Ref
Imports the contents of an external file into moodle filepool.

param: int $maxbytes throw an exception if file size is bigger than $maxbytes (0 means no limit)

send_relative_file($relativepath)   X-Ref
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.

param: string $relativepath the relative path to the file we are trying to access

generate_image_thumbnail($width, $height)   X-Ref
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.

param: int $width the width of the requested thumbnail
param: int $height the height of the requested thumbnail
return: string|bool false if a problem occurs, the thumbnail image data otherwise

resize_image($width, $height)   X-Ref
Generate a resized image for this stored_file.

param: int|null $width The desired width, or null to only use the height.
param: int|null $height The desired height, or null to only use the width.
return: string|false False when a problem occurs, else the image data.

compare_to_path($path)   X-Ref
Check whether the supplied file is the same as this file.

param: string $path The path to the file on disk
return: boolean

compare_to_string($content)   X-Ref
Check whether the supplied content is the same as this file.

param: string $content The file content
return: boolean

rotate_image()   X-Ref
Generate a rotated image for this stored_file based on exif information.

return: array|false False when a problem occurs, else the image data and image size.