files/externallib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * External files API
  20  *
  21  * @package    moodlecore
  22  * @subpackage webservice
  23  * @copyright  2010 Dongsheng Cai <dongsheng@moodle.com>
  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 functions
  32  */
  33 class core_files_external extends external_api {
  34
  35     /**
  36      * Returns description of get_files parameters
  37      * @return external_function_parameters
  38      */
  39     public static function get_files_parameters() {
  40         return new external_function_parameters(
  41             array(
  42                 'contextid' => new external_value(PARAM_INT, 'context id'),
  43                 'component' => new external_value(PARAM_TEXT, 'component'),
  44                 'filearea'  => new external_value(PARAM_TEXT, 'file area'),
  45                 'itemid'    => new external_value(PARAM_INT, 'associated id'),
  46                 'filepath'  => new external_value(PARAM_PATH, 'file path'),
  47                 'filename'  => new external_value(PARAM_FILE, 'file name')
  48             )
  49         );
  50     }
  51
  52     /**
  53      * Return moodle files listing
  54      * @param int $contextid
  55      * @param int $component
  56      * @param int $filearea
  57      * @param int $itemid
  58      * @param string $filepath
  59      * @param string $filename
  60      * @return array
  61      */
  62     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
  63         global $CFG, $USER, $OUTPUT;
  64         $fileinfo = self::validate_parameters(self::get_files_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename));
  65
  66         $browser = get_file_browser();
  67
  68         if (empty($fileinfo['contextid'])) {
  69             $context  = get_system_context();
  70         } else {
  71             $context  = get_context_instance_by_id($fileinfo['contextid']);
  72         }
  73         if (empty($fileinfo['component'])) {
  74             $fileinfo['component'] = null;
  75         }
  76         if (empty($fileinfo['filearea'])) {
  77             $fileinfo['filearea'] = null;
  78         }
  79         if (empty($fileinfo['itemid'])) {
  80             $fileinfo['itemid'] = null;
  81         }
  82         if (empty($fileinfo['filename'])) {
  83             $fileinfo['filename'] = null;
  84         }
  85         if (empty($fileinfo['filepath'])) {
  86             $fileinfo['filepath'] = null;
  87         }
  88
  89         $return = array();
  90         $return['parents'] = array();
  91         $return['files'] = array();
  92         if ($file = $browser->get_file_info($context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename'])) {
  93             $level = $file->get_parent();
  94             while ($level) {
  95                 $params = $level->get_params();
  96                 $params['filename'] = $level->get_visible_name();
  97                 array_unshift($return['parents'], $params);
  98                 $level = $level->get_parent();
  99             }
 100             $list = array();
 101             $children = $file->get_children();
 102             foreach ($children as $child) {
 103
 104                 $params = $child->get_params();
 105
 106                 if ($child->is_directory()) {
 107                     $node = array(
 108                         'contextid' => $params['contextid'],
 109                         'component' => $params['component'],
 110                         'filearea'  => $params['filearea'],
 111                         'itemid'    => $params['itemid'],
 112                         'filepath'  => $params['filepath'],
 113                         'filename'  => $child->get_visible_name(),
 114                         'url'       => null,
 115                         'isdir'     => true
 116                     );
 117                     $list[] = $node;
 118                 } else {
 119                     $node = array(
 120                         'contextid' => $params['contextid'],
 121                         'component' => $params['component'],
 122                         'filearea'  => $params['filearea'],
 123                         'itemid'    => $params['itemid'],
 124                         'filepath'  => $params['filepath'],
 125                         'filename'  => $child->get_visible_name(),
 126                         'url'       => $child->get_url(),
 127                         'isdir'     => false
 128                     );
 129                     $list[] = $node;
 130                 }
 131             }
 132         }
 133         $return['files'] = $list;
 134         return $return;
 135     }
 136
 137     /**
 138      * Returns description of get_files returns
 139      * @return external_multiple_structure
 140      */
 141     public static function get_files_returns() {
 142         return new external_single_structure(
 143             array(
 144                 'parents' => new external_multiple_structure(
 145                     new external_single_structure(
 146                         array(
 147                             'contextid' => new external_value(PARAM_INT, ''),
 148                             'component' => new external_value(PARAM_COMPONENT, ''),
 149                             'filearea'  => new external_value(PARAM_AREA, ''),
 150                             'itemid'    => new external_value(PARAM_INT, ''),
 151                             'filepath'  => new external_value(PARAM_TEXT, ''),
 152                             'filename'  => new external_value(PARAM_TEXT, ''),
 153                         )
 154                     )
 155                 ),
 156                 'files' => 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_FILE, ''),
 165                             'isdir'    => new external_value(PARAM_BOOL, ''),
 166                             'url'      => new external_value(PARAM_TEXT, ''),
 167                         )
 168                     )
 169                 )
 170             )
 171         );
 172     }
 173
 174     /**
 175      * Returns description of upload parameters
 176      * @return external_function_parameters
 177      */
 178     public static function upload_parameters() {
 179         return new external_function_parameters(
 180             array(
 181                 'contextid' => new external_value(PARAM_INT, 'context id'),
 182                 'component' => new external_value(PARAM_COMPONENT, 'component'),
 183                 'filearea'  => new external_value(PARAM_AREA, 'file area'),
 184                 'itemid'    => new external_value(PARAM_INT, 'associated id'),
 185                 'filepath'  => new external_value(PARAM_PATH, 'file path'),
 186                 'filename'  => new external_value(PARAM_FILE, 'file name'),
 187                 'filecontent' => new external_value(PARAM_TEXT, 'file content')
 188             )
 189         );
 190     }
 191
 192     /**
 193      * Uploading a file to moodle
 194      *
 195      * @param int $contextid
 196      * @param string $component
 197      * @param string $filearea
 198      * @param int $itemid
 199      * @param string $filepath
 200      * @param string $filename
 201      * @param string $filecontent
 202      * @return array
 203      */
 204     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
 205         global $USER, $CFG;
 206
 207         $fileinfo = self::validate_parameters(self::upload_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename, 'filecontent'=>$filecontent));
 208
 209         if (!isset($fileinfo['filecontent'])) {
 210             throw new moodle_exception('nofile');
 211         }
 212         // saving file
 213         $dir = make_temp_directory('wsupload');
 214
 215         if (empty($fileinfo['filename'])) {
 216             $filename = uniqid('wsupload', true).'_'.time().'.tmp';
 217         } else {
 218             $filename = $fileinfo['filename'];
 219         }
 220
 221         if (file_exists($dir.$filename)) {
 222             $savedfilepath = $dir.uniqid('m').$filename;
 223         } else {
 224             $savedfilepath = $dir.$filename;
 225         }
 226
 227
 228         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
 229         unset($fileinfo['filecontent']);
 230
 231         if (!empty($fileinfo['filepath'])) {
 232             $filepath = $fileinfo['filepath'];
 233         } else {
 234             $filepath = '/';
 235         }
 236
 237         if (isset($fileinfo['itemid'])) {
 238             // TODO: in user private area, itemid is always 0
 239             $itemid = 0;
 240         } else {
 241             throw new coding_exception('itemid cannot be empty');
 242         }
 243
 244         if (!empty($fileinfo['contextid'])) {
 245             $context = get_context_instance_by_id($fileinfo['contextid']);
 246         } else {
 247             $context = get_system_context();
 248         }
 249
 250         if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
 251             throw new coding_exception('File can be uploaded to user private area only');
 252         } else {
 253             // TODO: hard-coded to use user_private area
 254             $component = 'user';
 255             $filearea = 'private';
 256         }
 257
 258         $browser = get_file_browser();
 259
 260         // check existing file
 261         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
 262             throw new moodle_exception('fileexist');
 263         }
 264
 265         // move file to filepool
 266         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
 267             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
 268             $params = $info->get_params();
 269             unlink($savedfilepath);
 270             return array(
 271                 'contextid'=>$params['contextid'],
 272                 'component'=>$params['component'],
 273                 'filearea'=>$params['filearea'],
 274                 'itemid'=>$params['itemid'],
 275                 'filepath'=>$params['filepath'],
 276                 'filename'=>$params['filename'],
 277                 'url'=>$info->get_url()
 278                 );
 279         } else {
 280             throw new moodle_exception('nofile');
 281         }
 282     }
 283
 284     /**
 285      * Returns description of upload returns
 286      * @return external_multiple_structure
 287      */
 288     public static function upload_returns() {
 289         return new external_single_structure(
 290              array(
 291                  'contextid' => new external_value(PARAM_INT, ''),
 292                  'component' => new external_value(PARAM_COMPONENT, ''),
 293                  'filearea'  => new external_value(PARAM_AREA, ''),
 294                  'itemid'   => new external_value(PARAM_INT, ''),
 295                  'filepath' => new external_value(PARAM_TEXT, ''),
 296                  'filename' => new external_value(PARAM_FILE, ''),
 297                  'url'      => new external_value(PARAM_TEXT, ''),
 298              )
 299         );
 300     }
 301 }
 302
 303 /**
 304  * Deprecated files functions
 305  * @deprecated since Moodle 2.2 please use core_files_external instead
 306  */
 307 class moodle_file_external extends external_api {
 308
 309     /**
 310      * Returns description of get_files parameters
 311      * @deprecated since Moodle 2.2 please use core_files_external::get_files_parameters instead
 312      * @return external_function_parameters
 313      */
 314     public static function get_files_parameters() {
 315         return core_files_external::get_files_parameters();
 316     }
 317
 318     /**
 319      * Return moodle files listing
 320      * @deprecated since Moodle 2.2 please use core_files_external::get_files instead
 321      * @param int $contextid
 322      * @param int $component
 323      * @param int $filearea
 324      * @param int $itemid
 325      * @param string $filepath
 326      * @param string $filename
 327      * @return array
 328      */
 329     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
 330         return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
 331     }
 332
 333     /**
 334      * Returns description of get_files returns
 335      * @deprecated since Moodle 2.2 please use core_files_external::get_files_returns instead
 336      * @return external_multiple_structure
 337      */
 338     public static function get_files_returns() {
 339         return core_files_external::get_files_returns();
 340     }
 341
 342     /**
 343      * Returns description of upload parameters
 344      * @deprecated since Moodle 2.2 please use core_files_external::upload_parameters instead
 345      * @return external_function_parameters
 346      */
 347     public static function upload_parameters() {
 348         return core_files_external::upload_parameters();
 349     }
 350
 351     /**
 352      * Uploading a file to moodle
 353      * @deprecated since Moodle 2.2 please use core_files_external::upload instead
 354      * @param int $contextid
 355      * @param string $component
 356      * @param string $filearea
 357      * @param int $itemid
 358      * @param string $filepath
 359      * @param string $filename
 360      * @param string $filecontent
 361      * @return array
 362      */
 363     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
 364         return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
 365     }
 366
 367     /**
 368      * Returns description of upload returns
 369      * @deprecated since Moodle 2.2 please use core_files_external::upload_returns instead
 370      * @return external_multiple_structure
 371      */
 372     public static function upload_returns() {
 373         return core_files_external::upload_returns();
 374     }
 375 }