Merge branch 'wip-MDL-40038-master' of git://github.com/abgreeve/moodle
[moodle.git] / files / externallib.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  * External files API
20  *
21  * @package    core_files
22  * @category   external
23  * @copyright  2010 Dongsheng Cai
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 require_once("$CFG->libdir/externallib.php");
28 require_once("$CFG->libdir/filelib.php");
30 /**
31  * Files external functions
32  *
33  * @package    core_files
34  * @category   external
35  * @copyright  2011 Jerome Mouneyrac
36  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37  * @since Moodle 2.2
38  */
39 class core_files_external extends external_api {
41     /**
42      * Returns description of get_files parameters
43      *
44      * @return external_function_parameters
45      * @since Moodle 2.2
46      */
47     public static function get_files_parameters() {
48         return new external_function_parameters(
49             array(
50                 'contextid'    => new external_value(PARAM_INT, 'context id Set to -1 to use contextlevel and instanceid.'),
51                 'component'    => new external_value(PARAM_TEXT, 'component'),
52                 'filearea'     => new external_value(PARAM_TEXT, 'file area'),
53                 'itemid'       => new external_value(PARAM_INT, 'associated id'),
54                 'filepath'     => new external_value(PARAM_PATH, 'file path'),
55                 'filename'     => new external_value(PARAM_FILE, 'file name'),
56                 'modified'     => new external_value(PARAM_INT, 'timestamp to return files changed after this time.', VALUE_DEFAULT, null),
57                 'contextlevel' => new external_value(PARAM_ALPHA, 'The context level for the file location.', VALUE_DEFAULT, null),
58                 'instanceid'   => new external_value(PARAM_INT, 'The instance id for where the file is located.', VALUE_DEFAULT, null)
60             )
61         );
62     }
64     /**
65      * Return moodle files listing
66      *
67      * @param int $contextid context id
68      * @param int $component component
69      * @param int $filearea file area
70      * @param int $itemid item id
71      * @param string $filepath file path
72      * @param string $filename file name
73      * @param int $modified timestamp to return files changed after this time.
74      * @param string $contextlevel The context level for the file location.
75      * @param int $instanceid The instance id for where the file is located.
76      * @return array
77      * @since Moodle 2.2
78      */
79     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename, $modified = null,
80                                      $contextlevel = null, $instanceid = null) {
82         $parameters = array(
83             'contextid'    => $contextid,
84             'component'    => $component,
85             'filearea'     => $filearea,
86             'itemid'       => $itemid,
87             'filepath'     => $filepath,
88             'filename'     => $filename,
89             'modified'     => $modified,
90             'contextlevel' => $contextlevel,
91             'instanceid'   => $instanceid);
92         $fileinfo = self::validate_parameters(self::get_files_parameters(), $parameters);
94         $browser = get_file_browser();
96         // We need to preserve backwards compatibility. Zero will use the system context and minus one will
97         // use the addtional parameters to determine the context.
98         // TODO MDL-40489 get_context_from_params should handle this logic.
99         if ($fileinfo['contextid'] == 0) {
100             $context = context_system::instance();
101         } else {
102             if ($fileinfo['contextid'] == -1) {
103                 $fileinfo['contextid'] = null;
104             }
105             $context = self::get_context_from_params($fileinfo);
106         }
107         self::validate_context($context);
109         if (empty($fileinfo['component'])) {
110             $fileinfo['component'] = null;
111         }
112         if (empty($fileinfo['filearea'])) {
113             $fileinfo['filearea'] = null;
114         }
115         if (empty($fileinfo['itemid'])) {
116             $fileinfo['itemid'] = null;
117         }
118         if (empty($fileinfo['filename'])) {
119             $fileinfo['filename'] = null;
120         }
121         if (empty($fileinfo['filepath'])) {
122             $fileinfo['filepath'] = null;
123         }
125         $return = array();
126         $return['parents'] = array();
127         $return['files'] = array();
128         $list = array();
130         if ($file = $browser->get_file_info(
131             $context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'],
132                 $fileinfo['filepath'], $fileinfo['filename'])) {
133             $level = $file->get_parent();
134             while ($level) {
135                 $params = $level->get_params();
136                 $params['filename'] = $level->get_visible_name();
137                 array_unshift($return['parents'], $params);
138                 $level = $level->get_parent();
139             }
140             $children = $file->get_children();
141             foreach ($children as $child) {
143                 $params = $child->get_params();
144                 $timemodified = $child->get_timemodified();
146                 if ($child->is_directory()) {
147                     if ((is_null($modified)) or ($modified < $timemodified)) {
148                         $node = array(
149                             'contextid' => $params['contextid'],
150                             'component' => $params['component'],
151                             'filearea'  => $params['filearea'],
152                             'itemid'    => $params['itemid'],
153                             'filepath'  => $params['filepath'],
154                             'filename'  => $child->get_visible_name(),
155                             'url'       => null,
156                             'isdir'     => true,
157                             'timemodified' => $timemodified
158                            );
159                            $list[] = $node;
160                     }
161                 } else {
162                     if ((is_null($modified)) or ($modified < $timemodified)) {
163                         $node = array(
164                             'contextid' => $params['contextid'],
165                             'component' => $params['component'],
166                             'filearea'  => $params['filearea'],
167                             'itemid'    => $params['itemid'],
168                             'filepath'  => $params['filepath'],
169                             'filename'  => $child->get_visible_name(),
170                             'url'       => $child->get_url(),
171                             'isdir'     => false,
172                             'timemodified' => $timemodified
173                         );
174                            $list[] = $node;
175                     }
176                 }
177             }
178         }
179         $return['files'] = $list;
180         return $return;
181     }
183     /**
184      * Returns description of get_files returns
185      *
186      * @return external_single_structure
187      * @since Moodle 2.2
188      */
189     public static function get_files_returns() {
190         return new external_single_structure(
191             array(
192                 'parents' => new external_multiple_structure(
193                     new external_single_structure(
194                         array(
195                             'contextid' => new external_value(PARAM_INT, ''),
196                             'component' => new external_value(PARAM_COMPONENT, ''),
197                             'filearea'  => new external_value(PARAM_AREA, ''),
198                             'itemid'    => new external_value(PARAM_INT, ''),
199                             'filepath'  => new external_value(PARAM_TEXT, ''),
200                             'filename'  => new external_value(PARAM_TEXT, ''),
201                         )
202                     )
203                 ),
204                 'files' => new external_multiple_structure(
205                     new external_single_structure(
206                         array(
207                             'contextid' => new external_value(PARAM_INT, ''),
208                             'component' => new external_value(PARAM_COMPONENT, ''),
209                             'filearea'  => new external_value(PARAM_AREA, ''),
210                             'itemid'   => new external_value(PARAM_INT, ''),
211                             'filepath' => new external_value(PARAM_TEXT, ''),
212                             'filename' => new external_value(PARAM_FILE, ''),
213                             'isdir'    => new external_value(PARAM_BOOL, ''),
214                             'url'      => new external_value(PARAM_TEXT, ''),
215                             'timemodified' => new external_value(PARAM_INT, ''),
216                         )
217                     )
218                 )
219             )
220         );
221     }
223     /**
224      * Returns description of upload parameters
225      *
226      * @return external_function_parameters
227      * @since Moodle 2.2
228      */
229     public static function upload_parameters() {
230         return new external_function_parameters(
231             array(
232                 'contextid' => new external_value(PARAM_INT, 'context id', VALUE_DEFAULT, null),
233                 'component' => new external_value(PARAM_COMPONENT, 'component'),
234                 'filearea'  => new external_value(PARAM_AREA, 'file area'),
235                 'itemid'    => new external_value(PARAM_INT, 'associated id'),
236                 'filepath'  => new external_value(PARAM_PATH, 'file path'),
237                 'filename'  => new external_value(PARAM_FILE, 'file name'),
238                 'filecontent' => new external_value(PARAM_TEXT, 'file content'),
239                 'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to put the file in,
240                         (block, course, coursecat, system, user, module)', VALUE_DEFAULT, null),
241                 'instanceid' => new external_value(PARAM_INT, 'The Instance id of item associated
242                          with the context level', VALUE_DEFAULT, null)
243             )
244         );
245     }
247     /**
248      * Uploading a file to moodle
249      *
250      * @param int    $contextid    context id
251      * @param string $component    component
252      * @param string $filearea     file area
253      * @param int    $itemid       item id
254      * @param string $filepath     file path
255      * @param string $filename     file name
256      * @param string $filecontent  file content
257      * @param string $contextlevel Context level (block, course, coursecat, system, user or module)
258      * @param int    $instanceid   Instance id of the item associated with the context level
259      * @return array
260      * @since Moodle 2.2
261      */
262     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent, $contextlevel, $instanceid) {
263         global $USER, $CFG;
265         $fileinfo = self::validate_parameters(self::upload_parameters(), array(
266                 'contextid' => $contextid, 'component' => $component, 'filearea' => $filearea, 'itemid' => $itemid,
267                 'filepath' => $filepath, 'filename' => $filename, 'filecontent' => $filecontent, 'contextlevel' => $contextlevel,
268                 'instanceid' => $instanceid));
270         if (!isset($fileinfo['filecontent'])) {
271             throw new moodle_exception('nofile');
272         }
273         // Saving file.
274         $dir = make_temp_directory('wsupload');
276         if (empty($fileinfo['filename'])) {
277             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
278         } else {
279             $filename = $fileinfo['filename'];
280         }
282         if (file_exists($dir.$filename)) {
283             $savedfilepath = $dir.uniqid('m').$filename;
284         } else {
285             $savedfilepath = $dir.$filename;
286         }
288         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
289         @chmod($savedfilepath, $CFG->filepermissions);
290         unset($fileinfo['filecontent']);
292         if (!empty($fileinfo['filepath'])) {
293             $filepath = $fileinfo['filepath'];
294         } else {
295             $filepath = '/';
296         }
298         // Only allow uploads to draft or private areas (private is deprecated but still supported)
299         if (!($fileinfo['component'] == 'user' and in_array($fileinfo['filearea'], array('private', 'draft')))) {
300             throw new coding_exception('File can be uploaded to user private or draft areas only');
301         } else {
302             $component = 'user';
303             $filearea = $fileinfo['filearea'];
304         }
306         $itemid = 0;
307         if (isset($fileinfo['itemid'])) {
308             $itemid = $fileinfo['itemid'];
309         }
310         if ($filearea == 'draft' && $itemid <= 0) {
311             // Generate a draft area for the files.
312             $itemid = file_get_unused_draft_itemid();
313         } else if ($filearea == 'private') {
314             // TODO MDL-31116 in user private area, itemid is always 0.
315             $itemid = 0;
316         }
318         // We need to preserve backword compatibility. Context id is no more a required.
319         if (empty($fileinfo['contextid'])) {
320             unset($fileinfo['contextid']);
321         }
323         // Get and validate context.
324         $context = self::get_context_from_params($fileinfo);
325         self::validate_context($context);
326         if (($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
327             debugging('Uploading directly to user private files area is deprecated. Upload to a draft area and then move the files with core_user::add_user_private_files');
328         }
330         $browser = get_file_browser();
332         // Check existing file.
333         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
334             throw new moodle_exception('fileexist');
335         }
337         // Move file to filepool.
338         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
339             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
340             $params = $info->get_params();
341             unlink($savedfilepath);
342             return array(
343                 'contextid'=>$params['contextid'],
344                 'component'=>$params['component'],
345                 'filearea'=>$params['filearea'],
346                 'itemid'=>$params['itemid'],
347                 'filepath'=>$params['filepath'],
348                 'filename'=>$params['filename'],
349                 'url'=>$info->get_url()
350                 );
351         } else {
352             throw new moodle_exception('nofile');
353         }
354     }
356     /**
357      * Returns description of upload returns
358      *
359      * @return external_single_structure
360      * @since Moodle 2.2
361      */
362     public static function upload_returns() {
363         return new external_single_structure(
364              array(
365                  'contextid' => new external_value(PARAM_INT, ''),
366                  'component' => new external_value(PARAM_COMPONENT, ''),
367                  'filearea'  => new external_value(PARAM_AREA, ''),
368                  'itemid'   => new external_value(PARAM_INT, ''),
369                  'filepath' => new external_value(PARAM_TEXT, ''),
370                  'filename' => new external_value(PARAM_FILE, ''),
371                  'url'      => new external_value(PARAM_TEXT, ''),
372              )
373         );
374     }
377 /**
378  * Deprecated files external functions
379  *
380  * @package    core_files
381  * @copyright  2010 Dongsheng Cai
382  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
383  * @since Moodle 2.0
384  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
385  * @see core_files_external
386  */
387 class moodle_file_external extends external_api {
389     /**
390      * Returns description of get_files parameters
391      *
392      * @return external_function_parameters
393      * @since Moodle 2.0
394      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
395      * @see core_files_external::get_files_parameters()
396      */
397     public static function get_files_parameters() {
398         return core_files_external::get_files_parameters();
399     }
401     /**
402      * Return moodle files listing
403      *
404      * @param int $contextid
405      * @param int $component
406      * @param int $filearea
407      * @param int $itemid
408      * @param string $filepath
409      * @param string $filename
410      * @return array
411      * @since Moodle 2.0
412      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
413      * @see core_files_external::get_files()
414      */
415     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
416         return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
417     }
419     /**
420      * Returns description of get_files returns
421      *
422      * @return external_single_structure
423      * @since Moodle 2.0
424      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
425      * @see core_files_external::get_files_returns()
426      */
427     public static function get_files_returns() {
428         return core_files_external::get_files_returns();
429     }
431     /**
432      * Returns description of upload parameters
433      *
434      * @return external_function_parameters
435      * @since Moodle 2.0
436      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
437      * @see core_files_external::upload_parameters()
438      */
439     public static function upload_parameters() {
440         return core_files_external::upload_parameters();
441     }
443     /**
444      * Uploading a file to moodle
445      *
446      * @param int $contextid
447      * @param string $component
448      * @param string $filearea
449      * @param int $itemid
450      * @param string $filepath
451      * @param string $filename
452      * @param string $filecontent
453      * @return array
454      * @since Moodle 2.0
455      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
456      * @see core_files_external::upload()
457      */
458     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
459         return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
460     }
462     /**
463      * Returns description of upload returns
464      *
465      * @return external_single_structure
466      * @since Moodle 2.0
467      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
468      * @see core_files_external::upload_returns()
469      */
470     public static function upload_returns() {
471         return core_files_external::upload_returns();
472     }