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