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/>.
  16
  17
  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  */
  26
  27 require_once("$CFG->libdir/externallib.php");
  28 require_once("$CFG->libdir/filelib.php");
  29
  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 {
  40
  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     }
  60
  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));
  79
  80         $browser = get_file_browser();
  81
  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         }
 102
 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) {
 119
 120                 $params = $child->get_params();
 121                 $timemodified = $child->get_timemodified();
 122
 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     }
 159
 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     }
 199
 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     }
 223
 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;
 241
 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));
 246
 247         if (!isset($fileinfo['filecontent'])) {
 248             throw new moodle_exception('nofile');
 249         }
 250         // Saving file.
 251         $dir = make_temp_directory('wsupload');
 252
 253         if (empty($fileinfo['filename'])) {
 254             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
 255         } else {
 256             $filename = $fileinfo['filename'];
 257         }
 258
 259         if (file_exists($dir.$filename)) {
 260             $savedfilepath = $dir.uniqid('m').$filename;
 261         } else {
 262             $savedfilepath = $dir.$filename;
 263         }
 264
 265         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
 266         unset($fileinfo['filecontent']);
 267
 268         if (!empty($fileinfo['filepath'])) {
 269             $filepath = $fileinfo['filepath'];
 270         } else {
 271             $filepath = '/';
 272         }
 273
 274         if (isset($fileinfo['itemid'])) {
 275             // TODO MDL-31116 in user private area, itemid is always 0.
 276             $itemid = 0;
 277         } else {
 278             throw new coding_exception('itemid cannot be empty');
 279         }
 280
 281         // We need to preserve backword compatibility. Context id is no more a required.
 282         if (empty($fileinfo['contextid'])) {
 283             unset($fileinfo['contextid']);
 284         }
 285
 286         // Get and validate context.
 287         $context = self::get_context_from_params($fileinfo);
 288         self::validate_context($context);
 289
 290         if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
 291             throw new coding_exception('File can be uploaded to user private area only');
 292         } else {
 293             // TODO MDL-31116 hard-coded to use user_private area.
 294             $component = 'user';
 295             $filearea = 'private';
 296         }
 297
 298         $browser = get_file_browser();
 299
 300         // Check existing file.
 301         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
 302             throw new moodle_exception('fileexist');
 303         }
 304
 305         // Move file to filepool.
 306         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
 307             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
 308             $params = $info->get_params();
 309             unlink($savedfilepath);
 310             return array(
 311                 'contextid'=>$params['contextid'],
 312                 'component'=>$params['component'],
 313                 'filearea'=>$params['filearea'],
 314                 'itemid'=>$params['itemid'],
 315                 'filepath'=>$params['filepath'],
 316                 'filename'=>$params['filename'],
 317                 'url'=>$info->get_url()
 318                 );
 319         } else {
 320             throw new moodle_exception('nofile');
 321         }
 322     }
 323
 324     /**
 325      * Returns description of upload returns
 326      *
 327      * @return external_single_structure
 328      * @since Moodle 2.2
 329      */
 330     public static function upload_returns() {
 331         return new external_single_structure(
 332              array(
 333                  'contextid' => new external_value(PARAM_INT, ''),
 334                  'component' => new external_value(PARAM_COMPONENT, ''),
 335                  'filearea'  => new external_value(PARAM_AREA, ''),
 336                  'itemid'   => new external_value(PARAM_INT, ''),
 337                  'filepath' => new external_value(PARAM_TEXT, ''),
 338                  'filename' => new external_value(PARAM_FILE, ''),
 339                  'url'      => new external_value(PARAM_TEXT, ''),
 340              )
 341         );
 342     }
 343 }
 344
 345 /**
 346  * Deprecated files external functions
 347  *
 348  * @package    core_files
 349  * @copyright  2010 Dongsheng Cai
 350  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 351  * @since Moodle 2.0
 352  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 353  * @see core_files_external
 354  */
 355 class moodle_file_external extends external_api {
 356
 357     /**
 358      * Returns description of get_files parameters
 359      *
 360      * @return external_function_parameters
 361      * @since Moodle 2.0
 362      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 363      * @see core_files_external::get_files_parameters()
 364      */
 365     public static function get_files_parameters() {
 366         return core_files_external::get_files_parameters();
 367     }
 368
 369     /**
 370      * Return moodle files listing
 371      *
 372      * @param int $contextid
 373      * @param int $component
 374      * @param int $filearea
 375      * @param int $itemid
 376      * @param string $filepath
 377      * @param string $filename
 378      * @return array
 379      * @since Moodle 2.0
 380      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 381      * @see core_files_external::get_files()
 382      */
 383     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
 384         return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
 385     }
 386
 387     /**
 388      * Returns description of get_files returns
 389      *
 390      * @return external_single_structure
 391      * @since Moodle 2.0
 392      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 393      * @see core_files_external::get_files_returns()
 394      */
 395     public static function get_files_returns() {
 396         return core_files_external::get_files_returns();
 397     }
 398
 399     /**
 400      * Returns description of upload parameters
 401      *
 402      * @return external_function_parameters
 403      * @since Moodle 2.0
 404      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 405      * @see core_files_external::upload_parameters()
 406      */
 407     public static function upload_parameters() {
 408         return core_files_external::upload_parameters();
 409     }
 410
 411     /**
 412      * Uploading a file to moodle
 413      *
 414      * @param int $contextid
 415      * @param string $component
 416      * @param string $filearea
 417      * @param int $itemid
 418      * @param string $filepath
 419      * @param string $filename
 420      * @param string $filecontent
 421      * @return array
 422      * @since Moodle 2.0
 423      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 424      * @see core_files_external::upload()
 425      */
 426     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
 427         return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
 428     }
 429
 430     /**
 431      * Returns description of upload returns
 432      *
 433      * @return external_single_structure
 434      * @since Moodle 2.0
 435      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 436      * @see core_files_external::upload_returns()
 437      */
 438     public static function upload_returns() {
 439         return core_files_external::upload_returns();
 440     }
 441 }