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.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

< /** < * Core file system class definition. < * < * @package core_files < * @copyright 2017 Andrew Nicols <andrew@nicols.co.uk> < * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later < */ < < defined('MOODLE_INTERNAL') || die();
> use Psr\Http\Message\StreamInterface;
/** * File system class used for low level access to real files in filedir. * * @package core_files * @category files * @copyright 2017 Andrew Nicols <andrew@nicols.co.uk> * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ abstract class file_system { /** * Output the content of the specified stored file. * * Note, this is different to get_content() as it uses the built-in php * readfile function which is more efficient. * * @param stored_file $file The file to serve. * @return void */ public function readfile(stored_file $file) { if ($this->is_file_readable_locally_by_storedfile($file, false)) { $path = $this->get_local_path_from_storedfile($file, false); } else { $path = $this->get_remote_path_from_storedfile($file); } if (readfile_allow_large($path, $file->get_filesize()) === false) { throw new file_exception('storedfilecannotreadfile', $file->get_filename()); } } /** * Get the full path on disk for the specified stored file. * * Note: This must return a consistent path for the file's contenthash * and the path _will_ be in a standard local format. * Streamable paths will not work. * A local copy of the file _will_ be fetched if $fetchifnotfound is tree. * * The $fetchifnotfound allows you to determine the expected path of the file. * * @param stored_file $file The file to serve. * @param bool $fetchifnotfound Whether to attempt to fetch from the remote path if not found. * @return string full path to pool file with file content */ public function get_local_path_from_storedfile(stored_file $file, $fetchifnotfound = false) { return $this->get_local_path_from_hash($file->get_contenthash(), $fetchifnotfound); } /** * Get a remote filepath for the specified stored file. * * This is typically either the same as the local filepath, or it is a streamable resource. * * See https://secure.php.net/manual/en/wrappers.php for further information on valid wrappers. * * @param stored_file $file The file to serve. * @return string full path to pool file with file content */ public function get_remote_path_from_storedfile(stored_file $file) { return $this->get_remote_path_from_hash($file->get_contenthash(), false); } /** * Get the full path for the specified hash, including the path to the filedir. * * Note: This must return a consistent path for the file's contenthash * and the path _will_ be in a standard local format. * Streamable paths will not work. * A local copy of the file _will_ be fetched if $fetchifnotfound is tree. * * The $fetchifnotfound allows you to determine the expected path of the file. * * @param string $contenthash The content hash * @param bool $fetchifnotfound Whether to attempt to fetch from the remote path if not found. * @return string The full path to the content file */ abstract protected function get_local_path_from_hash($contenthash, $fetchifnotfound = false); /** * Get the full path for the specified hash, including the path to the filedir. * * This is typically either the same as the local filepath, or it is a streamable resource. * * See https://secure.php.net/manual/en/wrappers.php for further information on valid wrappers. * * @param string $contenthash The content hash * @return string The full path to the content file */ abstract protected function get_remote_path_from_hash($contenthash); /** * Determine whether the file is present on the file system somewhere. * A local copy of the file _will_ be fetched if $fetchifnotfound is tree. * * The $fetchifnotfound allows you to determine the expected path of the file. * * @param stored_file $file The file to ensure is available. * @param bool $fetchifnotfound Whether to attempt to fetch from the remote path if not found. * @return bool */ public function is_file_readable_locally_by_storedfile(stored_file $file, $fetchifnotfound = false) { if (!$file->get_filesize()) { // Files with empty size are either directories or empty. // We handle these virtually. return true; } // Check to see if the file is currently readable. $path = $this->get_local_path_from_storedfile($file, $fetchifnotfound); if (is_readable($path)) { return true; } return false; } /** * Determine whether the file is present on the local file system somewhere. * * @param stored_file $file The file to ensure is available. * @return bool */ public function is_file_readable_remotely_by_storedfile(stored_file $file) { if (!$file->get_filesize()) { // Files with empty size are either directories or empty. // We handle these virtually. return true; } $path = $this->get_remote_path_from_storedfile($file, false); if (is_readable($path)) { return true; } return false; } /** * Determine whether the file is present on the file system somewhere given * the contenthash. * * @param string $contenthash The contenthash of the file to check. * @param bool $fetchifnotfound Whether to attempt to fetch from the remote path if not found. * @return bool */ public function is_file_readable_locally_by_hash($contenthash, $fetchifnotfound = false) { if ($contenthash === file_storage::hash_from_string('')) { // Files with empty size are either directories or empty. // We handle these virtually. return true; } // This is called by file_storage::content_exists(), and in turn by the repository system. $path = $this->get_local_path_from_hash($contenthash, $fetchifnotfound); // Note - it is not possible to perform a content recovery safely from a hash alone. return is_readable($path); } /** * Determine whether the file is present locally on the file system somewhere given * the contenthash. * * @param string $contenthash The contenthash of the file to check. * @return bool */ public function is_file_readable_remotely_by_hash($contenthash) { if ($contenthash === file_storage::hash_from_string('')) { // Files with empty size are either directories or empty. // We handle these virtually. return true; } $path = $this->get_remote_path_from_hash($contenthash, false); // Note - it is not possible to perform a content recovery safely from a hash alone. return is_readable($path); } /** * Copy content of file to given pathname. * * @param stored_file $file The file to be copied * @param string $target real path to the new file * @return bool success */ abstract public function copy_content_from_storedfile(stored_file $file, $target); /** * Remove the file with the specified contenthash. * * Note, if overriding this function, you _must_ check that the file is * no longer in use - see {check_file_usage}. * * DO NOT call directly - reserved for core!! * * @param string $contenthash */ abstract public function remove_file($contenthash); /** * Check whether a file is removable. * * This must be called prior to file removal. * * @param string $contenthash * @return bool */ protected static function is_file_removable($contenthash) { global $DB; if ($contenthash === file_storage::hash_from_string('')) { // No need to delete files without content. return false; } // Note: This section is critical - in theory file could be reused at the same time, if this // happens we can still recover the file from trash. // Technically this is the responsibility of the file_storage API, but as this method is public, we go belt-and-braces. if ($DB->record_exists('files', array('contenthash' => $contenthash))) { // File content is still used. return false; } return true; } /** * Get the content of the specified stored file. * * Generally you will probably want to use readfile() to serve content, * and where possible you should see if you can use * get_content_file_handle and work with the file stream instead. * * @param stored_file $file The file to retrieve * @return string The full file content */ public function get_content(stored_file $file) { if (!$file->get_filesize()) { // Directories are empty. Empty files are not worth fetching. return ''; } $source = $this->get_remote_path_from_storedfile($file); return file_get_contents($source); } /** * List contents of archive. * * @param stored_file $file The archive to inspect * @param file_packer $packer file packer instance * @return array of file infos */ public function list_files($file, file_packer $packer) { $archivefile = $this->get_local_path_from_storedfile($file, true); return $packer->list_files($archivefile); } /** * Extract file to given file path (real OS filesystem), existing files are overwritten. * * @param stored_file $file The archive to inspect * @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 */ public function extract_to_pathname(stored_file $file, file_packer $packer, $pathname, file_progress $progress = null) { $archivefile = $this->get_local_path_from_storedfile($file, true); return $packer->extract_to_pathname($archivefile, $pathname, null, $progress); } /** * Extract file to given file path (real OS filesystem), existing files are overwritten. * * @param stored_file $file The archive to inspect * @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 */ public function extract_to_storage(stored_file $file, file_packer $packer, $contextid, $component, $filearea, $itemid, $pathbase, $userid = null, file_progress $progress = null) { // Since we do not know which extractor we have, and whether it supports remote paths, use a local path here. $archivefile = $this->get_local_path_from_storedfile($file, true); return $packer->extract_to_storage($archivefile, $contextid, $component, $filearea, $itemid, $pathbase, $userid, $progress); } /** * Add file/directory into archive. * * @param stored_file $file The file to archive * @param file_archive $filearch file archive instance * @param string $archivepath pathname in archive * @return bool success */ public function add_storedfile_to_archive(stored_file $file, file_archive $filearch, $archivepath) { if ($file->is_directory()) { return $filearch->add_directory($archivepath); } else { // Since we do not know which extractor we have, and whether it supports remote paths, use a local path here. return $filearch->add_file_from_pathname($archivepath, $this->get_local_path_from_storedfile($file, true)); } } /** * Adds this file path to a curl request (POST only). * * @param stored_file $file The file to add to the curl request * @param curl $curlrequest The curl request object * @param string $key What key to use in the POST request * @return void * This needs the fullpath for the storedfile :/ * Can this be achieved in some other fashion? */ public function add_to_curl_request(stored_file $file, &$curlrequest, $key) { // Note: curl_file_create does not work with remote paths. $path = $this->get_local_path_from_storedfile($file, true); $curlrequest->_tmp_file_post_params[$key] = curl_file_create($path, null, $file->get_filename()); } /** * Returns information about image. * Information is determined from the file content * * @param stored_file $file The file to inspect * @return mixed array with width, height and mimetype; false if not an image */ public function get_imageinfo(stored_file $file) { if (!$this->is_image_from_storedfile($file)) { return false; } $hash = $file->get_contenthash(); $cache = cache::make('core', 'file_imageinfo'); $info = $cache->get($hash); if ($info !== false) { return $info; } // Whilst get_imageinfo_from_path can use remote paths, it must download the entire file first. // It is more efficient to use a local file when possible. $info = $this->get_imageinfo_from_path($this->get_local_path_from_storedfile($file, true)); $cache->set($hash, $info); return $info; } /** * Attempt to determine whether the specified file is likely to be an * image. * Since this relies upon the mimetype stored in the files table, there * may be times when this information is not 100% accurate. * * @param stored_file $file The file to check * @return bool */ public function is_image_from_storedfile(stored_file $file) { if (!$file->get_filesize()) { // An empty file cannot be an image. return false; } $mimetype = $file->get_mimetype(); if (!preg_match('|^image/|', $mimetype)) { // The mimetype does not include image. return false; } // If it looks like an image, and it smells like an image, perhaps it's an image! return true; } /** * Returns image information relating to the specified path or URL. * * @param string $path The full path of the image file. * @return array|bool array that containing width, height, and mimetype or false if cannot get the image info. */ protected function get_imageinfo_from_path($path) { $imagemimetype = file_storage::mimetype_from_file($path); $issvgimage = file_is_svg_image_from_mimetype($imagemimetype); if (!$issvgimage) { $imageinfo = getimagesize($path); if (!is_array($imageinfo)) { return false; // Nothing to process, the file was not recognised as image by GD. } $image = [ 'width' => $imageinfo[0], 'height' => $imageinfo[1], 'mimetype' => image_type_to_mime_type($imageinfo[2]), ]; } else { // Since SVG file is actually an XML file, GD cannot handle. $svgcontent = @simplexml_load_file($path); if (!$svgcontent) { // Cannot parse the file. return false; } $svgattrs = $svgcontent->attributes(); if (!empty($svgattrs->viewBox)) { // We have viewBox. $viewboxval = explode(' ', $svgattrs->viewBox); $width = intval($viewboxval[2]); $height = intval($viewboxval[3]); } else { // Get the width. if (!empty($svgattrs->width) && intval($svgattrs->width) > 0) { $width = intval($svgattrs->width); } else { // Default width. $width = 800; } // Get the height. if (!empty($svgattrs->height) && intval($svgattrs->height) > 0) { $height = intval($svgattrs->height); } else { // Default width. $height = 600; } } $image = [ 'width' => $width, 'height' => $height, 'mimetype' => $imagemimetype, ]; } if (empty($image['width']) or empty($image['height']) or empty($image['mimetype'])) { // GD can not parse it, sorry. return false; } return $image; } /** * Serve file content using X-Sendfile header. * Please make sure that all headers are already sent and the all * access control checks passed. * * This alternate method to xsendfile() allows an alternate file system * to use the full file metadata and avoid extra lookups. * * @param stored_file $file The file to send * @return bool success */ public function xsendfile_file(stored_file $file): bool { return $this->xsendfile($file->get_contenthash()); } /** * Serve file content using X-Sendfile header. * Please make sure that all headers are already sent and the all * access control checks passed. * * @param string $contenthash The content hash of the file to be served * @return bool success */ public function xsendfile($contenthash) { global $CFG; require_once($CFG->libdir . "/xsendfilelib.php"); return xsendfile($this->get_remote_path_from_hash($contenthash)); } /** * Returns true if filesystem is configured to support xsendfile. * * @return bool */ public function supports_xsendfile() { global $CFG; return !empty($CFG->xsendfile); } /** * Validate that the content hash matches the content hash of the file on disk. * * @param string $contenthash The current content hash to validate * @param string $pathname The path to the file on disk * @return array The content hash (it might change) and file size */ protected function validate_hash_and_file_size($contenthash, $pathname) { global $CFG; if (!is_readable($pathname)) { throw new file_exception('storedfilecannotread', '', $pathname); } $filesize = filesize($pathname); if ($filesize === false) { throw new file_exception('storedfilecannotread', '', $pathname); } if (is_null($contenthash)) { $contenthash = file_storage::hash_from_path($pathname); } else if ($CFG->debugdeveloper) { $filehash = file_storage::hash_from_path($pathname); if ($filehash === false) { throw new file_exception('storedfilecannotread', '', $pathname); } if ($filehash !== $contenthash) { // Hopefully this never happens, if yes we need to fix calling code. debugging("Invalid contenthash submitted for file $pathname", DEBUG_DEVELOPER); $contenthash = $filehash; } } if ($contenthash === false) { throw new file_exception('storedfilecannotread', '', $pathname); } if ($filesize > 0 and $contenthash === file_storage::hash_from_string('')) { // Did the file change or is file_storage::hash_from_path() borked for this file? clearstatcache(); $contenthash = file_storage::hash_from_path($pathname); $filesize = filesize($pathname); if ($contenthash === false or $filesize === false) { throw new file_exception('storedfilecannotread', '', $pathname); } if ($filesize > 0 and $contenthash === file_storage::hash_from_string('')) { // This is very weird... throw new file_exception('storedfilecannotread', '', $pathname); } } return [$contenthash, $filesize]; } /** * Add the supplied file to the file system. * * Note: If overriding this function, it is advisable to store the file * in the path returned by get_local_path_from_hash as there may be * subsequent uses of the file in the same request. * * @param string $pathname Path to file currently on disk * @param string $contenthash SHA1 hash of content if known (performance only) * @return array (contenthash, filesize, newfile) */ abstract public function add_file_from_path($pathname, $contenthash = null); /** * Add a file with the supplied content to the file system. * * Note: If overriding this function, it is advisable to store the file * in the path returned by get_local_path_from_hash as there may be * subsequent uses of the file in the same request. * * @param string $content file content - binary string * @return array (contenthash, filesize, newfile) */ abstract public function add_file_from_string($content); /** * 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 stored_file $file The file to retrieve a handle for * @param int $type Type of file handle (FILE_HANDLE_xx constant) * @return resource file handle */ public function get_content_file_handle(stored_file $file, $type = stored_file::FILE_HANDLE_FOPEN) { if ($type === stored_file::FILE_HANDLE_GZOPEN) { // Local file required for gzopen. $path = $this->get_local_path_from_storedfile($file, true); } else { $path = $this->get_remote_path_from_storedfile($file); } return self::get_file_handle_for_path($path, $type); } /** * Return a file handle for the specified path. * * This abstraction should be used when overriding get_content_file_handle in a new file system. * * @param string $path The path to the file. This shoudl be any type of path that fopen and gzopen accept. * @param int $type Type of file handle (FILE_HANDLE_xx constant) * @return resource * @throws coding_exception When an unexpected type of file handle is requested */ protected static function get_file_handle_for_path($path, $type = stored_file::FILE_HANDLE_FOPEN) { switch ($type) { case stored_file::FILE_HANDLE_FOPEN: // Binary reading. return fopen($path, 'rb'); case stored_file::FILE_HANDLE_GZOPEN: // Binary reading of file in gz format. return gzopen($path, 'rb'); default: throw new coding_exception('Unexpected file handle type'); }
> } } > > /** /** > * Get a PSR7 Stream for the specified file which implements the PSR Message StreamInterface. * Retrieve the mime information for the specified stored file. > * * > * @param stored_file $file * @param string $contenthash > * @return StreamInterface * @param string $filename > */ * @return string The MIME type. > public function get_psr_stream(stored_file $file): StreamInterface { */ > return \GuzzleHttp\Psr7\Utils::streamFor($this->get_content_file_handle($file));
public function mimetype_from_hash($contenthash, $filename) { $pathname = $this->get_local_path_from_hash($contenthash); $mimetype = file_storage::mimetype($pathname, $filename); if ($mimetype === 'document/unknown' && !$this->is_file_readable_locally_by_hash($contenthash)) { // The type is unknown, but the full checks weren't completed because the file isn't locally available. // Ensure we have a local copy and try again. $pathname = $this->get_local_path_from_hash($contenthash, true); $mimetype = file_storage::mimetype_from_file($pathname); } return $mimetype; } /** * Retrieve the mime information for the specified stored file. * * @param stored_file $file The stored file to retrieve mime information for * @return string The MIME type. */ public function mimetype_from_storedfile($file) { if (!$file->get_filesize()) { // Files with an empty filesize are treated as directories and have no mimetype. return null; } return $this->mimetype_from_hash($file->get_contenthash(), $file->get_filename()); } /** * Run any periodic tasks which must be performed. */ public function cron() { } }