Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 3.9.x will end* 10 May 2021 (12 months).
  • Bug fixes for security issues in 3.9.x will end* 8 May 2023 (36 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
/lib/ -> boxlib.php (source)
   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   * Box.net client.
  19   *
  20   * @package core
  21   * @author James Levy <james@box.net>
  22   * @link http://enabled.box.net
  23   * @access public
  24   * @version 1.0
  25   * @copyright copyright Box.net 2007
  26   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  27   */
  28  
  29  defined('MOODLE_INTERNAL') || die();
  30  require_once($CFG->libdir . '/oauthlib.php');
  31  
  32  /**
  33   * Box.net client class.
  34   *
  35   * @package    core
  36   * @copyright  2013 Frédéric Massart
  37   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38   */
  39  class boxnet_client extends oauth2_client {
  40  
  41      /** @const API URL */
  42      const API = 'https://api.box.com/2.0';
  43  
  44      /** @const UPLOAD_API URL */
  45      const UPLOAD_API = 'https://upload.box.com/api/2.0';
  46  
  47      /**
  48       * Return authorize URL.
  49       *
  50       * @return string
  51       */
  52      protected function auth_url() {
  53          return 'https://www.box.com/api/oauth2/authorize';
  54      }
  55  
  56      /**
  57       * Create a folder.
  58       *
  59       * @param string $foldername The folder name.
  60       * @param int $parentid The ID of the parent folder.
  61       * @return array Information about the new folder.
  62       */
  63      public function create_folder($foldername, $parentid = 0) {
  64          $params = array('name' => $foldername, 'parent' => array('id' => (string) $parentid));
  65          $this->reset_state();
  66          $result = $this->post($this->make_url("/folders"), json_encode($params));
  67          $result = json_decode($result);
  68          return $result;
  69      }
  70  
  71      /**
  72       * Download the file.
  73       *
  74       * @param int $fileid File ID.
  75       * @param string $path Path to download the file to.
  76       * @return bool Success or not.
  77       */
  78      public function download_file($fileid, $path) {
  79          $this->reset_state();
  80          $result = $this->download_one($this->make_url("/files/$fileid/content"), array(),
  81              array('filepath' => $path, 'CURLOPT_FOLLOWLOCATION' => true));
  82          return ($result === true && $this->info['http_code'] === 200);
  83      }
  84  
  85      /**
  86       * Get info of a file.
  87       *
  88       * @param int $fileid File ID.
  89       * @return object
  90       */
  91      public function get_file_info($fileid) {
  92          $this->reset_state();
  93          $result = $this->request($this->make_url("/files/$fileid"));
  94          return json_decode($result);
  95      }
  96  
  97      /**
  98       * Get a folder content.
  99       *
 100       * @param int $folderid Folder ID.
 101       * @return object
 102       */
 103      public function get_folder_items($folderid = 0) {
 104          $this->reset_state();
 105          $result = $this->request($this->make_url("/folders/$folderid/items",
 106              array('fields' => 'id,name,type,modified_at,size,owned_by')));
 107          return json_decode($result);
 108      }
 109  
 110      /**
 111       * Log out.
 112       *
 113       * @return void
 114       */
 115      public function log_out() {
 116          if ($accesstoken = $this->get_accesstoken()) {
 117              $params = array(
 118                  'client_id' => $this->get_clientid(),
 119                  'client_secret' => $this->get_clientsecret(),
 120                  'token' => $accesstoken->token
 121              );
 122              $this->reset_state();
 123              $this->post($this->revoke_url(), $params);
 124          }
 125          parent::log_out();
 126      }
 127  
 128      /**
 129       * Build a request URL.
 130       *
 131       * @param string $uri The URI to request.
 132       * @param array $params Query string parameters.
 133       * @param bool $uploadapi Whether this works with the upload API or not.
 134       * @return string
 135       */
 136      protected function make_url($uri, $params = array(), $uploadapi = false) {
 137          $api = $uploadapi ? self::UPLOAD_API : self::API;
 138          $url = new moodle_url($api . '/' . ltrim($uri, '/'), $params);
 139          return $url->out(false);
 140      }
 141  
 142      /**
 143       * Rename a file.
 144       *
 145       * @param int $fileid The file ID.
 146       * @param string $newname The new file name.
 147       * @return object Box.net file object.
 148       */
 149      public function rename_file($fileid, $newname) {
 150          // This requires a PUT request with data within it. We cannot use
 151          // the standard PUT request 'CURLOPT_PUT' because it expects a file.
 152          $data = array('name' => $newname);
 153          $options = array(
 154              'CURLOPT_CUSTOMREQUEST' => 'PUT',
 155              'CURLOPT_POSTFIELDS' => json_encode($data)
 156          );
 157          $url = $this->make_url("/files/$fileid");
 158          $this->reset_state();
 159          $result = $this->request($url, $options);
 160          $result = json_decode($result);
 161          return $result;
 162      }
 163  
 164      /**
 165       * Resets curl for multiple requests.
 166       *
 167       * @return void
 168       */
 169      public function reset_state() {
 170          $this->cleanopt();
 171          $this->resetHeader();
 172      }
 173  
 174      /**
 175       * Return the revoke URL.
 176       *
 177       * @return string
 178       */
 179      protected function revoke_url() {
 180          return 'https://www.box.com/api/oauth2/revoke';
 181      }
 182  
 183      /**
 184       * Share a file and return the link to it.
 185       *
 186       * @param string $fileid The file ID.
 187       * @param bool $businesscheck Whether or not to check if the user can share files, has a business account.
 188       * @return object
 189       */
 190      public function share_file($fileid, $businesscheck = true) {
 191          // Sharing the file, this requires a PUT request with data within it. We cannot use
 192          // the standard PUT request 'CURLOPT_PUT' because it expects a file.
 193          $data = array('shared_link' => array('access' => 'open', 'permissions' =>
 194              array('can_download' => true, 'can_preview' => true)));
 195          $options = array(
 196              'CURLOPT_CUSTOMREQUEST' => 'PUT',
 197              'CURLOPT_POSTFIELDS' => json_encode($data)
 198          );
 199          $this->reset_state();
 200          $result = $this->request($this->make_url("/files/$fileid"), $options);
 201          $result = json_decode($result);
 202  
 203          if ($businesscheck) {
 204              // Checks that the user has the right to share the file. If not, throw an exception.
 205              $this->reset_state();
 206              $this->head($result->shared_link->download_url);
 207              $info = $this->get_info();
 208              if ($info['http_code'] == 403) {
 209                  throw new moodle_exception('No permission to share the file');
 210              }
 211          }
 212  
 213          return $result->shared_link;
 214      }
 215  
 216      /**
 217       * Search.
 218       *
 219       * @return object
 220       */
 221      public function search($query) {
 222          $this->reset_state();
 223          $result = $this->request($this->make_url('/search', array('query' => $query, 'limit' => 50, 'offset' => 0)));
 224          return json_decode($result);
 225      }
 226  
 227      /**
 228       * Return token URL.
 229       *
 230       * @return string
 231       */
 232      protected function token_url() {
 233          return 'https://www.box.com/api/oauth2/token';
 234      }
 235  
 236      /**
 237       * Upload a file.
 238       *
 239       * Please note that the file is named on Box.net using the path we are providing, and so
 240       * the file has the name of the stored_file hash.
 241       *
 242       * @param stored_file $storedfile A stored_file.
 243       * @param integer $parentid The ID of the parent folder.
 244       * @return object Box.net file object.
 245       */
 246      public function upload_file(stored_file $storedfile, $parentid = 0) {
 247          $url = $this->make_url('/files/content', array(), true);
 248          $options = array(
 249              'filename' => $storedfile,
 250              'parent_id' => $parentid
 251          );
 252          $this->reset_state();
 253          $result = $this->post($url, $options);
 254          $result = json_decode($result);
 255          return $result;
 256      }
 257  
 258  }
 259  
 260  /**
 261   * @deprecated since 2.6, 2.5.3, 2.4.7
 262   */
 263  class boxclient {
 264      public function __construct() {
 265          throw new coding_exception(__CLASS__ . ' has been removed. Please update your code to use boxnet_client.',
 266              DEBUG_DEVELOPER);
 267      }
 268  }