Merge branch 'w33_MDL-41112_m26_cachedist' of https://github.com/skodak/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'),
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 area
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  = context_system::instance();
84         } else {
85             $context  = 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', VALUE_DEFAULT, null),
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                 'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to put the file in,
217                         (block, course, coursecat, system, user, module)', VALUE_DEFAULT, null),
218                 'instanceid' => new external_value(PARAM_INT, 'The Instance id of item associated
219                          with the context level', VALUE_DEFAULT, null)
220             )
221         );
222     }
224     /**
225      * Uploading a file to moodle
226      *
227      * @param int    $contextid    context id
228      * @param string $component    component
229      * @param string $filearea     file area
230      * @param int    $itemid       item id
231      * @param string $filepath     file path
232      * @param string $filename     file name
233      * @param string $filecontent  file content
234      * @param string $contextlevel Context level (block, course, coursecat, system, user or module)
235      * @param int    $instanceid   Instance id of the item associated with the context level
236      * @return array
237      * @since Moodle 2.2
238      */
239     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent, $contextlevel, $instanceid) {
240         global $USER, $CFG;
242         $fileinfo = self::validate_parameters(self::upload_parameters(), array(
243                 'contextid' => $contextid, 'component' => $component, 'filearea' => $filearea, 'itemid' => $itemid,
244                 'filepath' => $filepath, 'filename' => $filename, 'filecontent' => $filecontent, 'contextlevel' => $contextlevel,
245                 'instanceid' => $instanceid));
247         if (!isset($fileinfo['filecontent'])) {
248             throw new moodle_exception('nofile');
249         }
250         // Saving file.
251         $dir = make_temp_directory('wsupload');
253         if (empty($fileinfo['filename'])) {
254             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
255         } else {
256             $filename = $fileinfo['filename'];
257         }
259         if (file_exists($dir.$filename)) {
260             $savedfilepath = $dir.uniqid('m').$filename;
261         } else {
262             $savedfilepath = $dir.$filename;
263         }
265         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
266         @chmod($savedfilepath, $CFG->filepermissions);
267         unset($fileinfo['filecontent']);
269         if (!empty($fileinfo['filepath'])) {
270             $filepath = $fileinfo['filepath'];
271         } else {
272             $filepath = '/';
273         }
275         // Only allow uploads to draft or private areas (private is deprecated but still supported)
276         if (!($fileinfo['component'] == 'user' and in_array($fileinfo['filearea'], array('private', 'draft')))) {
277             throw new coding_exception('File can be uploaded to user private or draft areas only');
278         } else {
279             $component = 'user';
280             $filearea = $fileinfo['filearea'];
281         }
283         $itemid = 0;
284         if (isset($fileinfo['itemid'])) {
285             $itemid = $fileinfo['itemid'];
286         }
287         if ($filearea == 'draft' && $itemid <= 0) {
288             // Generate a draft area for the files.
289             $itemid = file_get_unused_draft_itemid();
290         } else if ($filearea == 'private') {
291             // TODO MDL-31116 in user private area, itemid is always 0.
292             $itemid = 0;
293         }
295         // We need to preserve backword compatibility. Context id is no more a required.
296         if (empty($fileinfo['contextid'])) {
297             unset($fileinfo['contextid']);
298         }
300         // Get and validate context.
301         $context = self::get_context_from_params($fileinfo);
302         self::validate_context($context);
303         if (($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
304             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');
305         }
307         $browser = get_file_browser();
309         // Check existing file.
310         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
311             throw new moodle_exception('fileexist');
312         }
314         // Move file to filepool.
315         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
316             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
317             $params = $info->get_params();
318             unlink($savedfilepath);
319             return array(
320                 'contextid'=>$params['contextid'],
321                 'component'=>$params['component'],
322                 'filearea'=>$params['filearea'],
323                 'itemid'=>$params['itemid'],
324                 'filepath'=>$params['filepath'],
325                 'filename'=>$params['filename'],
326                 'url'=>$info->get_url()
327                 );
328         } else {
329             throw new moodle_exception('nofile');
330         }
331     }
333     /**
334      * Returns description of upload returns
335      *
336      * @return external_single_structure
337      * @since Moodle 2.2
338      */
339     public static function upload_returns() {
340         return new external_single_structure(
341              array(
342                  'contextid' => new external_value(PARAM_INT, ''),
343                  'component' => new external_value(PARAM_COMPONENT, ''),
344                  'filearea'  => new external_value(PARAM_AREA, ''),
345                  'itemid'   => new external_value(PARAM_INT, ''),
346                  'filepath' => new external_value(PARAM_TEXT, ''),
347                  'filename' => new external_value(PARAM_FILE, ''),
348                  'url'      => new external_value(PARAM_TEXT, ''),
349              )
350         );
351     }
354 /**
355  * Deprecated files external functions
356  *
357  * @package    core_files
358  * @copyright  2010 Dongsheng Cai
359  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
360  * @since Moodle 2.0
361  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
362  * @see core_files_external
363  */
364 class moodle_file_external extends external_api {
366     /**
367      * Returns description of get_files parameters
368      *
369      * @return external_function_parameters
370      * @since Moodle 2.0
371      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
372      * @see core_files_external::get_files_parameters()
373      */
374     public static function get_files_parameters() {
375         return core_files_external::get_files_parameters();
376     }
378     /**
379      * Return moodle files listing
380      *
381      * @param int $contextid
382      * @param int $component
383      * @param int $filearea
384      * @param int $itemid
385      * @param string $filepath
386      * @param string $filename
387      * @return array
388      * @since Moodle 2.0
389      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
390      * @see core_files_external::get_files()
391      */
392     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
393         return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
394     }
396     /**
397      * Returns description of get_files returns
398      *
399      * @return external_single_structure
400      * @since Moodle 2.0
401      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
402      * @see core_files_external::get_files_returns()
403      */
404     public static function get_files_returns() {
405         return core_files_external::get_files_returns();
406     }
408     /**
409      * Returns description of upload parameters
410      *
411      * @return external_function_parameters
412      * @since Moodle 2.0
413      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
414      * @see core_files_external::upload_parameters()
415      */
416     public static function upload_parameters() {
417         return core_files_external::upload_parameters();
418     }
420     /**
421      * Uploading a file to moodle
422      *
423      * @param int $contextid
424      * @param string $component
425      * @param string $filearea
426      * @param int $itemid
427      * @param string $filepath
428      * @param string $filename
429      * @param string $filecontent
430      * @return array
431      * @since Moodle 2.0
432      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
433      * @see core_files_external::upload()
434      */
435     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
436         return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
437     }
439     /**
440      * Returns description of upload returns
441      *
442      * @return external_single_structure
443      * @since Moodle 2.0
444      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
445      * @see core_files_external::upload_returns()
446      */
447     public static function upload_returns() {
448         return core_files_external::upload_returns();
449     }