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_TEXT, '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.9 Returns additional fields (timecreated, filesize, author, license)
  78      * @since Moodle 2.2
  79      */
  80     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename, $modified = null,
  81                                      $contextlevel = null, $instanceid = null) {
  82
  83         $parameters = array(
  84             'contextid'    => $contextid,
  85             'component'    => $component,
  86             'filearea'     => $filearea,
  87             'itemid'       => $itemid,
  88             'filepath'     => $filepath,
  89             'filename'     => $filename,
  90             'modified'     => $modified,
  91             'contextlevel' => $contextlevel,
  92             'instanceid'   => $instanceid);
  93         $fileinfo = self::validate_parameters(self::get_files_parameters(), $parameters);
  94
  95         $browser = get_file_browser();
  96
  97         // We need to preserve backwards compatibility. Zero will use the system context and minus one will
  98         // use the addtional parameters to determine the context.
  99         // TODO MDL-40489 get_context_from_params should handle this logic.
 100         if ($fileinfo['contextid'] == 0) {
 101             $context = context_system::instance();
 102         } else {
 103             if ($fileinfo['contextid'] == -1) {
 104                 $fileinfo['contextid'] = null;
 105             }
 106             $context = self::get_context_from_params($fileinfo);
 107         }
 108         self::validate_context($context);
 109
 110         if (empty($fileinfo['component'])) {
 111             $fileinfo['component'] = null;
 112         }
 113         if (empty($fileinfo['filearea'])) {
 114             $fileinfo['filearea'] = null;
 115         }
 116         if (empty($fileinfo['filename'])) {
 117             $fileinfo['filename'] = null;
 118         }
 119         if (empty($fileinfo['filepath'])) {
 120             $fileinfo['filepath'] = null;
 121         }
 122
 123         $return = array();
 124         $return['parents'] = array();
 125         $return['files'] = array();
 126         $list = array();
 127
 128         if ($file = $browser->get_file_info(
 129             $context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'],
 130                 $fileinfo['filepath'], $fileinfo['filename'])) {
 131             $level = $file->get_parent();
 132             while ($level) {
 133                 $params = $level->get_params();
 134                 $params['filename'] = $level->get_visible_name();
 135                 array_unshift($return['parents'], $params);
 136                 $level = $level->get_parent();
 137             }
 138             $children = $file->get_children();
 139             foreach ($children as $child) {
 140
 141                 $params = $child->get_params();
 142                 $timemodified = $child->get_timemodified();
 143                 $timecreated = $child->get_timecreated();
 144
 145                 if ($child->is_directory()) {
 146                     if ((is_null($modified)) or ($modified < $timemodified)) {
 147                         $node = array(
 148                             'contextid' => $params['contextid'],
 149                             'component' => $params['component'],
 150                             'filearea'  => $params['filearea'],
 151                             'itemid'    => $params['itemid'],
 152                             'filepath'  => $params['filepath'],
 153                             'filename'  => $child->get_visible_name(),
 154                             'url'       => null,
 155                             'isdir'     => true,
 156                             'timemodified' => $timemodified,
 157                             'timecreated' => $timecreated,
 158                             'filesize' => 0,
 159                             'author' => null,
 160                             'license' => null
 161                            );
 162                            $list[] = $node;
 163                     }
 164                 } else {
 165                     if ((is_null($modified)) or ($modified < $timemodified)) {
 166                         $node = array(
 167                             'contextid' => $params['contextid'],
 168                             'component' => $params['component'],
 169                             'filearea'  => $params['filearea'],
 170                             'itemid'    => $params['itemid'],
 171                             'filepath'  => $params['filepath'],
 172                             'filename'  => $child->get_visible_name(),
 173                             'url'       => $child->get_url(),
 174                             'isdir'     => false,
 175                             'timemodified' => $timemodified,
 176                             'timecreated' => $timecreated,
 177                             'filesize' => $child->get_filesize(),
 178                             'author' => $child->get_author(),
 179                             'license' => $child->get_license()
 180                         );
 181                            $list[] = $node;
 182                     }
 183                 }
 184             }
 185         }
 186         $return['files'] = $list;
 187         return $return;
 188     }
 189
 190     /**
 191      * Returns description of get_files returns
 192      *
 193      * @return external_single_structure
 194      * @since Moodle 2.9 Returns additional fields for files (timecreated, filesize, author, license)
 195      * @since Moodle 2.2
 196      */
 197     public static function get_files_returns() {
 198         return new external_single_structure(
 199             array(
 200                 'parents' => new external_multiple_structure(
 201                     new external_single_structure(
 202                         array(
 203                             'contextid' => new external_value(PARAM_INT, ''),
 204                             'component' => new external_value(PARAM_COMPONENT, ''),
 205                             'filearea'  => new external_value(PARAM_AREA, ''),
 206                             'itemid'    => new external_value(PARAM_INT, ''),
 207                             'filepath'  => new external_value(PARAM_TEXT, ''),
 208                             'filename'  => new external_value(PARAM_TEXT, ''),
 209                         )
 210                     )
 211                 ),
 212                 'files' => new external_multiple_structure(
 213                     new external_single_structure(
 214                         array(
 215                             'contextid' => new external_value(PARAM_INT, ''),
 216                             'component' => new external_value(PARAM_COMPONENT, ''),
 217                             'filearea'  => new external_value(PARAM_AREA, ''),
 218                             'itemid'   => new external_value(PARAM_INT, ''),
 219                             'filepath' => new external_value(PARAM_TEXT, ''),
 220                             'filename' => new external_value(PARAM_TEXT, ''),
 221                             'isdir'    => new external_value(PARAM_BOOL, ''),
 222                             'url'      => new external_value(PARAM_TEXT, ''),
 223                             'timemodified' => new external_value(PARAM_INT, ''),
 224                             'timecreated' => new external_value(PARAM_INT, 'Time created', VALUE_OPTIONAL),
 225                             'filesize' => new external_value(PARAM_INT, 'File size', VALUE_OPTIONAL),
 226                             'author' => new external_value(PARAM_TEXT, 'File owner', VALUE_OPTIONAL),
 227                             'license' => new external_value(PARAM_TEXT, 'File license', VALUE_OPTIONAL),
 228                         )
 229                     )
 230                 )
 231             )
 232         );
 233     }
 234
 235     /**
 236      * Returns description of upload parameters
 237      *
 238      * @return external_function_parameters
 239      * @since Moodle 2.2
 240      */
 241     public static function upload_parameters() {
 242         return new external_function_parameters(
 243             array(
 244                 'contextid' => new external_value(PARAM_INT, 'context id', VALUE_DEFAULT, null),
 245                 'component' => new external_value(PARAM_COMPONENT, 'component'),
 246                 'filearea'  => new external_value(PARAM_AREA, 'file area'),
 247                 'itemid'    => new external_value(PARAM_INT, 'associated id'),
 248                 'filepath'  => new external_value(PARAM_PATH, 'file path'),
 249                 'filename'  => new external_value(PARAM_FILE, 'file name'),
 250                 'filecontent' => new external_value(PARAM_TEXT, 'file content'),
 251                 'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to put the file in,
 252                         (block, course, coursecat, system, user, module)', VALUE_DEFAULT, null),
 253                 'instanceid' => new external_value(PARAM_INT, 'The Instance id of item associated
 254                          with the context level', VALUE_DEFAULT, null)
 255             )
 256         );
 257     }
 258
 259     /**
 260      * Uploading a file to moodle
 261      *
 262      * @param int    $contextid    context id
 263      * @param string $component    component
 264      * @param string $filearea     file area
 265      * @param int    $itemid       item id
 266      * @param string $filepath     file path
 267      * @param string $filename     file name
 268      * @param string $filecontent  file content
 269      * @param string $contextlevel Context level (block, course, coursecat, system, user or module)
 270      * @param int    $instanceid   Instance id of the item associated with the context level
 271      * @return array
 272      * @since Moodle 2.2
 273      */
 274     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent, $contextlevel, $instanceid) {
 275         global $USER, $CFG;
 276
 277         $fileinfo = self::validate_parameters(self::upload_parameters(), array(
 278                 'contextid' => $contextid, 'component' => $component, 'filearea' => $filearea, 'itemid' => $itemid,
 279                 'filepath' => $filepath, 'filename' => $filename, 'filecontent' => $filecontent, 'contextlevel' => $contextlevel,
 280                 'instanceid' => $instanceid));
 281
 282         if (!isset($fileinfo['filecontent'])) {
 283             throw new moodle_exception('nofile');
 284         }
 285         // Saving file.
 286         $dir = make_temp_directory('wsupload');
 287
 288         if (empty($fileinfo['filename'])) {
 289             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
 290         } else {
 291             $filename = $fileinfo['filename'];
 292         }
 293
 294         if (file_exists($dir.$filename)) {
 295             $savedfilepath = $dir.uniqid('m').$filename;
 296         } else {
 297             $savedfilepath = $dir.$filename;
 298         }
 299
 300         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
 301         @chmod($savedfilepath, $CFG->filepermissions);
 302         unset($fileinfo['filecontent']);
 303
 304         if (!empty($fileinfo['filepath'])) {
 305             $filepath = $fileinfo['filepath'];
 306         } else {
 307             $filepath = '/';
 308         }
 309
 310         // Only allow uploads to draft or private areas (private is deprecated but still supported)
 311         if (!($fileinfo['component'] == 'user' and in_array($fileinfo['filearea'], array('private', 'draft')))) {
 312             throw new coding_exception('File can be uploaded to user private or draft areas only');
 313         } else {
 314             $component = 'user';
 315             $filearea = $fileinfo['filearea'];
 316         }
 317
 318         $itemid = 0;
 319         if (isset($fileinfo['itemid'])) {
 320             $itemid = $fileinfo['itemid'];
 321         }
 322         if ($filearea == 'draft' && $itemid <= 0) {
 323             // Generate a draft area for the files.
 324             $itemid = file_get_unused_draft_itemid();
 325         } else if ($filearea == 'private') {
 326             // TODO MDL-31116 in user private area, itemid is always 0.
 327             $itemid = 0;
 328         }
 329
 330         // We need to preserve backword compatibility. Context id is no more a required.
 331         if (empty($fileinfo['contextid'])) {
 332             unset($fileinfo['contextid']);
 333         }
 334
 335         // Get and validate context.
 336         $context = self::get_context_from_params($fileinfo);
 337         self::validate_context($context);
 338         if (($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
 339             require_capability('moodle/user:manageownfiles', $context);
 340             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');
 341         }
 342
 343         $browser = get_file_browser();
 344
 345         // Check existing file.
 346         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
 347             throw new moodle_exception('fileexist');
 348         }
 349
 350         // Move file to filepool.
 351         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
 352             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
 353             $params = $info->get_params();
 354             unlink($savedfilepath);
 355             return array(
 356                 'contextid'=>$params['contextid'],
 357                 'component'=>$params['component'],
 358                 'filearea'=>$params['filearea'],
 359                 'itemid'=>$params['itemid'],
 360                 'filepath'=>$params['filepath'],
 361                 'filename'=>$params['filename'],
 362                 'url'=>$info->get_url()
 363                 );
 364         } else {
 365             throw new moodle_exception('nofile');
 366         }
 367     }
 368
 369     /**
 370      * Returns description of upload returns
 371      *
 372      * @return external_single_structure
 373      * @since Moodle 2.2
 374      */
 375     public static function upload_returns() {
 376         return new external_single_structure(
 377              array(
 378                  'contextid' => new external_value(PARAM_INT, ''),
 379                  'component' => new external_value(PARAM_COMPONENT, ''),
 380                  'filearea'  => new external_value(PARAM_AREA, ''),
 381                  'itemid'   => new external_value(PARAM_INT, ''),
 382                  'filepath' => new external_value(PARAM_TEXT, ''),
 383                  'filename' => new external_value(PARAM_FILE, ''),
 384                  'url'      => new external_value(PARAM_TEXT, ''),
 385              )
 386         );
 387     }
 388 }
 389
 390 /**
 391  * Deprecated files external functions
 392  *
 393  * @package    core_files
 394  * @copyright  2010 Dongsheng Cai
 395  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 396  * @since Moodle 2.0
 397  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 398  * @see core_files_external
 399  */
 400 class moodle_file_external extends external_api {
 401
 402     /**
 403      * Returns description of get_files parameters
 404      *
 405      * @return external_function_parameters
 406      * @since Moodle 2.0
 407      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 408      * @see core_files_external::get_files_parameters()
 409      */
 410     public static function get_files_parameters() {
 411         return core_files_external::get_files_parameters();
 412     }
 413
 414     /**
 415      * Return moodle files listing
 416      *
 417      * @param int $contextid
 418      * @param int $component
 419      * @param int $filearea
 420      * @param int $itemid
 421      * @param string $filepath
 422      * @param string $filename
 423      * @param int $modified timestamp to return files changed after this time.
 424      * @param string $contextlevel The context level for the file location.
 425      * @param int $instanceid The instance id for where the file is located.
 426      * @return array
 427      * @since Moodle 2.0
 428      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 429      * @see core_files_external::get_files()
 430      */
 431     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename, $modified = null,
 432                                      $contextlevel = null, $instanceid = null) {
 433         return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename,
 434             $modified, $contextlevel, $instanceid);
 435     }
 436
 437     /**
 438      * Returns description of get_files returns
 439      *
 440      * @return external_single_structure
 441      * @since Moodle 2.0
 442      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 443      * @see core_files_external::get_files_returns()
 444      */
 445     public static function get_files_returns() {
 446         return core_files_external::get_files_returns();
 447     }
 448
 449     /**
 450      * Marking the method as deprecated.
 451      *
 452      * @return bool
 453      */
 454     public static function get_files_is_deprecated() {
 455         return true;
 456     }
 457
 458     /**
 459      * Returns description of upload parameters
 460      *
 461      * @return external_function_parameters
 462      * @since Moodle 2.0
 463      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 464      * @see core_files_external::upload_parameters()
 465      */
 466     public static function upload_parameters() {
 467         return core_files_external::upload_parameters();
 468     }
 469
 470     /**
 471      * Uploading a file to moodle
 472      *
 473      * @param int $contextid
 474      * @param string $component
 475      * @param string $filearea
 476      * @param int $itemid
 477      * @param string $filepath
 478      * @param string $filename
 479      * @param string $filecontent
 480      * @param string $contextlevel Context level (block, course, coursecat, system, user or module)
 481      * @param int    $instanceid   Instance id of the item associated with the context level
 482      * @return array
 483      * @since Moodle 2.0
 484      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 485      * @see core_files_external::upload()
 486      */
 487     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent, $contextlevel, $instanceid) {
 488         return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename,
 489             $filecontent, $contextlevel, $instanceid);
 490     }
 491
 492     /**
 493      * Returns description of upload returns
 494      *
 495      * @return external_single_structure
 496      * @since Moodle 2.0
 497      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 498      * @see core_files_external::upload_returns()
 499      */
 500     public static function upload_returns() {
 501         return core_files_external::upload_returns();
 502     }
 503
 504     /**
 505      * Marking the method as deprecated.
 506      *
 507      * @return bool
 508      */
 509     public static function upload_is_deprecated() {
 510         return true;
 511     }
 512
 513 }