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