Merge branch 'MOODLE_23_STABLE' into install_23_STABLE
[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'),
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             )
58         );
59     }
61     /**
62      * Return moodle files listing
63      *
64      * @param int $contextid context id
65      * @param int $component component
66      * @param int $filearea file aera
67      * @param int $itemid item id
68      * @param string $filepath file path
69      * @param string $filename file name
70      * @param int $modified timestamp to return files changed after this time.
71      * @return array
72      * @since Moodle 2.2
73      */
74     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename, $modified = null) {
75         global $CFG, $USER, $OUTPUT;
76         $fileinfo = self::validate_parameters(self::get_files_parameters(), array(
77                     'contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea,
78                     'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename, 'modified'=>$modified));
80         $browser = get_file_browser();
82         if (empty($fileinfo['contextid'])) {
83             $context  = get_system_context();
84         } else {
85             $context  = get_context_instance_by_id($fileinfo['contextid']);
86         }
87         if (empty($fileinfo['component'])) {
88             $fileinfo['component'] = null;
89         }
90         if (empty($fileinfo['filearea'])) {
91             $fileinfo['filearea'] = null;
92         }
93         if (empty($fileinfo['itemid'])) {
94             $fileinfo['itemid'] = null;
95         }
96         if (empty($fileinfo['filename'])) {
97             $fileinfo['filename'] = null;
98         }
99         if (empty($fileinfo['filepath'])) {
100             $fileinfo['filepath'] = null;
101         }
103         $return = array();
104         $return['parents'] = array();
105         $return['files'] = array();
106         $list = array();
107         if ($file = $browser->get_file_info(
108             $context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'],
109                 $fileinfo['filepath'], $fileinfo['filename'])) {
110             $level = $file->get_parent();
111             while ($level) {
112                 $params = $level->get_params();
113                 $params['filename'] = $level->get_visible_name();
114                 array_unshift($return['parents'], $params);
115                 $level = $level->get_parent();
116             }
117             $children = $file->get_children();
118             foreach ($children as $child) {
120                 $params = $child->get_params();
121                 $timemodified = $child->get_timemodified();
123                 if ($child->is_directory()) {
124                     if ((is_null($modified)) or ($modified < $timemodified)) {
125                         $node = array(
126                             'contextid' => $params['contextid'],
127                             'component' => $params['component'],
128                             'filearea'  => $params['filearea'],
129                             'itemid'    => $params['itemid'],
130                             'filepath'  => $params['filepath'],
131                             'filename'  => $child->get_visible_name(),
132                             'url'       => null,
133                             'isdir'     => true,
134                             'timemodified' => $timemodified
135                            );
136                            $list[] = $node;
137                     }
138                 } else {
139                     if ((is_null($modified)) or ($modified < $timemodified)) {
140                         $node = array(
141                             'contextid' => $params['contextid'],
142                             'component' => $params['component'],
143                             'filearea'  => $params['filearea'],
144                             'itemid'    => $params['itemid'],
145                             'filepath'  => $params['filepath'],
146                             'filename'  => $child->get_visible_name(),
147                             'url'       => $child->get_url(),
148                             'isdir'     => false,
149                             'timemodified' => $timemodified
150                         );
151                            $list[] = $node;
152                     }
153                 }
154             }
155         }
156         $return['files'] = $list;
157         return $return;
158     }
160     /**
161      * Returns description of get_files returns
162      *
163      * @return external_single_structure
164      * @since Moodle 2.2
165      */
166     public static function get_files_returns() {
167         return new external_single_structure(
168             array(
169                 'parents' => new external_multiple_structure(
170                     new external_single_structure(
171                         array(
172                             'contextid' => new external_value(PARAM_INT, ''),
173                             'component' => new external_value(PARAM_COMPONENT, ''),
174                             'filearea'  => new external_value(PARAM_AREA, ''),
175                             'itemid'    => new external_value(PARAM_INT, ''),
176                             'filepath'  => new external_value(PARAM_TEXT, ''),
177                             'filename'  => new external_value(PARAM_TEXT, ''),
178                         )
179                     )
180                 ),
181                 'files' => new external_multiple_structure(
182                     new external_single_structure(
183                         array(
184                             'contextid' => new external_value(PARAM_INT, ''),
185                             'component' => new external_value(PARAM_COMPONENT, ''),
186                             'filearea'  => new external_value(PARAM_AREA, ''),
187                             'itemid'   => new external_value(PARAM_INT, ''),
188                             'filepath' => new external_value(PARAM_TEXT, ''),
189                             'filename' => new external_value(PARAM_FILE, ''),
190                             'isdir'    => new external_value(PARAM_BOOL, ''),
191                             'url'      => new external_value(PARAM_TEXT, ''),
192                             'timemodified' => new external_value(PARAM_INT, ''),
193                         )
194                     )
195                 )
196             )
197         );
198     }
200     /**
201      * Returns description of upload parameters
202      *
203      * @return external_function_parameters
204      * @since Moodle 2.2
205      */
206     public static function upload_parameters() {
207         return new external_function_parameters(
208             array(
209                 'contextid' => new external_value(PARAM_INT, 'context id'),
210                 'component' => new external_value(PARAM_COMPONENT, 'component'),
211                 'filearea'  => new external_value(PARAM_AREA, 'file area'),
212                 'itemid'    => new external_value(PARAM_INT, 'associated id'),
213                 'filepath'  => new external_value(PARAM_PATH, 'file path'),
214                 'filename'  => new external_value(PARAM_FILE, 'file name'),
215                 'filecontent' => new external_value(PARAM_TEXT, 'file content')
216             )
217         );
218     }
220     /**
221      * Uploading a file to moodle
222      *
223      * @param int $contextid context id
224      * @param string $component component
225      * @param string $filearea file aera
226      * @param int $itemid item id
227      * @param string $filepath file path
228      * @param string $filename file name
229      * @param string $filecontent file content
230      * @return array
231      * @since Moodle 2.2
232      */
233     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
234         global $USER, $CFG;
236         $fileinfo = self::validate_parameters(self::upload_parameters(), array(
237             'contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid,
238             'filepath'=>$filepath, 'filename'=>$filename, 'filecontent'=>$filecontent));
240         if (!isset($fileinfo['filecontent'])) {
241             throw new moodle_exception('nofile');
242         }
243         // Saving file.
244         $dir = make_temp_directory('wsupload');
246         if (empty($fileinfo['filename'])) {
247             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
248         } else {
249             $filename = $fileinfo['filename'];
250         }
252         if (file_exists($dir.$filename)) {
253             $savedfilepath = $dir.uniqid('m').$filename;
254         } else {
255             $savedfilepath = $dir.$filename;
256         }
258         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
259         unset($fileinfo['filecontent']);
261         if (!empty($fileinfo['filepath'])) {
262             $filepath = $fileinfo['filepath'];
263         } else {
264             $filepath = '/';
265         }
267         if (isset($fileinfo['itemid'])) {
268             // TODO MDL-31116 in user private area, itemid is always 0.
269             $itemid = 0;
270         } else {
271             throw new coding_exception('itemid cannot be empty');
272         }
274         if (!empty($fileinfo['contextid'])) {
275             $context = get_context_instance_by_id($fileinfo['contextid']);
276         } else {
277             $context = get_system_context();
278         }
280         if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
281             throw new coding_exception('File can be uploaded to user private area only');
282         } else {
283             // TODO MDL-31116 hard-coded to use user_private area.
284             $component = 'user';
285             $filearea = 'private';
286         }
288         $browser = get_file_browser();
290         // Check existing file.
291         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
292             throw new moodle_exception('fileexist');
293         }
295         // Move file to filepool.
296         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
297             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
298             $params = $info->get_params();
299             unlink($savedfilepath);
300             return array(
301                 'contextid'=>$params['contextid'],
302                 'component'=>$params['component'],
303                 'filearea'=>$params['filearea'],
304                 'itemid'=>$params['itemid'],
305                 'filepath'=>$params['filepath'],
306                 'filename'=>$params['filename'],
307                 'url'=>$info->get_url()
308                 );
309         } else {
310             throw new moodle_exception('nofile');
311         }
312     }
314     /**
315      * Returns description of upload returns
316      *
317      * @return external_single_structure
318      * @since Moodle 2.2
319      */
320     public static function upload_returns() {
321         return new external_single_structure(
322              array(
323                  'contextid' => new external_value(PARAM_INT, ''),
324                  'component' => new external_value(PARAM_COMPONENT, ''),
325                  'filearea'  => new external_value(PARAM_AREA, ''),
326                  'itemid'   => new external_value(PARAM_INT, ''),
327                  'filepath' => new external_value(PARAM_TEXT, ''),
328                  'filename' => new external_value(PARAM_FILE, ''),
329                  'url'      => new external_value(PARAM_TEXT, ''),
330              )
331         );
332     }
335 /**
336  * Deprecated files external functions
337  *
338  * @package    core_files
339  * @copyright  2010 Dongsheng Cai
340  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
341  * @since Moodle 2.0
342  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
343  * @todo MDL-31194 This will be deleted in Moodle 2.5.
344  * @see core_files_external
345  */
346 class moodle_file_external extends external_api {
348     /**
349      * Returns description of get_files parameters
350      *
351      * @return external_function_parameters
352      * @since Moodle 2.0
353      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
354      * @todo MDL-31194 This will be deleted in Moodle 2.5.
355      * @see core_files_external::get_files_parameters()
356      */
357     public static function get_files_parameters() {
358         return core_files_external::get_files_parameters();
359     }
361     /**
362      * Return moodle files listing
363      *
364      * @param int $contextid
365      * @param int $component
366      * @param int $filearea
367      * @param int $itemid
368      * @param string $filepath
369      * @param string $filename
370      * @return array
371      * @since Moodle 2.0
372      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
373      * @todo MDL-31194 This will be deleted in Moodle 2.5.
374      * @see core_files_external::get_files()
375      */
376     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
377         return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
378     }
380     /**
381      * Returns description of get_files returns
382      *
383      * @return external_single_structure
384      * @since Moodle 2.0
385      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
386      * @todo MDL-31194 This will be deleted in Moodle 2.5.
387      * @see core_files_external::get_files_returns()
388      */
389     public static function get_files_returns() {
390         return core_files_external::get_files_returns();
391     }
393     /**
394      * Returns description of upload parameters
395      *
396      * @return external_function_parameters
397      * @since Moodle 2.0
398      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
399      * @todo MDL-31194 This will be deleted in Moodle 2.5.
400      * @see core_files_external::upload_parameters()
401      */
402     public static function upload_parameters() {
403         return core_files_external::upload_parameters();
404     }
406     /**
407      * Uploading a file to moodle
408      *
409      * @param int $contextid
410      * @param string $component
411      * @param string $filearea
412      * @param int $itemid
413      * @param string $filepath
414      * @param string $filename
415      * @param string $filecontent
416      * @return array
417      * @since Moodle 2.0
418      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
419      * @todo MDL-31194 This will be deleted in Moodle 2.5.
420      * @see core_files_external::upload()
421      */
422     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
423         return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
424     }
426     /**
427      * Returns description of upload returns
428      *
429      * @return external_single_structure
430      * @since Moodle 2.0
431      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
432      * @todo MDL-31194 This will be deleted in Moodle 2.5.
433      * @see core_files_external::upload_returns()
434      */
435     public static function upload_returns() {
436         return core_files_external::upload_returns();
437     }