You are here

Home » API reference » Dropbox Client 7.4 » dropbox.php

class dropbox in Dropbox Client 7.4

Same name and namespace in other branches
  1. 7 dropbox.php \dropbox
  2. 7.2 dropbox.php \dropbox
  3. 7.3 dropbox.php \dropbox

Hierarchy

Expanded class hierarchy of dropbox

4 string references to 'dropbox'
dropbox_client_access in ./dropbox_client.module
dropbox_client_connect in ./dropbox_client.module
dropbox_client_get_client in ./dropbox_client.module
dropbox_client_success in ./dropbox_client.module

File

./dropbox.php, line 25

View source 
class dropbox {
  const SCHEME = 'https';
  const HOST = 'api.dropbox.com';
  const AUTHORIZE_URI = '/oauth/authorize';
  const REQUEST_URI = '/oauth/request_token';
  const ACCESS_URI = '/oauth/access_token';
  const API_VERSION = '1';
  const HTTP_1 = '1.1';
  const LINE_END = "\r\n";
  const DEBUG = true;

  //Array that should contain the consumer secret and

  //key which should be passed into the constructor.
  private $_consumer = false;
  private $_access = false;
  private $_header = array(
    'Host' => self::HOST,
    'Connection' => 'close',
    'User-Agent' => 'Drupal',
    'Accept-encoding' => 'identity',
  );

  /**
   * Pass in a parameters array which should look as follows:
   * array('key'=>'example.com', 'secret'=>'mysecret');
   * Note that the secret should either be a hash string for
   * HMAC signatures or a file path string for RSA signatures.
   *
   * @param array $params
   */
  public function dropbox($params) {
    if (!array_key_exists('method', $params)) {
      $params['method'] = 'GET';
    }
    $params['algorithm'] = OAUTH_ALGORITHMS::HMAC_SHA1;

    //Only thing available in dropbox

    //$params['algorithm'] = OAUTH_ALGORITHMS::PLAINTEXT;
    $this->_consumer = array_diff_key($params, array(
      'access' => 0,
    ));
    if (array_key_exists('access', $params)) {
      $this->_access = $params['access'];
    }
  }

  /**
   * Sets OAuth access data to authenticate a user with dropbox.
   *
   * @param array $access an array of the form
   *                      array('oauth_token'=>url encoded token,'oauth_token_secret'=>url encoded secret)
   **/
  public function set_oauth_access(array $access) {
    $this->_access = $access;
  }

  /**
   * This is called to begin the oauth token exchange. This should only
   * need to be called once for a user, provided they allow oauth access.
   * It will return a URL that your site should redirect to, allowing the
   * user to login and accept your application.
   *
   * @param string $callback the page on your site you wish to return to
   *                         after the user grants your application access.
   * @return mixed either the URL to redirect to, or if they specified HMAC
   *         signing an array with the token_secret and the redirect url
   */
  public function get_request_token($callback) {
    $baseurl = self::SCHEME . '://' . self::HOST . '/' . self::API_VERSION . self::REQUEST_URI;

    //Generate an array with the initial oauth values we need
    $auth = build_auth_array($baseurl, $this->_consumer['key'], $this->_consumer['secret'], array(), $this->_consumer['method'], $this->_consumer['algorithm']);

    //Create the "Authorization" portion of the header
    $str = "";
    foreach ($auth as $key => $value) {
      $str .= ",{$key}=\"{$value}\"";
    }
    $str = 'Authorization: OAuth ' . substr($str, 1);

    //Send it
    $response = $this
      ->_connect($baseurl, $str, $this->_consumer['method']);

    //We should get back a request token and secret which

    //we will add to the redirect url.
    parse_str($response, $resarray);
    $callback = urlencode($callback);

    //Return the full redirect url and let the user decide what to do from there.
    $redirect = self::SCHEME . '://www.dropbox.com/' . self::API_VERSION . self::AUTHORIZE_URI . "?oauth_token={$resarray['oauth_token']}&oauth_callback={$callback}";
    return array(
      'token_secret' => $resarray['oauth_token_secret'],
      'redirect' => $redirect,
    );
  }

  /**
   * This is called to finish the oauth token exchange. This too should
   * only need to be called once for a user. The token returned should
   * be stored in your database for that particular user.
   *
   * @param string $token this is the oauth_token returned with your callback url
   * @param string $secret this is the token secret supplied from the request (Only required if using HMAC)
   * @param string $verifier this is the oauth_verifier returned with your callback url
   * @return array access token and token secret
   */
  public function get_access_token($secret, $token = false, $verifier = false) {

    //If no request token was specified then attempt to get one from the url
    if ($token === false && isset($_GET['oauth_token'])) {
      $token = $_GET['oauth_token'];
    }
    if ($verifier === false && isset($_GET['oauth_verifier'])) {
      $verifier = $_GET['oauth_verifier'];
    }

    //If all else fails attempt to get it from the request uri.
    if ($token === false && $verifier === false) {
      $uri = $_SERVER['REQUEST_URI'];
      $uriparts = explode('?', $uri);
      $authfields = array();
      parse_str($uriparts[1], $authfields);
      $token = $authfields['oauth_token'];
      $verifier = $authfields['oauth_verifier'];
    }
    $tokenddata = array(
      'oauth_token' => urlencode($token),
      'oauth_verifier' => urlencode($verifier),
    );
    if ($secret !== false) {
      $tokenddata['oauth_token_secret'] = urlencode($secret);
    }
    $baseurl = self::SCHEME . '://' . self::HOST . '/' . self::API_VERSION . self::ACCESS_URI;

    //Include the token and verifier into the header request.
    $auth = get_auth_header($baseurl, $this->_consumer['key'], $this->_consumer['secret'], $tokenddata, $this->_consumer['method'], $this->_consumer['algorithm'], $this->_access['oauth_token'], $this->_access['oauth_token_secret']);
    $response = $this
      ->_connect($baseurl, $auth, $this->_consumer['method']);

    //Parse the response into an array it should contain

    //both the access token and the secret key. (You only

    //need the secret key if you use HMAC-SHA1 signatures.)
    parse_str($response, $oauth);
    $this->_access = $oauth;

    //Return the token and secret for storage
    return $oauth;
  }

  /**
   * Retrieve information about the authenticated users account.
   *
   * @return a response object
   **/
  public function account() {
    return $this
      ->_response_request('/account/info');
  }

  /**
   * Retrieve a file from the currently authenticated user's dropbox
   * account. Note: The path should be relative to the root dropbox
   * folder and the destination should be relative to your sites root
   * folder.
   *
   * @param string $destination The path to create the new file
   * @param string $path The path to the file or folder in question.
   * @param string $root Either 'dropbox' or 'sandbox'
   * @return a response object.
   **/
  public function get($destination, $path, $root = 'dropbox') {
    $path = str_replace(' ', '%20', $path);
    return $this
      ->_content_request("/files/{$root}/{$path}", $destination);
  }

  /**
   * Retrieve thumbnail data from image files at specified path.
   *
   * @param string $destination The path to create the thumbnail image.
   * @param string $path The path to the image file or folder.
   * @param array $params (optional) Consult the Dropbox API documentation for more details
   * @param string root Either 'dropbox' or 'sandbox'
   **/
  public function thumbnails($destination, $path, array $params = array(
    'size' => 'small',
    'format' => 'JPEG',
  ), $root = 'dropbox') {
    $path = str_replace(' ', '%20', $path);
    $parstr = http_build_query($params);
    return $this
      ->_content_request("/thumbnails/{$root}/{$path}?{$parstr}", $destination);
  }

  /**
   * Adds a local file to the authenticated user's dropbox account using the post method
   *
   * @param string $dbpath The location in the user's dropbox to place the file.
   * @param string $filepath The relative path on the server of the file to upload.
   * @param array $params (optional) Consult the Dropbox API documentation for more details
   * @param string $root Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function add($dbpath, $filepath, array $params = array(), $root = 'dropbox') {
    $dbpath = str_replace(' ', '%20', $dbpath);
    $filename = rawurlencode($filepath);
    $parstr = empty($params) ? '' : '&' . http_build_query($params);
    $uri = preg_replace("#(^|[^:])//+#", "\\1/", "/files/{$root}/{$dbpath}?file={$filename}{$parstr}");
    $specialhost = 'api-content.dropbox.com';
    return $this
      ->_post_request($uri, array(
      'file' => '@' . $filepath,
    ), $specialhost);
  }

  /**
   * Retrieve metadata information about files or folders in the currently
   * authenticated user's dropbox account. Note: The path should be relative
   * to the root dropbox folder.
   *
   * @param string $path The path to the file or folder in question.
   * @param array $params (optional) Consult the Dropbox API documentation for more details
   * @param string $root Either 'dropbox' or 'sandbox'
   * @return a response object.
   **/
  public function metadata($path, array $params = array(), $root = 'dropbox') {
    $path = str_replace(' ', '%20', $path);
    $parstr = empty($params) ? '' : '?' . http_build_query($params);
    return $this
      ->_response_request("/metadata/{$root}/{$path}{$parstr}");
  }

  /**
   * Retrieve revision data about files or folders in the currently
   * authenticated user's dropbox account. Note: The path should be relative
   * to the root drop box folder.
   *
   * @param string $path The path to the file or folder in question
   * @param array $params (optional) Consult the Dropbox API documentation for more details
   * @param string $root (optional) Either 'dropbox' or 'sandbox'
   * @return a response object.
   **/
  public function revisions($path, array $params = array(), $root = 'dropbox') {
    $path = str_replace(' ', '%20', $path);
    $parstr = empty($params) ? '' : '?' . http_build_query($params);
    return $this
      ->_response_request("/revisions/{$root}/{$path}{$parstr}");
  }

  /**
   * Restore a file or folder to a previous revision.
   *
   * @param string $path The path to the file or folder in question
   * @param string $revision The rev hash to revert to.
   * @param string $root (optional) Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function restore($path, $revision, $root = 'dropbox') {
    $path = str_replace(' ', '%20', $path);
    return $this
      ->_post_request("/restore/{$root}/{$path}?rev={$revision}");
  }

  /**
   * Retrieve metadata for all files and folders that match the search query
   *
   * @param string $path The path to the file or folder in question
   * @param string $query The search query must be at least 3 characters in length
   * @param array $params (optional) Consult the Dropbox API documentation for more details
   * @param strint $root (optional) Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function search($path, $query, array $params = array(), $root = 'dropbox') {
    $path = str_replace(' ', '%20', $path);
    $query = rawurlencode($query);
    $parstr = empty($params) ? '' : '&' . http_build_query($params);
    return $this
      ->_response_request("/search/{$root}/{$path}?query={$query}{$parstr}");
  }

  /**
   * Retrieve a shareable link to files or folders. The link can be used
   * publicly and directs to a preview page of the file. Also returns the
   * link's expiration date.
   *
   * @param string $path The path to the file or folder in question
   * @param strint $root (optional) Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function shares($path, $root = 'dropbox') {
    $path = str_replace(' ', '%20', $path);
    return $this
      ->_response_request("/shares/{$root}/{$path}");
  }

  /**
   * Retrieve a link directly to a file.
   *
   * @param string $path The path to the file or folder in question
   * @param strint $root (optional) Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function media($path, $root = 'dropbox') {
    $path = implode("/", array_map("rawurlencode", explode("/", $path)));
    return $this
      ->_response_request("/media/{$root}/{$path}");
  }

  /**
   * Copies a file or folder in dropbox to another location within dropbox.
   *
   * @param string $from The relative path to the file to be copied.
   * @param string $to The relative path (Including file or folder name) to place to copy.
   * @param string $root Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function copy($from, $to, $root = 'dropbox') {
    return $this
      ->_response_request('/fileops/copy?from_path=' . rawurlencode($from) . '&to_path=' . rawurlencode($to) . '&root=' . $root);
  }

  /**
   * Create a folder relative to the user's Dropbox root or the user's
   * application sandbox folder.
   *
   * @param string $path The path to the new folder to create.
   * @param string $root Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function create_folder($path, $root = 'dropbox') {
    return $this
      ->_response_request('/fileops/create_folder?path=' . rawurlencode($path) . '&root=' . $root);
  }

  /**
   * Delete a folder or file relative to the user's Dropbox root or
   * the user's application sandbox folder.
   *
   * @param string $path The path to the folder or file to delete.
   * @param string $root Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function delete($path, $root = 'dropbox') {
    return $this
      ->_response_request('/fileops/delete?path=' . rawurlencode($path) . '&root=' . $root);
  }

  /**
   * Copies a file or folder in dropbox to another location within dropbox.
   *
   * @param string $from The relative path to the file to be moved.
   * @param string $to The relative path (Including file or folder name) to the new location.
   * @param string $root Either 'dropbox' or 'sandbox'
   * @return a response object
   **/
  public function move($from, $to, $root = 'dropbox') {
    return $this
      ->_response_request('/fileops/move?from_path=' . rawurlencode($from) . '&to_path=' . rawurlencode($to) . '&root=' . $root);
  }

  ////////////////////////////////////////////////////////////////////////////////////////////////

  // Below are the private methods used to create and send the requests to the dropbox api server.

  ////////////////////////////////////////////////////////////////////////////////////////////////
  private function _post_request($uri, $data = false, $specialhost = false) {
    $request = "POST {$uri} HTTP/" . self::HTTP_1 . self::LINE_END;
    $host = self::HOST;
    $extra = array();
    if ($specialhost !== false) {
      $host = $specialhost;
      $extra['Host'] = $specialhost;
    }
    $url = self::SCHEME . "://{$host}/" . self::API_VERSION . $uri;
    $header = $this
      ->_build_header($url, 'POST', $request, self::LINE_END, $extra);
    if (self::DEBUG) {
      error_log($header);
    }
    $response = $this
      ->_connect($url, $header, 'POST', $data);
    return json_decode($response);
  }
  private function _content_request($uri, $destination) {
    $uri = preg_replace("#(^|[^:])//+#", "\\1/", '/' . self::API_VERSION . $uri);
    $request = "GET {$uri} HTTP/" . self::HTTP_1 . self::LINE_END;
    $specialhost = 'api-content.dropbox.com';
    $url = self::SCHEME . '://' . $specialhost . $uri;
    $header = $this
      ->_build_header($url, 'GET', $request, self::LINE_END, array(
      'Host' => $specialhost,
    ));
    if (self::DEBUG) {
      error_log($header);
    }
    $this
      ->_connect($url, $header, 'GET', false, $destination);
  }
  private function _response_request($uri, $algo = OAUTH_ALGORITHMS::HMAC_SHA1) {

    #$uri =  ('/'.self::API_VERSION.$uri);
    $uri = preg_replace("#(^|[^:])//+#", "\\1/", '/' . self::API_VERSION . $uri);
    $request = "GET {$uri} HTTP/" . self::HTTP_1 . self::LINE_END;
    $url = self::SCHEME . '://' . self::HOST . $uri;
    $header = $this
      ->_build_header($url, 'GET', $request, self::LINE_END, array(), $algo);
    if (self::DEBUG) {
      error_log($header);
    }
    $response = $this
      ->_connect($url, $header, 'GET');
    return json_decode($response);
  }
  private function _build_header($url, $method, $prepend, $append, $overwrite = array(), $algo = OAUTH_ALGORITHMS::HMAC_SHA1) {
    $str = $prepend === false ? '' : $prepend;
    foreach ($this->_header as $key => $value) {
      if (array_key_exists($key, $overwrite)) {
        $str .= $key . ': ' . $overwrite[$key] . self::LINE_END;
      }
      else {
        $str .= $key . ': ' . $value . self::LINE_END;
      }
    }
    if ($this->_access !== false && $url !== false) {
      $str .= get_auth_header($url, $this->_consumer['key'], $this->_consumer['secret'], $this->_access, $method, isset($algo) ? $algo : $this->_consumer['algorithm'], $this->_access['oauth_token'], $this->_access['oauth_token_secret']);
    }
    $str .= $append === false ? '' : $append;
    return $str;
  }
  private function _connect($url, $header, $request, $postdata = false, $destination = false) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $request);
    curl_setopt($ch, CURLOPT_HTTPHEADER, explode(self::LINE_END, $header));
    curl_setopt($ch, CURLINFO_HEADER_OUT, true);
    if (is_array($postdata)) {
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata);
    }
    $response = curl_exec($ch);
    if (self::DEBUG) {
      error_log(print_r(curl_getinfo($ch), true));
      error_log($response);
    }

    //If the specified a destination and the request went OK write the file.
    if ($destination !== false && curl_getinfo($ch, CURLINFO_HTTP_CODE) == '200') {
      $fh = fopen($destination, 'w');
      fwrite($fh, $response);
      if ($fh !== false) {
        fclose($fh);
      }
    }
    curl_close($ch);
    return $response;
  }

}

Members

Namesort descending Modifiers Type Description Overrides
dropbox::$_access private property
dropbox::$_consumer private property
dropbox::$_header private property
dropbox::ACCESS_URI constant
dropbox::account public function Retrieve information about the authenticated users account.
dropbox::add public function Adds a local file to the authenticated user's dropbox account using the post method
dropbox::API_VERSION constant
dropbox::AUTHORIZE_URI constant
dropbox::copy public function Copies a file or folder in dropbox to another location within dropbox.
dropbox::create_folder public function Create a folder relative to the user's Dropbox root or the user's application sandbox folder.
dropbox::DEBUG constant
dropbox::delete public function Delete a folder or file relative to the user's Dropbox root or the user's application sandbox folder.
dropbox::dropbox public function Pass in a parameters array which should look as follows: array('key'=>'example.com', 'secret'=>'mysecret'); Note that the secret should either be a hash string for HMAC signatures or a file path string for…
dropbox::get public function Retrieve a file from the currently authenticated user's dropbox account. Note: The path should be relative to the root dropbox folder and the destination should be relative to your sites root folder.
dropbox::get_access_token public function This is called to finish the oauth token exchange. This too should only need to be called once for a user. The token returned should be stored in your database for that particular user.
dropbox::get_request_token public function This is called to begin the oauth token exchange. This should only need to be called once for a user, provided they allow oauth access. It will return a URL that your site should redirect to, allowing the user to login and accept your application.
dropbox::HOST constant
dropbox::HTTP_1 constant
dropbox::LINE_END constant
dropbox::media public function Retrieve a link directly to a file.
dropbox::metadata public function Retrieve metadata information about files or folders in the currently authenticated user's dropbox account. Note: The path should be relative to the root dropbox folder.
dropbox::move public function Copies a file or folder in dropbox to another location within dropbox.
dropbox::REQUEST_URI constant
dropbox::restore public function Restore a file or folder to a previous revision.
dropbox::revisions public function Retrieve revision data about files or folders in the currently authenticated user's dropbox account. Note: The path should be relative to the root drop box folder.
dropbox::SCHEME constant
dropbox::search public function Retrieve metadata for all files and folders that match the search query
dropbox::set_oauth_access public function Sets OAuth access data to authenticate a user with dropbox.
dropbox::shares public function Retrieve a shareable link to files or folders. The link can be used publicly and directs to a preview page of the file. Also returns the link's expiration date.
dropbox::thumbnails public function Retrieve thumbnail data from image files at specified path.
dropbox::_build_header private function
dropbox::_connect private function
dropbox::_content_request private function
dropbox::_post_request private function
dropbox::_response_request private function