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 use core_external\external_api;
  28 use core_external\external_function_parameters;
  29 use core_external\external_multiple_structure;
  30 use core_external\external_single_structure;
  31 use core_external\external_value;
  32
  33 defined('MOODLE_INTERNAL') || die();
  34
  35 require_once("{$CFG->libdir}/filelib.php");
  36
  37 /**
  38  * Files external functions
  39  *
  40  * @package    core_files
  41  * @category   external
  42  * @copyright  2011 Jerome Mouneyrac
  43  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  44  * @since Moodle 2.2
  45  */
  46 class core_files_external extends external_api {
  47
  48     /**
  49      * Returns description of get_files parameters
  50      *
  51      * @return external_function_parameters
  52      * @since Moodle 2.2
  53      */
  54     public static function get_files_parameters() {
  55         return new external_function_parameters([
  56             'contextid'    => new external_value(PARAM_INT, 'context id Set to -1 to use contextlevel and instanceid.'),
  57             'component'    => new external_value(PARAM_TEXT, 'component'),
  58             'filearea'     => new external_value(PARAM_TEXT, 'file area'),
  59             'itemid'       => new external_value(PARAM_INT, 'associated id'),
  60             'filepath'     => new external_value(PARAM_PATH, 'file path'),
  61             'filename'     => new external_value(PARAM_TEXT, 'file name'),
  62             'modified'     => new external_value(
  63                 PARAM_INT,
  64                 'timestamp to return files changed after this time.',
  65                 VALUE_DEFAULT,
  66                 null
  67             ),
  68             'contextlevel' => new external_value(PARAM_ALPHA, 'The context level for the file location.', VALUE_DEFAULT, null),
  69             'instanceid'   => new external_value(PARAM_INT, 'The instance id for where the file is located.', VALUE_DEFAULT, null),
  70         ]);
  71     }
  72
  73     /**
  74      * Return moodle files listing
  75      *
  76      * @param int $contextid context id
  77      * @param int $component component
  78      * @param int $filearea file area
  79      * @param int $itemid item id
  80      * @param string $filepath file path
  81      * @param string $filename file name
  82      * @param int $modified timestamp to return files changed after this time.
  83      * @param string $contextlevel The context level for the file location.
  84      * @param int $instanceid The instance id for where the file is located.
  85      * @return array
  86      * @since Moodle 2.9 Returns additional fields (timecreated, filesize, author, license)
  87      * @since Moodle 2.2
  88      */
  89     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename, $modified = null,
  90                                      $contextlevel = null, $instanceid = null) {
  91
  92         $parameters = [
  93             'contextid'    => $contextid,
  94             'component'    => $component,
  95             'filearea'     => $filearea,
  96             'itemid'       => $itemid,
  97             'filepath'     => $filepath,
  98             'filename'     => $filename,
  99             'modified'     => $modified,
 100             'contextlevel' => $contextlevel,
 101             'instanceid'   => $instanceid,
 102         ];
 103         $fileinfo = self::validate_parameters(self::get_files_parameters(), $parameters);
 104
 105         $browser = get_file_browser();
 106
 107         // We need to preserve backwards compatibility. Zero will use the system context and minus one will
 108         // use the addtional parameters to determine the context.
 109         // TODO MDL-40489 get_context_from_params should handle this logic.
 110         if ($fileinfo['contextid'] == 0) {
 111             $context = context_system::instance();
 112         } else {
 113             if ($fileinfo['contextid'] == -1) {
 114                 $fileinfo['contextid'] = null;
 115             }
 116             $context = self::get_context_from_params($fileinfo);
 117         }
 118         self::validate_context($context);
 119
 120         if (empty($fileinfo['component'])) {
 121             $fileinfo['component'] = null;
 122         }
 123         if (empty($fileinfo['filearea'])) {
 124             $fileinfo['filearea'] = null;
 125         }
 126         if (empty($fileinfo['filename'])) {
 127             $fileinfo['filename'] = null;
 128         }
 129         if (empty($fileinfo['filepath'])) {
 130             $fileinfo['filepath'] = null;
 131         }
 132
 133         $return = array();
 134         $return['parents'] = array();
 135         $return['files'] = array();
 136         $list = array();
 137
 138         if ($file = $browser->get_file_info(
 139             $context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'],
 140                 $fileinfo['filepath'], $fileinfo['filename'])) {
 141             $level = $file->get_parent();
 142             while ($level) {
 143                 $params = $level->get_params();
 144                 $params['filename'] = $level->get_visible_name();
 145                 array_unshift($return['parents'], $params);
 146                 $level = $level->get_parent();
 147             }
 148             $children = $file->get_children();
 149             foreach ($children as $child) {
 150
 151                 $params = $child->get_params();
 152                 $timemodified = $child->get_timemodified();
 153                 $timecreated = $child->get_timecreated();
 154
 155                 if ($child->is_directory()) {
 156                     if ((is_null($modified)) or ($modified < $timemodified)) {
 157                         $node = [
 158                             'contextid' => $params['contextid'],
 159                             'component' => $params['component'],
 160                             'filearea'  => $params['filearea'],
 161                             'itemid'    => $params['itemid'],
 162                             'filepath'  => $params['filepath'],
 163                             'filename'  => $child->get_visible_name(),
 164                             'url'       => null,
 165                             'isdir'     => true,
 166                             'timemodified' => $timemodified,
 167                             'timecreated' => $timecreated,
 168                             'filesize' => 0,
 169                             'author' => null,
 170                             'license' => null,
 171                         ];
 172                         $list[] = $node;
 173                     }
 174                 } else {
 175                     if ((is_null($modified)) or ($modified < $timemodified)) {
 176                         $node = [
 177                             'contextid' => $params['contextid'],
 178                             'component' => $params['component'],
 179                             'filearea'  => $params['filearea'],
 180                             'itemid'    => $params['itemid'],
 181                             'filepath'  => $params['filepath'],
 182                             'filename'  => $child->get_visible_name(),
 183                             'url'       => $child->get_url(),
 184                             'isdir'     => false,
 185                             'timemodified' => $timemodified,
 186                             'timecreated' => $timecreated,
 187                             'filesize' => $child->get_filesize(),
 188                             'author' => $child->get_author(),
 189                             'license' => $child->get_license(),
 190                         ];
 191                         $list[] = $node;
 192                     }
 193                 }
 194             }
 195         }
 196         $return['files'] = $list;
 197         return $return;
 198     }
 199
 200     /**
 201      * Returns description of get_files returns
 202      *
 203      * @return external_single_structure
 204      * @since Moodle 2.9 Returns additional fields for files (timecreated, filesize, author, license)
 205      * @since Moodle 2.2
 206      */
 207     public static function get_files_returns() {
 208         return new external_single_structure([
 209             'parents' => new external_multiple_structure(
 210                 new external_single_structure([
 211                     'contextid' => new external_value(PARAM_INT, ''),
 212                     'component' => new external_value(PARAM_COMPONENT, ''),
 213                     'filearea'  => new external_value(PARAM_AREA, ''),
 214                     'itemid'    => new external_value(PARAM_INT, ''),
 215                     'filepath'  => new external_value(PARAM_TEXT, ''),
 216                     'filename'  => new external_value(PARAM_TEXT, ''),
 217                 ])
 218             ),
 219             'files' => new external_multiple_structure(
 220                 new external_single_structure([
 221                     'contextid' => new external_value(PARAM_INT, ''),
 222                     'component' => new external_value(PARAM_COMPONENT, ''),
 223                     'filearea'  => new external_value(PARAM_AREA, ''),
 224                     'itemid'   => new external_value(PARAM_INT, ''),
 225                     'filepath' => new external_value(PARAM_TEXT, ''),
 226                     'filename' => new external_value(PARAM_TEXT, ''),
 227                     'isdir'    => new external_value(PARAM_BOOL, ''),
 228                     'url'      => new external_value(PARAM_TEXT, ''),
 229                     'timemodified' => new external_value(PARAM_INT, ''),
 230                     'timecreated' => new external_value(PARAM_INT, 'Time created', VALUE_OPTIONAL),
 231                     'filesize' => new external_value(PARAM_INT, 'File size', VALUE_OPTIONAL),
 232                     'author' => new external_value(PARAM_TEXT, 'File owner', VALUE_OPTIONAL),
 233                     'license' => new external_value(PARAM_TEXT, 'File license', VALUE_OPTIONAL),
 234                 ])
 235             ),
 236         ]);
 237     }
 238
 239     /**
 240      * Returns description of upload parameters
 241      *
 242      * @return external_function_parameters
 243      * @since Moodle 2.2
 244      */
 245     public static function upload_parameters() {
 246         return new external_function_parameters([
 247             'contextid' => new external_value(PARAM_INT, 'context id', VALUE_DEFAULT, null),
 248             'component' => new external_value(PARAM_COMPONENT, 'component'),
 249             'filearea'  => new external_value(PARAM_AREA, 'file area'),
 250             'itemid'    => new external_value(PARAM_INT, 'associated id'),
 251             'filepath'  => new external_value(PARAM_PATH, 'file path'),
 252             'filename'  => new external_value(PARAM_FILE, 'file name'),
 253             'filecontent' => new external_value(PARAM_TEXT, 'file content'),
 254             'contextlevel' => new external_value(
 255                 PARAM_ALPHA,
 256                 'The context level to put the file in,
 257                         (block, course, coursecat, system, user, module)',
 258                 VALUE_DEFAULT,
 259                 null
 260             ),
 261             'instanceid' => new external_value(PARAM_INT, 'The Instance id of item associated
 262                          with the context level', VALUE_DEFAULT, null),
 263         ]);
 264     }
 265
 266     /**
 267      * Uploading a file to moodle
 268      *
 269      * @param int    $contextid    context id
 270      * @param string $component    component
 271      * @param string $filearea     file area
 272      * @param int    $itemid       item id
 273      * @param string $filepath     file path
 274      * @param string $filename     file name
 275      * @param string $filecontent  file content
 276      * @param string $contextlevel Context level (block, course, coursecat, system, user or module)
 277      * @param int    $instanceid   Instance id of the item associated with the context level
 278      * @return array
 279      * @since Moodle 2.2
 280      */
 281     public static function upload(
 282         $contextid,
 283         $component,
 284         $filearea,
 285         $itemid,
 286         $filepath,
 287         $filename,
 288         $filecontent,
 289         $contextlevel,
 290         $instanceid
 291     ) {
 292         global $USER, $CFG;
 293
 294         $fileinfo = self::validate_parameters(self::upload_parameters(), [
 295             'contextid' => $contextid, 'component' => $component, 'filearea' => $filearea, 'itemid' => $itemid,
 296             'filepath' => $filepath, 'filename' => $filename, 'filecontent' => $filecontent, 'contextlevel' => $contextlevel,
 297             'instanceid' => $instanceid,
 298         ]);
 299
 300         if (!isset($fileinfo['filecontent'])) {
 301             throw new moodle_exception('nofile');
 302         }
 303         // Saving file.
 304         $dir = make_temp_directory('wsupload');
 305
 306         if (empty($fileinfo['filename'])) {
 307             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
 308         } else {
 309             $filename = $fileinfo['filename'];
 310         }
 311
 312         if (file_exists($dir.$filename)) {
 313             $savedfilepath = $dir.uniqid('m').$filename;
 314         } else {
 315             $savedfilepath = $dir.$filename;
 316         }
 317
 318         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
 319         @chmod($savedfilepath, $CFG->filepermissions);
 320         unset($fileinfo['filecontent']);
 321
 322         if (!empty($fileinfo['filepath'])) {
 323             $filepath = $fileinfo['filepath'];
 324         } else {
 325             $filepath = '/';
 326         }
 327
 328         // Only allow uploads to draft area.
 329         if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'draft')) {
 330             throw new coding_exception('File can be uploaded to user draft area only');
 331         } else {
 332             $component = 'user';
 333             $filearea = $fileinfo['filearea'];
 334         }
 335
 336         $itemid = 0;
 337         if (isset($fileinfo['itemid'])) {
 338             $itemid = $fileinfo['itemid'];
 339         }
 340         if ($filearea == 'draft' && $itemid <= 0) {
 341             // Generate a draft area for the files.
 342             $itemid = file_get_unused_draft_itemid();
 343         } else if ($filearea == 'private') {
 344             // TODO MDL-31116 in user private area, itemid is always 0.
 345             $itemid = 0;
 346         }
 347
 348         // We need to preserve backword compatibility. Context id is no more a required.
 349         if (empty($fileinfo['contextid'])) {
 350             unset($fileinfo['contextid']);
 351         }
 352
 353         // Get and validate context.
 354         $context = self::get_context_from_params($fileinfo);
 355         self::validate_context($context);
 356         if (($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
 357             throw new moodle_exception('privatefilesupload');
 358         }
 359
 360         $browser = get_file_browser();
 361
 362         // Check existing file.
 363         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
 364             throw new moodle_exception('fileexist');
 365         }
 366
 367         // Move file to filepool.
 368         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
 369             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
 370             $params = $info->get_params();
 371             unlink($savedfilepath);
 372             return [
 373                 'contextid' => $params['contextid'],
 374                 'component' => $params['component'],
 375                 'filearea' => $params['filearea'],
 376                 'itemid' => $params['itemid'],
 377                 'filepath' => $params['filepath'],
 378                 'filename' => $params['filename'],
 379                 'url' => $info->get_url(),
 380             ];
 381         } else {
 382             throw new moodle_exception('nofile');
 383         }
 384     }
 385
 386     /**
 387      * Returns description of upload returns
 388      *
 389      * @return external_single_structure
 390      * @since Moodle 2.2
 391      */
 392     public static function upload_returns() {
 393         return new external_single_structure([
 394             'contextid' => new external_value(PARAM_INT, ''),
 395             'component' => new external_value(PARAM_COMPONENT, ''),
 396             'filearea'  => new external_value(PARAM_AREA, ''),
 397             'itemid'   => new external_value(PARAM_INT, ''),
 398             'filepath' => new external_value(PARAM_TEXT, ''),
 399             'filename' => new external_value(PARAM_FILE, ''),
 400             'url'      => new external_value(PARAM_TEXT, ''),
 401         ]);
 402     }
 403 }