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             )
  57         );
  58     }
  59
  60     /**
  61      * Return moodle files listing
  62      *
  63      * @param int $contextid context id
  64      * @param int $component component
  65      * @param int $filearea file aera
  66      * @param int $itemid item id
  67      * @param string $filepath file path
  68      * @param string $filename file name
  69      * @return array
  70      * @since Moodle 2.2
  71      */
  72     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
  73         global $CFG, $USER, $OUTPUT;
  74         $fileinfo = self::validate_parameters(self::get_files_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename));
  75
  76         $browser = get_file_browser();
  77
  78         if (empty($fileinfo['contextid'])) {
  79             $context  = get_system_context();
  80         } else {
  81             $context  = get_context_instance_by_id($fileinfo['contextid']);
  82         }
  83         if (empty($fileinfo['component'])) {
  84             $fileinfo['component'] = null;
  85         }
  86         if (empty($fileinfo['filearea'])) {
  87             $fileinfo['filearea'] = null;
  88         }
  89         if (empty($fileinfo['itemid'])) {
  90             $fileinfo['itemid'] = null;
  91         }
  92         if (empty($fileinfo['filename'])) {
  93             $fileinfo['filename'] = null;
  94         }
  95         if (empty($fileinfo['filepath'])) {
  96             $fileinfo['filepath'] = null;
  97         }
  98
  99         $return = array();
 100         $return['parents'] = array();
 101         $return['files'] = array();
 102         if ($file = $browser->get_file_info($context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename'])) {
 103             $level = $file->get_parent();
 104             while ($level) {
 105                 $params = $level->get_params();
 106                 $params['filename'] = $level->get_visible_name();
 107                 array_unshift($return['parents'], $params);
 108                 $level = $level->get_parent();
 109             }
 110             $list = array();
 111             $children = $file->get_children();
 112             foreach ($children as $child) {
 113
 114                 $params = $child->get_params();
 115
 116                 if ($child->is_directory()) {
 117                     $node = array(
 118                         'contextid' => $params['contextid'],
 119                         'component' => $params['component'],
 120                         'filearea'  => $params['filearea'],
 121                         'itemid'    => $params['itemid'],
 122                         'filepath'  => $params['filepath'],
 123                         'filename'  => $child->get_visible_name(),
 124                         'url'       => null,
 125                         'isdir'     => true
 126                     );
 127                     $list[] = $node;
 128                 } else {
 129                     $node = array(
 130                         'contextid' => $params['contextid'],
 131                         'component' => $params['component'],
 132                         'filearea'  => $params['filearea'],
 133                         'itemid'    => $params['itemid'],
 134                         'filepath'  => $params['filepath'],
 135                         'filename'  => $child->get_visible_name(),
 136                         'url'       => $child->get_url(),
 137                         'isdir'     => false
 138                     );
 139                     $list[] = $node;
 140                 }
 141             }
 142         }
 143         $return['files'] = $list;
 144         return $return;
 145     }
 146
 147     /**
 148      * Returns description of get_files returns
 149      *
 150      * @return external_single_structure
 151      * @since Moodle 2.2
 152      */
 153     public static function get_files_returns() {
 154         return new external_single_structure(
 155             array(
 156                 'parents' => new external_multiple_structure(
 157                     new external_single_structure(
 158                         array(
 159                             'contextid' => new external_value(PARAM_INT, ''),
 160                             'component' => new external_value(PARAM_COMPONENT, ''),
 161                             'filearea'  => new external_value(PARAM_AREA, ''),
 162                             'itemid'    => new external_value(PARAM_INT, ''),
 163                             'filepath'  => new external_value(PARAM_TEXT, ''),
 164                             'filename'  => new external_value(PARAM_TEXT, ''),
 165                         )
 166                     )
 167                 ),
 168                 'files' => new external_multiple_structure(
 169                     new external_single_structure(
 170                         array(
 171                             'contextid' => new external_value(PARAM_INT, ''),
 172                             'component' => new external_value(PARAM_COMPONENT, ''),
 173                             'filearea'  => new external_value(PARAM_AREA, ''),
 174                             'itemid'   => new external_value(PARAM_INT, ''),
 175                             'filepath' => new external_value(PARAM_TEXT, ''),
 176                             'filename' => new external_value(PARAM_FILE, ''),
 177                             'isdir'    => new external_value(PARAM_BOOL, ''),
 178                             'url'      => new external_value(PARAM_TEXT, ''),
 179                         )
 180                     )
 181                 )
 182             )
 183         );
 184     }
 185
 186     /**
 187      * Returns description of upload parameters
 188      *
 189      * @return external_function_parameters
 190      * @since Moodle 2.2
 191      */
 192     public static function upload_parameters() {
 193         return new external_function_parameters(
 194             array(
 195                 'contextid' => new external_value(PARAM_INT, 'context id'),
 196                 'component' => new external_value(PARAM_COMPONENT, 'component'),
 197                 'filearea'  => new external_value(PARAM_AREA, 'file area'),
 198                 'itemid'    => new external_value(PARAM_INT, 'associated id'),
 199                 'filepath'  => new external_value(PARAM_PATH, 'file path'),
 200                 'filename'  => new external_value(PARAM_FILE, 'file name'),
 201                 'filecontent' => new external_value(PARAM_TEXT, 'file content')
 202             )
 203         );
 204     }
 205
 206     /**
 207      * Uploading a file to moodle
 208      *
 209      * @param int $contextid context id
 210      * @param string $component component
 211      * @param string $filearea file aera
 212      * @param int $itemid item id
 213      * @param string $filepath file path
 214      * @param string $filename file name
 215      * @param string $filecontent file content
 216      * @return array
 217      * @since Moodle 2.2
 218      */
 219     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
 220         global $USER, $CFG;
 221
 222         $fileinfo = self::validate_parameters(self::upload_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename, 'filecontent'=>$filecontent));
 223
 224         if (!isset($fileinfo['filecontent'])) {
 225             throw new moodle_exception('nofile');
 226         }
 227         // saving file
 228         $dir = make_temp_directory('wsupload');
 229
 230         if (empty($fileinfo['filename'])) {
 231             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
 232         } else {
 233             $filename = $fileinfo['filename'];
 234         }
 235
 236         if (file_exists($dir.$filename)) {
 237             $savedfilepath = $dir.uniqid('m').$filename;
 238         } else {
 239             $savedfilepath = $dir.$filename;
 240         }
 241
 242
 243         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
 244         unset($fileinfo['filecontent']);
 245
 246         if (!empty($fileinfo['filepath'])) {
 247             $filepath = $fileinfo['filepath'];
 248         } else {
 249             $filepath = '/';
 250         }
 251
 252         if (isset($fileinfo['itemid'])) {
 253             // TODO MDL-31116 in user private area, itemid is always 0
 254             $itemid = 0;
 255         } else {
 256             throw new coding_exception('itemid cannot be empty');
 257         }
 258
 259         if (!empty($fileinfo['contextid'])) {
 260             $context = get_context_instance_by_id($fileinfo['contextid']);
 261         } else {
 262             $context = get_system_context();
 263         }
 264
 265         if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
 266             throw new coding_exception('File can be uploaded to user private area only');
 267         } else {
 268             // TODO MDL-31116 hard-coded to use user_private area
 269             $component = 'user';
 270             $filearea = 'private';
 271         }
 272
 273         $browser = get_file_browser();
 274
 275         // check existing file
 276         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
 277             throw new moodle_exception('fileexist');
 278         }
 279
 280         // move file to filepool
 281         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
 282             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
 283             $params = $info->get_params();
 284             unlink($savedfilepath);
 285             return array(
 286                 'contextid'=>$params['contextid'],
 287                 'component'=>$params['component'],
 288                 'filearea'=>$params['filearea'],
 289                 'itemid'=>$params['itemid'],
 290                 'filepath'=>$params['filepath'],
 291                 'filename'=>$params['filename'],
 292                 'url'=>$info->get_url()
 293                 );
 294         } else {
 295             throw new moodle_exception('nofile');
 296         }
 297     }
 298
 299     /**
 300      * Returns description of upload returns
 301      *
 302      * @return external_single_structure
 303      * @since Moodle 2.2
 304      */
 305     public static function upload_returns() {
 306         return new external_single_structure(
 307              array(
 308                  'contextid' => new external_value(PARAM_INT, ''),
 309                  'component' => new external_value(PARAM_COMPONENT, ''),
 310                  'filearea'  => new external_value(PARAM_AREA, ''),
 311                  'itemid'   => new external_value(PARAM_INT, ''),
 312                  'filepath' => new external_value(PARAM_TEXT, ''),
 313                  'filename' => new external_value(PARAM_FILE, ''),
 314                  'url'      => new external_value(PARAM_TEXT, ''),
 315              )
 316         );
 317     }
 318 }
 319
 320 /**
 321  * Deprecated files external functions
 322  *
 323  * @package    core_files
 324  * @copyright  2010 Dongsheng Cai
 325  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 326  * @since Moodle 2.0
 327  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 328  * @todo MDL-31194 This will be deleted in Moodle 2.5.
 329  * @see core_files_external
 330  */
 331 class moodle_file_external extends external_api {
 332
 333     /**
 334      * Returns description of get_files parameters
 335      *
 336      * @return external_function_parameters
 337      * @since Moodle 2.0
 338      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 339      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 340      * @see core_files_external::get_files_parameters()
 341      */
 342     public static function get_files_parameters() {
 343         return core_files_external::get_files_parameters();
 344     }
 345
 346     /**
 347      * Return moodle files listing
 348      *
 349      * @param int $contextid
 350      * @param int $component
 351      * @param int $filearea
 352      * @param int $itemid
 353      * @param string $filepath
 354      * @param string $filename
 355      * @return array
 356      * @since Moodle 2.0
 357      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 358      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 359      * @see core_files_external::get_files()
 360      */
 361     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
 362         return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
 363     }
 364
 365     /**
 366      * Returns description of get_files returns
 367      *
 368      * @return external_single_structure
 369      * @since Moodle 2.0
 370      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 371      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 372      * @see core_files_external::get_files_returns()
 373      */
 374     public static function get_files_returns() {
 375         return core_files_external::get_files_returns();
 376     }
 377
 378     /**
 379      * Returns description of upload parameters
 380      *
 381      * @return external_function_parameters
 382      * @since Moodle 2.0
 383      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 384      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 385      * @see core_files_external::upload_parameters()
 386      */
 387     public static function upload_parameters() {
 388         return core_files_external::upload_parameters();
 389     }
 390
 391     /**
 392      * Uploading a file to moodle
 393      *
 394      * @param int $contextid
 395      * @param string $component
 396      * @param string $filearea
 397      * @param int $itemid
 398      * @param string $filepath
 399      * @param string $filename
 400      * @param string $filecontent
 401      * @return array
 402      * @since Moodle 2.0
 403      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 404      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 405      * @see core_files_external::upload()
 406      */
 407     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
 408         return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
 409     }
 410
 411     /**
 412      * Returns description of upload returns
 413      *
 414      * @return external_single_structure
 415      * @since Moodle 2.0
 416      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 417      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 418      * @see core_files_external::upload_returns()
 419      */
 420     public static function upload_returns() {
 421         return core_files_external::upload_returns();
 422     }
 423 }