f1c3f759f03aa78e459a225b972445a25301a888
[moodle.git] / lib / filestorage / stored_file.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * Definition of a class stored_file.
20  *
21  * @package   core_files
22  * @copyright 2008 Petr Skoda {@link http://skodak.org}
23  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 defined('MOODLE_INTERNAL') || die();
28 require_once($CFG->dirroot . '/lib/filestorage/file_progress.php');
29 require_once($CFG->dirroot . '/lib/filestorage/file_system.php');
31 /**
32  * Class representing local files stored in a sha1 file pool.
33  *
34  * Since Moodle 2.0 file contents are stored in sha1 pool and
35  * all other file information is stored in new "files" database table.
36  *
37  * @package   core_files
38  * @category  files
39  * @copyright 2008 Petr Skoda {@link http://skodak.org}
40  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41  * @since     Moodle 2.0
42  */
43 class stored_file {
44     /** @var file_storage file storage pool instance */
45     private $fs;
46     /** @var stdClass record from the files table left join files_reference table */
47     private $file_record;
48     /** @var repository repository plugin instance */
49     private $repository;
50     /** @var file_system filesystem instance */
51     private $filesystem;
53     /**
54      * @var int Indicates a file handle of the type returned by fopen.
55      */
56     const FILE_HANDLE_FOPEN = 0;
58     /**
59      * @var int Indicates a file handle of the type returned by gzopen.
60      */
61     const FILE_HANDLE_GZOPEN = 1;
64     /**
65      * Constructor, this constructor should be called ONLY from the file_storage class!
66      *
67      * @param file_storage $fs file  storage instance
68      * @param stdClass $file_record description of file
69      * @param string $deprecated
70      */
71     public function __construct(file_storage $fs, stdClass $file_record, $deprecated = null) {
72         global $DB, $CFG;
73         $this->fs          = $fs;
74         $this->file_record = clone($file_record); // prevent modifications
76         if (!empty($file_record->repositoryid)) {
77             require_once("$CFG->dirroot/repository/lib.php");
78             $this->repository = repository::get_repository_by_id($file_record->repositoryid, SYSCONTEXTID);
79             if ($this->repository->supported_returntypes() & FILE_REFERENCE != FILE_REFERENCE) {
80                 // Repository cannot do file reference.
81                 throw new moodle_exception('error');
82             }
83         } else {
84             $this->repository = null;
85         }
86         // make sure all reference fields exist in file_record even when it is not a reference
87         foreach (array('referencelastsync', 'referencefileid', 'reference', 'repositoryid') as $key) {
88             if (empty($this->file_record->$key)) {
89                 $this->file_record->$key = null;
90             }
91         }
93         $this->filesystem = $fs->get_file_system();
94     }
96     /**
97      * Magic method, called during serialization.
98      *
99      * @return array
100      */
101     public function __sleep() {
102         // We only ever want the file_record saved, not the file_storage object.
103         return ['file_record'];
104     }
106     /**
107      * Magic method, called during unserialization.
108      */
109     public function __wakeup() {
110         // Recreate our stored_file based on the file_record, and using file storage retrieved the correct way.
111         $this->__construct(get_file_storage(), $this->file_record);
112     }
114     /**
115      * Whether or not this is a external resource
116      *
117      * @return bool
118      */
119     public function is_external_file() {
120         return !empty($this->repository);
121     }
123     /**
124      * Whether or not this is a controlled link. Note that repositories cannot support FILE_REFERENCE and FILE_CONTROLLED_LINK.
125      *
126      * @return bool
127      */
128     public function is_controlled_link() {
129         return $this->is_external_file() && $this->repository->supported_returntypes() & FILE_CONTROLLED_LINK;
130     }
132     /**
133      * Update some file record fields
134      * NOTE: Must remain protected
135      *
136      * @param stdClass $dataobject
137      */
138     protected function update($dataobject) {
139         global $DB;
140         $updatereferencesneeded = false;
141         $updatemimetype = false;
142         $keys = array_keys((array)$this->file_record);
143         $filepreupdate = clone($this->file_record);
144         foreach ($dataobject as $field => $value) {
145             if (in_array($field, $keys)) {
146                 if ($field == 'contextid' and (!is_number($value) or $value < 1)) {
147                     throw new file_exception('storedfileproblem', 'Invalid contextid');
148                 }
150                 if ($field == 'component') {
151                     $value = clean_param($value, PARAM_COMPONENT);
152                     if (empty($value)) {
153                         throw new file_exception('storedfileproblem', 'Invalid component');
154                     }
155                 }
157                 if ($field == 'filearea') {
158                     $value = clean_param($value, PARAM_AREA);
159                     if (empty($value)) {
160                         throw new file_exception('storedfileproblem', 'Invalid filearea');
161                     }
162                 }
164                 if ($field == 'itemid' and (!is_number($value) or $value < 0)) {
165                     throw new file_exception('storedfileproblem', 'Invalid itemid');
166                 }
169                 if ($field == 'filepath') {
170                     $value = clean_param($value, PARAM_PATH);
171                     if (strpos($value, '/') !== 0 or strrpos($value, '/') !== strlen($value)-1) {
172                         // path must start and end with '/'
173                         throw new file_exception('storedfileproblem', 'Invalid file path');
174                     }
175                 }
177                 if ($field == 'filename') {
178                     // folder has filename == '.', so we pass this
179                     if ($value != '.') {
180                         $value = clean_param($value, PARAM_FILE);
181                     }
182                     if ($value === '') {
183                         throw new file_exception('storedfileproblem', 'Invalid file name');
184                     }
185                 }
187                 if ($field === 'timecreated' or $field === 'timemodified') {
188                     if (!is_number($value)) {
189                         throw new file_exception('storedfileproblem', 'Invalid timestamp');
190                     }
191                     if ($value < 0) {
192                         $value = 0;
193                     }
194                 }
196                 if ($field === 'referencefileid') {
197                     if (!is_null($value) and !is_number($value)) {
198                         throw new file_exception('storedfileproblem', 'Invalid reference info');
199                     }
200                 }
202                 if (($field == 'contenthash' || $field == 'filesize') && $this->file_record->$field != $value) {
203                     $updatereferencesneeded = true;
204                 }
206                 if ($updatereferencesneeded || ($field === 'filename' && $this->file_record->filename != $value)) {
207                     $updatemimetype = true;
208                 }
210                 // adding the field
211                 $this->file_record->$field = $value;
212             } else {
213                 throw new coding_exception("Invalid field name, $field doesn't exist in file record");
214             }
215         }
216         // Validate mimetype field
217         if ($updatemimetype) {
218             $mimetype = $this->filesystem->mimetype_from_storedfile($this);
219             $this->file_record->mimetype = $mimetype;
220         }
222         $DB->update_record('files', $this->file_record);
223         if ($updatereferencesneeded) {
224             // Either filesize or contenthash of this file have changed. Update all files that reference to it.
225             $this->fs->update_references_to_storedfile($this);
226         }
228         // Callback for file update.
229         if (!$this->is_directory()) {
230             if ($pluginsfunction = get_plugins_with_function('after_file_updated')) {
231                 foreach ($pluginsfunction as $plugintype => $plugins) {
232                     foreach ($plugins as $pluginfunction) {
233                         $pluginfunction($this->file_record, $filepreupdate);
234                     }
235                 }
236             }
237         }
238     }
240     /**
241      * Rename filename
242      *
243      * @param string $filepath file path
244      * @param string $filename file name
245      */
246     public function rename($filepath, $filename) {
247         if ($this->fs->file_exists($this->get_contextid(), $this->get_component(), $this->get_filearea(), $this->get_itemid(), $filepath, $filename)) {
248             $a = new stdClass();
249             $a->contextid = $this->get_contextid();
250             $a->component = $this->get_component();
251             $a->filearea  = $this->get_filearea();
252             $a->itemid    = $this->get_itemid();
253             $a->filepath  = $filepath;
254             $a->filename  = $filename;
255             throw new file_exception('storedfilenotcreated', $a, 'file exists, cannot rename');
256         }
257         $filerecord = new stdClass;
258         $filerecord->filepath = $filepath;
259         $filerecord->filename = $filename;
260         // populate the pathname hash
261         $filerecord->pathnamehash = $this->fs->get_pathname_hash($this->file_record->contextid, $this->file_record->component, $this->file_record->filearea, $this->file_record->itemid, $filepath, $filename);
262         $this->update($filerecord);
263     }
265     /**
266      * Function stored_file::replace_content_with() is deprecated. Please use stored_file::replace_file_with()
267      *
268      * @deprecated since Moodle 2.6 MDL-42016 - please do not use this function any more.
269      * @see stored_file::replace_file_with()
270      */
271     public function replace_content_with(stored_file $storedfile) {
272         throw new coding_exception('Function stored_file::replace_content_with() can not be used any more . ' .
273             'Please use stored_file::replace_file_with()');
274     }
276     /**
277      * Replaces the fields that might have changed when file was overriden in filepicker:
278      * reference, contenthash, filesize, userid
279      *
280      * Note that field 'source' must be updated separately because
281      * it has different format for draft and non-draft areas and
282      * this function will usually be used to replace non-draft area
283      * file with draft area file.
284      *
285      * @param stored_file $newfile
286      * @throws coding_exception
287      */
288     public function replace_file_with(stored_file $newfile) {
289         if ($newfile->get_referencefileid() &&
290                 $this->fs->get_references_count_by_storedfile($this)) {
291             // The new file is a reference.
292             // The current file has other local files referencing to it.
293             // Double reference is not allowed.
294             throw new moodle_exception('errordoublereference', 'repository');
295         }
297         $filerecord = new stdClass;
298         if ($this->filesystem->is_file_readable_remotely_by_storedfile($newfile)) {
299             $contenthash = $newfile->get_contenthash();
300             $filerecord->contenthash = $contenthash;
301         } else {
302             throw new file_exception('storedfileproblem', 'Invalid contenthash, content must be already in filepool', $contenthash);
303         }
304         $filerecord->filesize = $newfile->get_filesize();
305         $filerecord->referencefileid = $newfile->get_referencefileid();
306         $filerecord->userid = $newfile->get_userid();
307         $oldcontenthash = $this->get_contenthash();
308         $this->update($filerecord);
309         $this->filesystem->remove_file($oldcontenthash);
310     }
312     /**
313      * Unlink the stored file from the referenced file
314      *
315      * This methods destroys the link to the record in files_reference table. This effectively
316      * turns the stored file from being an alias to a plain copy. However, the caller has
317      * to make sure that the actual file's content has beed synced prior to calling this method.
318      */
319     public function delete_reference() {
320         global $DB;
322         if (!$this->is_external_file()) {
323             throw new coding_exception('An attempt to unlink a non-reference file.');
324         }
326         $transaction = $DB->start_delegated_transaction();
328         // Are we the only one referring to the original file? If so, delete the
329         // referenced file record. Note we do not use file_storage::search_references_count()
330         // here because we want to count draft files too and we are at a bit lower access level here.
331         $countlinks = $DB->count_records('files',
332             array('referencefileid' => $this->file_record->referencefileid));
333         if ($countlinks == 1) {
334             $DB->delete_records('files_reference', array('id' => $this->file_record->referencefileid));
335         }
337         // Update the underlying record in the database.
338         $update = new stdClass();
339         $update->referencefileid = null;
340         $this->update($update);
342         $transaction->allow_commit();
344         // Update our properties and the record in the memory.
345         $this->repository = null;
346         $this->file_record->repositoryid = null;
347         $this->file_record->reference = null;
348         $this->file_record->referencefileid = null;
349         $this->file_record->referencelastsync = null;
350     }
352     /**
353      * Is this a directory?
354      *
355      * Directories are only emulated, internally they are stored as empty
356      * files with a "." instead of name - this means empty directory contains
357      * exactly one empty file with name dot.
358      *
359      * @return bool true means directory, false means file
360      */
361     public function is_directory() {
362         return ($this->file_record->filename === '.');
363     }
365     /**
366      * Delete file from files table.
367      *
368      * The content of files stored in sha1 pool is reclaimed
369      * later - the occupied disk space is reclaimed much later.
370      *
371      * @return bool always true or exception if error occurred
372      */
373     public function delete() {
374         global $DB;
376         if ($this->is_directory()) {
377             // Directories can not be referenced, just delete the record.
378             $DB->delete_records('files', array('id'=>$this->file_record->id));
380         } else {
381             $transaction = $DB->start_delegated_transaction();
383             // If there are other files referring to this file, convert them to copies.
384             if ($files = $this->fs->get_references_by_storedfile($this)) {
385                 foreach ($files as $file) {
386                     $this->fs->import_external_file($file);
387                 }
388             }
390             // If this file is a reference (alias) to another file, unlink it first.
391             if ($this->is_external_file()) {
392                 $this->delete_reference();
393             }
395             // Now delete the file record.
396             $DB->delete_records('files', array('id'=>$this->file_record->id));
398             $transaction->allow_commit();
400             if (!$this->is_directory()) {
401                 // Callback for file deletion.
402                 if ($pluginsfunction = get_plugins_with_function('after_file_deleted')) {
403                     foreach ($pluginsfunction as $plugintype => $plugins) {
404                         foreach ($plugins as $pluginfunction) {
405                             $pluginfunction($this->file_record);
406                         }
407                     }
408                 }
409             }
410         }
412         // Move pool file to trash if content not needed any more.
413         $this->filesystem->remove_file($this->file_record->contenthash);
414         return true; // BC only
415     }
417     /**
418     * adds this file path to a curl request (POST only)
419     *
420     * @param curl $curlrequest the curl request object
421     * @param string $key what key to use in the POST request
422     * @return void
423     */
424     public function add_to_curl_request(&$curlrequest, $key) {
425         return $this->filesystem->add_to_curl_request($this, $curlrequest, $key);
426     }
428     /**
429      * Returns file handle - read only mode, no writing allowed into pool files!
430      *
431      * When you want to modify a file, create a new file and delete the old one.
432      *
433      * @param int $type Type of file handle (FILE_HANDLE_xx constant)
434      * @return resource file handle
435      */
436     public function get_content_file_handle($type = self::FILE_HANDLE_FOPEN) {
437         return $this->filesystem->get_content_file_handle($this, $type);
438     }
440     /**
441      * Dumps file content to page.
442      */
443     public function readfile() {
444         return $this->filesystem->readfile($this);
445     }
447     /**
448      * Returns file content as string.
449      *
450      * @return string content
451      */
452     public function get_content() {
453         return $this->filesystem->get_content($this);
454     }
456     /**
457      * Copy content of file to given pathname.
458      *
459      * @param string $pathname real path to the new file
460      * @return bool success
461      */
462     public function copy_content_to($pathname) {
463         return $this->filesystem->copy_content_from_storedfile($this, $pathname);
464     }
466     /**
467      * Copy content of file to temporary folder and returns file path
468      *
469      * @param string $dir name of the temporary directory
470      * @param string $fileprefix prefix of temporary file.
471      * @return string|bool path of temporary file or false.
472      */
473     public function copy_content_to_temp($dir = 'files', $fileprefix = 'tempup_') {
474         $tempfile = false;
475         if (!$dir = make_temp_directory($dir)) {
476             return false;
477         }
478         if (!$tempfile = tempnam($dir, $fileprefix)) {
479             return false;
480         }
481         if (!$this->copy_content_to($tempfile)) {
482             // something went wrong
483             @unlink($tempfile);
484             return false;
485         }
486         return $tempfile;
487     }
489     /**
490      * List contents of archive.
491      *
492      * @param file_packer $packer file packer instance
493      * @return array of file infos
494      */
495     public function list_files(file_packer $packer) {
496         return $this->filesystem->list_files($this, $packer);
497     }
499     /**
500      * Extract file to given file path (real OS filesystem), existing files are overwritten.
501      *
502      * @param file_packer $packer file packer instance
503      * @param string $pathname target directory
504      * @param file_progress $progress Progress indicator callback or null if not required
505      * @return array|bool list of processed files; false if error
506      */
507     public function extract_to_pathname(file_packer $packer, $pathname,
508             file_progress $progress = null) {
509         return $this->filesystem->extract_to_pathname($this, $packer, $pathname, $progress);
510     }
512     /**
513      * Extract file to given file path (real OS filesystem), existing files are overwritten.
514      *
515      * @param file_packer $packer file packer instance
516      * @param int $contextid context ID
517      * @param string $component component
518      * @param string $filearea file area
519      * @param int $itemid item ID
520      * @param string $pathbase path base
521      * @param int $userid user ID
522      * @param file_progress $progress Progress indicator callback or null if not required
523      * @return array|bool list of processed files; false if error
524      */
525     public function extract_to_storage(file_packer $packer, $contextid,
526             $component, $filearea, $itemid, $pathbase, $userid = null, file_progress $progress = null) {
528         return $this->filesystem->extract_to_storage($this, $packer, $contextid, $component, $filearea,
529                 $itemid, $pathbase, $userid, $progress);
530     }
532     /**
533      * Add file/directory into archive.
534      *
535      * @param file_archive $filearch file archive instance
536      * @param string $archivepath pathname in archive
537      * @return bool success
538      */
539     public function archive_file(file_archive $filearch, $archivepath) {
540         if ($this->repository) {
541             $this->sync_external_file();
542             if ($this->compare_to_string('')) {
543                 // This file is not stored locally - attempt to retrieve it from the repository.
544                 // This may happen if the repository deliberately does not fetch files, or if there is a failure with the sync.
545                 $fileinfo = $this->repository->get_file($this->get_reference());
546                 if (isset($fileinfo['path'])) {
547                     return $filearch->add_file_from_pathname($archivepath, $fileinfo['path']);
548                 }
549             }
550         }
552         return $this->filesystem->add_storedfile_to_archive($this, $filearch, $archivepath);
553     }
555     /**
556      * Returns information about image,
557      * information is determined from the file content
558      *
559      * @return mixed array with width, height and mimetype; false if not an image
560      */
561     public function get_imageinfo() {
562         return $this->filesystem->get_imageinfo($this);
563     }
565     /**
566      * Verifies the file is a valid web image - gif, png and jpeg only.
567      *
568      * It should be ok to serve this image from server without any other security workarounds.
569      *
570      * @return bool true if file ok
571      */
572     public function is_valid_image() {
573         $mimetype = $this->get_mimetype();
574         if (!file_mimetype_in_typegroup($mimetype, 'web_image')) {
575             return false;
576         }
577         if (!$info = $this->get_imageinfo()) {
578             return false;
579         }
580         if ($info['mimetype'] !== $mimetype) {
581             return false;
582         }
583         // ok, GD likes this image
584         return true;
585     }
587     /**
588      * Returns parent directory, creates missing parents if needed.
589      *
590      * @return stored_file
591      */
592     public function get_parent_directory() {
593         if ($this->file_record->filepath === '/' and $this->file_record->filename === '.') {
594             //root dir does not have parent
595             return null;
596         }
598         if ($this->file_record->filename !== '.') {
599             return $this->fs->create_directory($this->file_record->contextid, $this->file_record->component, $this->file_record->filearea, $this->file_record->itemid, $this->file_record->filepath);
600         }
602         $filepath = $this->file_record->filepath;
603         $filepath = trim($filepath, '/');
604         $dirs = explode('/', $filepath);
605         array_pop($dirs);
606         $filepath = implode('/', $dirs);
607         $filepath = ($filepath === '') ? '/' : "/$filepath/";
609         return $this->fs->create_directory($this->file_record->contextid, $this->file_record->component, $this->file_record->filearea, $this->file_record->itemid, $filepath);
610     }
612     /**
613      * Set synchronised content from file.
614      *
615      * @param string $path Path to the file.
616      */
617     public function set_synchronised_content_from_file($path) {
618         $this->fs->synchronise_stored_file_from_file($this, $path, $this->file_record);
619     }
621     /**
622      * Set synchronised content from content.
623      *
624      * @param string $content File content.
625      */
626     public function set_synchronised_content_from_string($content) {
627         $this->fs->synchronise_stored_file_from_string($this, $content, $this->file_record);
628     }
630     /**
631      * Synchronize file if it is a reference and needs synchronizing
632      *
633      * Updates contenthash and filesize
634      */
635     public function sync_external_file() {
636         if (!empty($this->repository)) {
637             $this->repository->sync_reference($this);
638         }
639     }
641     /**
642      * Returns context id of the file
643      *
644      * @return int context id
645      */
646     public function get_contextid() {
647         return $this->file_record->contextid;
648     }
650     /**
651      * Returns component name - this is the owner of the areas,
652      * nothing else is allowed to read or modify the files directly!!
653      *
654      * @return string
655      */
656     public function get_component() {
657         return $this->file_record->component;
658     }
660     /**
661      * Returns file area name, this divides files of one component into groups with different access control.
662      * All files in one area have the same access control.
663      *
664      * @return string
665      */
666     public function get_filearea() {
667         return $this->file_record->filearea;
668     }
670     /**
671      * Returns returns item id of file.
672      *
673      * @return int
674      */
675     public function get_itemid() {
676         return $this->file_record->itemid;
677     }
679     /**
680      * Returns file path - starts and ends with /, \ are not allowed.
681      *
682      * @return string
683      */
684     public function get_filepath() {
685         return $this->file_record->filepath;
686     }
688     /**
689      * Returns file name or '.' in case of directories.
690      *
691      * @return string
692      */
693     public function get_filename() {
694         return $this->file_record->filename;
695     }
697     /**
698      * Returns id of user who created the file.
699      *
700      * @return int
701      */
702     public function get_userid() {
703         return $this->file_record->userid;
704     }
706     /**
707      * Returns the size of file in bytes.
708      *
709      * @return int bytes
710      */
711     public function get_filesize() {
712         $this->sync_external_file();
713         return $this->file_record->filesize;
714     }
716      /**
717      * Function stored_file::set_filesize() is deprecated. Please use stored_file::replace_file_with
718      *
719      * @deprecated since Moodle 2.6 MDL-42016 - please do not use this function any more.
720      * @see stored_file::replace_file_with()
721      */
722     public function set_filesize($filesize) {
723         throw new coding_exception('Function stored_file::set_filesize() can not be used any more. ' .
724             'Please use stored_file::replace_file_with()');
725     }
727     /**
728      * Returns mime type of file.
729      *
730      * @return string
731      */
732     public function get_mimetype() {
733         return $this->file_record->mimetype;
734     }
736     /**
737      * Returns unix timestamp of file creation date.
738      *
739      * @return int
740      */
741     public function get_timecreated() {
742         return $this->file_record->timecreated;
743     }
745     /**
746      * Returns unix timestamp of last file modification.
747      *
748      * @return int
749      */
750     public function get_timemodified() {
751         $this->sync_external_file();
752         return $this->file_record->timemodified;
753     }
755     /**
756      * set timemodified
757      *
758      * @param int $timemodified
759      */
760     public function set_timemodified($timemodified) {
761         $filerecord = new stdClass;
762         $filerecord->timemodified = $timemodified;
763         $this->update($filerecord);
764     }
766     /**
767      * Returns file status flag.
768      *
769      * @return int 0 means file OK, anything else is a problem and file can not be used
770      */
771     public function get_status() {
772         return $this->file_record->status;
773     }
775     /**
776      * Returns file id.
777      *
778      * @return int
779      */
780     public function get_id() {
781         return $this->file_record->id;
782     }
784     /**
785      * Returns sha1 hash of file content.
786      *
787      * @return string
788      */
789     public function get_contenthash() {
790         $this->sync_external_file();
791         return $this->file_record->contenthash;
792     }
794     /**
795      * Returns sha1 hash of all file path components sha1("contextid/component/filearea/itemid/dir/dir/filename.ext").
796      *
797      * @return string
798      */
799     public function get_pathnamehash() {
800         return $this->file_record->pathnamehash;
801     }
803     /**
804      * Returns the license type of the file, it is a short name referred from license table.
805      *
806      * @return string
807      */
808     public function get_license() {
809         return $this->file_record->license;
810     }
812     /**
813      * Set license
814      *
815      * @param string $license license
816      */
817     public function set_license($license) {
818         $filerecord = new stdClass;
819         $filerecord->license = $license;
820         $this->update($filerecord);
821     }
823     /**
824      * Returns the author name of the file.
825      *
826      * @return string
827      */
828     public function get_author() {
829         return $this->file_record->author;
830     }
832     /**
833      * Set author
834      *
835      * @param string $author
836      */
837     public function set_author($author) {
838         $filerecord = new stdClass;
839         $filerecord->author = $author;
840         $this->update($filerecord);
841     }
843     /**
844      * Returns the source of the file, usually it is a url.
845      *
846      * @return string
847      */
848     public function get_source() {
849         return $this->file_record->source;
850     }
852     /**
853      * Set license
854      *
855      * @param string $license license
856      */
857     public function set_source($source) {
858         $filerecord = new stdClass;
859         $filerecord->source = $source;
860         $this->update($filerecord);
861     }
864     /**
865      * Returns the sort order of file
866      *
867      * @return int
868      */
869     public function get_sortorder() {
870         return $this->file_record->sortorder;
871     }
873     /**
874      * Set file sort order
875      *
876      * @param int $sortorder
877      * @return int
878      */
879     public function set_sortorder($sortorder) {
880         $oldorder = $this->file_record->sortorder;
881         $filerecord = new stdClass;
882         $filerecord->sortorder = $sortorder;
883         $this->update($filerecord);
884         if (!$this->is_directory()) {
885             // Callback for file sort order change.
886             if ($pluginsfunction = get_plugins_with_function('after_file_sorted')) {
887                 foreach ($pluginsfunction as $plugintype => $plugins) {
888                     foreach ($plugins as $pluginfunction) {
889                         $pluginfunction($this->file_record, $oldorder, $sortorder);
890                     }
891                 }
892             }
893         }
894     }
896     /**
897      * Returns repository id
898      *
899      * @return int|null
900      */
901     public function get_repository_id() {
902         if (!empty($this->repository)) {
903             return $this->repository->id;
904         } else {
905             return null;
906         }
907     }
909     /**
910      * Returns repository type.
911      *
912      * @return mixed str|null the repository type or null if is not an external file
913      * @since  Moodle 3.3
914      */
915     public function get_repository_type() {
917         if (!empty($this->repository)) {
918             return $this->repository->get_typename();
919         } else {
920             return null;
921         }
922     }
925     /**
926      * get reference file id
927      * @return int
928      */
929     public function get_referencefileid() {
930         return $this->file_record->referencefileid;
931     }
933     /**
934      * Get reference last sync time
935      * @return int
936      */
937     public function get_referencelastsync() {
938         return $this->file_record->referencelastsync;
939     }
941     /**
942      * Function stored_file::get_referencelifetime() is deprecated as reference
943      * life time is no longer stored in DB or returned by repository. Each
944      * repository should decide by itself when to synchronise the references.
945      *
946      * @deprecated since Moodle 2.6 MDL-42016 - please do not use this function any more.
947      * @see repository::sync_reference()
948      */
949     public function get_referencelifetime() {
950         throw new coding_exception('Function stored_file::get_referencelifetime() can not be used any more. ' .
951             'See repository::sync_reference().');
952     }
953     /**
954      * Returns file reference
955      *
956      * @return string
957      */
958     public function get_reference() {
959         return $this->file_record->reference;
960     }
962     /**
963      * Get human readable file reference information
964      *
965      * @return string
966      */
967     public function get_reference_details() {
968         return $this->repository->get_reference_details($this->get_reference(), $this->get_status());
969     }
971     /**
972      * Called after reference-file has been synchronized with the repository
973      *
974      * We update contenthash, filesize and status in files table if changed
975      * and we always update lastsync in files_reference table
976      *
977      * @param null|string $contenthash if set to null contenthash is not changed
978      * @param int $filesize new size of the file
979      * @param int $status new status of the file (0 means OK, 666 - source missing)
980      * @param int $timemodified last time modified of the source, if known
981      */
982     public function set_synchronized($contenthash, $filesize, $status = 0, $timemodified = null) {
983         if (!$this->is_external_file()) {
984             return;
985         }
986         $now = time();
987         if ($contenthash === null) {
988             $contenthash = $this->file_record->contenthash;
989         }
990         if ($contenthash != $this->file_record->contenthash) {
991             $oldcontenthash = $this->file_record->contenthash;
992         }
993         // this will update all entries in {files} that have the same filereference id
994         $this->fs->update_references($this->file_record->referencefileid, $now, null, $contenthash, $filesize, $status, $timemodified);
995         // we don't need to call update() for this object, just set the values of changed fields
996         $this->file_record->contenthash = $contenthash;
997         $this->file_record->filesize = $filesize;
998         $this->file_record->status = $status;
999         $this->file_record->referencelastsync = $now;
1000         if ($timemodified) {
1001             $this->file_record->timemodified = $timemodified;
1002         }
1003         if (isset($oldcontenthash)) {
1004             $this->filesystem->remove_file($oldcontenthash);
1005         }
1006     }
1008     /**
1009      * Sets the error status for a file that could not be synchronised
1010      */
1011     public function set_missingsource() {
1012         $this->set_synchronized($this->file_record->contenthash, $this->file_record->filesize, 666);
1013     }
1015     /**
1016      * Send file references
1017      *
1018      * @param int $lifetime Number of seconds before the file should expire from caches (default 24 hours)
1019      * @param int $filter 0 (default)=no filtering, 1=all files, 2=html files only
1020      * @param bool $forcedownload If true (default false), forces download of file rather than view in browser/plugin
1021      * @param array $options additional options affecting the file serving
1022      */
1023     public function send_file($lifetime, $filter, $forcedownload, $options) {
1024         $this->repository->send_file($this, $lifetime, $filter, $forcedownload, $options);
1025     }
1027     /**
1028      * Imports the contents of an external file into moodle filepool.
1029      *
1030      * @throws moodle_exception if file could not be downloaded or is too big
1031      * @param int $maxbytes throw an exception if file size is bigger than $maxbytes (0 means no limit)
1032      */
1033     public function import_external_file_contents($maxbytes = 0) {
1034         if ($this->repository) {
1035             $this->repository->import_external_file_contents($this, $maxbytes);
1036         }
1037     }
1039     /**
1040      * Gets a file relative to this file in the repository and sends it to the browser.
1041      * Checks the function repository::supports_relative_file() to make sure it can be used.
1042      *
1043      * @param string $relativepath the relative path to the file we are trying to access
1044      */
1045     public function send_relative_file($relativepath) {
1046         if ($this->repository && $this->repository->supports_relative_file()) {
1047             $relativepath = clean_param($relativepath, PARAM_PATH);
1048             $this->repository->send_relative_file($this, $relativepath);
1049         } else {
1050             send_file_not_found();
1051         }
1052     }
1054     /**
1055      * Generates a thumbnail for this stored_file.
1056      *
1057      * If the GD library has at least version 2 and PNG support is available, the returned data
1058      * is the content of a transparent PNG file containing the thumbnail. Otherwise, the function
1059      * returns contents of a JPEG file with black background containing the thumbnail.
1060      *
1061      * @param   int $width the width of the requested thumbnail
1062      * @param   int $height the height of the requested thumbnail
1063      * @return  string|bool false if a problem occurs, the thumbnail image data otherwise
1064      */
1065     public function generate_image_thumbnail($width, $height) {
1066         global $CFG;
1067         require_once($CFG->libdir . '/gdlib.php');
1069         if (empty($width) or empty($height)) {
1070             return false;
1071         }
1073         $content = $this->get_content();
1075         // Fetch the image information for this image.
1076         $imageinfo = @getimagesizefromstring($content);
1077         if (empty($imageinfo)) {
1078             return false;
1079         }
1081         // Create a new image from the file.
1082         $original = @imagecreatefromstring($content);
1084         // Generate the thumbnail.
1085         return generate_image_thumbnail_from_image($original, $imageinfo, $width, $height);
1086     }
1088     /**
1089      * Generate a resized image for this stored_file.
1090      *
1091      * @param int|null $width The desired width, or null to only use the height.
1092      * @param int|null $height The desired height, or null to only use the width.
1093      * @return string|false False when a problem occurs, else the image data.
1094      */
1095     public function resize_image($width, $height) {
1096         global $CFG;
1097         require_once($CFG->libdir . '/gdlib.php');
1099         $content = $this->get_content();
1101         // Fetch the image information for this image.
1102         $imageinfo = @getimagesizefromstring($content);
1103         if (empty($imageinfo)) {
1104             return false;
1105         }
1107         // Create a new image from the file.
1108         $original = @imagecreatefromstring($content);
1110         // Generate the resized image.
1111         return resize_image_from_image($original, $imageinfo, $width, $height);
1112     }
1114     /**
1115      * Check whether the supplied file is the same as this file.
1116      *
1117      * @param   string $path The path to the file on disk
1118      * @return  boolean
1119      */
1120     public function compare_to_path($path) {
1121         return $this->get_contenthash() === file_storage::hash_from_path($path);
1122     }
1124     /**
1125      * Check whether the supplied content is the same as this file.
1126      *
1127      * @param   string $content The file content
1128      * @return  boolean
1129      */
1130     public function compare_to_string($content) {
1131         return $this->get_contenthash() === file_storage::hash_from_string($content);
1132     }