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 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)
  59
  60             )
  61         );
  62     }
  63
  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) {
  81
  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);
  93
  94         $browser = get_file_browser();
  95
  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);
 108
 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         }
 124
 125         $return = array();
 126         $return['parents'] = array();
 127         $return['files'] = array();
 128         $list = array();
 129
 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) {
 142
 143                 $params = $child->get_params();
 144                 $timemodified = $child->get_timemodified();
 145
 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     }
 182
 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     }
 222
 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     }
 246
 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;
 264
 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));
 269
 270         if (!isset($fileinfo['filecontent'])) {
 271             throw new moodle_exception('nofile');
 272         }
 273         // Saving file.
 274         $dir = make_temp_directory('wsupload');
 275
 276         if (empty($fileinfo['filename'])) {
 277             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
 278         } else {
 279             $filename = $fileinfo['filename'];
 280         }
 281
 282         if (file_exists($dir.$filename)) {
 283             $savedfilepath = $dir.uniqid('m').$filename;
 284         } else {
 285             $savedfilepath = $dir.$filename;
 286         }
 287
 288         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
 289         @chmod($savedfilepath, $CFG->filepermissions);
 290         unset($fileinfo['filecontent']);
 291
 292         if (!empty($fileinfo['filepath'])) {
 293             $filepath = $fileinfo['filepath'];
 294         } else {
 295             $filepath = '/';
 296         }
 297
 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         }
 305
 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         }
 317
 318         // We need to preserve backword compatibility. Context id is no more a required.
 319         if (empty($fileinfo['contextid'])) {
 320             unset($fileinfo['contextid']);
 321         }
 322
 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         }
 329
 330         $browser = get_file_browser();
 331
 332         // Check existing file.
 333         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
 334             throw new moodle_exception('fileexist');
 335         }
 336
 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     }
 355
 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     }
 375 }
 376
 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 {
 388
 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     }
 400
 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     }
 418
 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     }
 430
 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     }
 442
 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     }
 461
 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     }
 473 }