Search moodle.org's
Developer Documentation


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

Search This Site: