%PDF- %PDF-
Direktori : /home/emergentqj/jugement/wp-content/plugins/backup-guard-platinum/com/lib/Dropbox/ |
Current File : /home/emergentqj/jugement/wp-content/plugins/backup-guard-platinum/com/lib/Dropbox/Client.php |
<?php namespace Dropbox; /** * The class used to make most Dropbox API calls. You can use this once you've gotten an * {@link AccessToken} via {@link WebAuth}. * * This class is stateless so it can be shared/reused. */ class Client { /** * The access token used by this client to make authenticated API calls. You can get an * access token via {@link WebAuth}. * * @return AccessToken */ function getAccessToken() { return $this->accessToken; } /** @var AccessToken */ private $accessToken; /** * An identifier for the API client, typically of the form "Name/Version". * This is used to set the HTTP <code>User-Agent</code> header when making API requests. * Example: <code>"PhotoEditServer/1.3"</code> * * If you're the author a higher-level library on top of the basic SDK, and the * "Photo Edit" app's server code is using your library to access Dropbox, you should append * your library's name and version to form the full identifier. For example, * if your library is called "File Picker", you might set this field to: * <code>"PhotoEditServer/1.3 FilePicker/0.1-beta"</code> * * The exact format of the <code>User-Agent</code> header is described in * <a href="http://tools.ietf.org/html/rfc2616#section-3.8">section 3.8 of the HTTP specification</a>. * * Note that underlying HTTP client may append other things to the <code>User-Agent</code>, such as * the name of the library being used to actually make the HTTP request (such as cURL). * * @return string */ function getClientIdentifier() { return $this->clientIdentifier; } /** @var string */ private $clientIdentifier; /** * The locale of the user of your application. Some API calls return localized * data and error messages; this "user locale" setting determines which locale * the server should use to localize those strings. * * @return null|string */ function getUserLocale() { return $this->userLocale; } /** @var null|string */ private $userLocale; /** * The {@link Host} object that determines the hostnames we make requests to. * * @return Host */ function getHost() { return $this->host; } /** * Constructor. * * @param string $accessToken * See {@link getAccessToken()} * @param string $clientIdentifier * See {@link getClientIdentifier()} * @param null|string $userLocale * See {@link getUserLocale()} */ function __construct($accessToken, $clientIdentifier, $userLocale = null) { self::checkAccessTokenArg("accessToken", $accessToken); self::checkClientIdentifierArg("clientIdentifier", $clientIdentifier); Checker::argStringNonEmptyOrNull("userLocale", $userLocale); $this->accessToken = $accessToken; $this->clientIdentifier = $clientIdentifier; $this->userLocale = $userLocale; // The $host parameter is sort of internal. We don't include it in the param list because // we don't want it to be included in the documentation. Use PHP arg list hacks to get at // it. $host = null; if (\func_num_args() == 4) { $host = \func_get_arg(3); Host::checkArgOrNull("host", $host); } if ($host === null) { $host = Host::getDefault(); } $this->host = $host; // These fields are redundant, but it makes these values a little more convenient // to access. $this->apiHost = $host->getApi(); $this->contentHost = $host->getContent(); } /** @var string */ private $apiHost; /** @var string */ public $contentHost; /** * Given a <code>$base</code> path for an API endpoint (for example, "/files"), append * a Dropbox API file path to the end of that URL. Special characters in the file will * be encoded properly. * * This is for endpoints like "/files" takes the path on the URL and not as a separate * query or POST parameter. * * @param string $base * @param string $path * @return string */ function appendFilePath($base, $path) { return $base . "/auto/" . rawurlencode(substr($path, 1)); } /** * Make an API call to disable the access token that you constructed this <code>Client</code> * with. After calling this, API calls made with this <code>Client</code> will fail. * * See <a href="https://www.dropbox.com/developers/core/docs#disable-token">/disable_access_token</a>. * * @throws Exception */ // function disableAccessToken() // { // $response = $this->doPost($this->apiHost, "1/disable_access_token"); // if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); // } /*Dropbox api 2*/ function disableAccessToken() { $response = $this->doPost($this->apiHost, "2/auth/token/revoke"); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); } /** * Make an API call to get basic account and quota information. * * <code> * $client = ... * $accountInfo = $client->getAccountInfo(); * print_r($accountInfo); * </code> * * @return array * See <a href="https://www.dropbox.com/developers/core/docs#account-info">/account/info</a>. * * @throws Exception */ // function getAccountInfo() // { // $response = $this->doGet($this->apiHost, "1/account/info"); // if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); // return RequestUtil::parseResponseJson($response->body); // } /*Dropbox api 2*/ function getAccountInfo() { $response = $this->doPost( $this->apiHost, "2/users/get_current_account", null, "Content-Type: application/json" ); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Downloads a file from Dropbox. The file's contents are written to the * given <code>$outStream</code> and the file's metadata is returned. * * <code> * $client = ...; * $fd = fopen("./Frog.jpeg", "wb"); * $metadata = $client->getFile("/Photos/Frog.jpeg", $fd); * fclose($fd); * print_r($metadata); * </code> * * @param string $path * The path to the file on Dropbox (UTF-8). * * @param resource $outStream * If the file exists, the file contents will be written to this stream. * * @param string|null $rev * If you want the latest revision of the file at the given path, pass in <code>null</code>. * If you want a specific version of a file, pass in value of the file metadata's "rev" field. * * @return null|array * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata * object</a> for the file at the given $path and $rev, or <code>null</code> if the file * doesn't exist, * * @throws Exception */ function getFile($path, $outStream, $rev = null) { Path::checkArgNonRoot("path", $path); Checker::argResource("outStream", $outStream); Checker::argStringNonEmptyOrNull("rev", $rev); $url = $this->buildUrlForGetOrPut( $this->contentHost, $this->appendFilePath("1/files", $path), array("rev" => $rev)); $curl = $this->mkCurl($url); $metadataCatcher = new DropboxMetadataHeaderCatcher($curl->handle); $streamRelay = new CurlStreamRelay($curl->handle, $outStream); $response = $curl->exec(); if ($response->statusCode === 404) return null; if ($response->statusCode !== 200) { $response->body = $streamRelay->getErrorBody(); throw RequestUtil::unexpectedStatus($response); } return $metadataCatcher->getMetadata(); } /** * Calling 'uploadFile' with <code>$numBytes</code> less than this value, will cause this SDK * to use the standard /files_put endpoint. When <code>$numBytes</code> is greater than this * value, we'll use the /chunked_upload endpoint. * * @var int */ private static $AUTO_CHUNKED_UPLOAD_THRESHOLD = 9863168; // 8 MB /** * @var int */ private static $DEFAULT_CHUNK_SIZE = 4194304; // 4 MB /** * Creates a file on Dropbox, using the data from <code>$inStream</code> for the file contents. * * <code> * use \Dropbox as dbx; * $client = ...; * $fd = fopen("./frog.jpeg", "rb"); * $md1 = $client->uploadFile("/Photos/Frog.jpeg", * dbx\WriteMode::add(), $fd); * fclose($fd); * print_r($md1); * $rev = $md1["rev"]; * * // Re-upload with WriteMode::update(...), which will overwrite the * // file if it hasn't been modified from our original upload. * $fd = fopen("./frog-new.jpeg", "rb"); * $md2 = $client->uploadFile("/Photos/Frog.jpeg", * dbx\WriteMode::update($rev), $fd); * fclose($fd); * print_r($md2); * </code> * * @param string $path * The Dropbox path to save the file to (UTF-8). * * @param WriteMode $writeMode * What to do if there's already a file at the given path. * * @param resource $inStream * The data to use for the file contents. * * @param int|null $numBytes * You can pass in <code>null</code> if you don't know. If you do provide the size, we can * perform a slightly more efficient upload (fewer network round-trips) for files smaller * than 8 MB. * * @return mixed * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata * object</a> for the newly-added file. * * @throws Exception */ function uploadFile($path, $writeMode, $inStream, $numBytes = null) { Path::checkArgNonRoot("path", $path); WriteMode::checkArg("writeMode", $writeMode); Checker::argResource("inStream", $inStream); Checker::argNatOrNull("numBytes", $numBytes); // If we don't know how many bytes are coming, we have to use chunked upload. // If $numBytes is large, we elect to use chunked upload. // In all other cases, use regular upload. if ($numBytes === null || $numBytes > self::$AUTO_CHUNKED_UPLOAD_THRESHOLD) { $metadata = $this->_uploadFileChunked($path, $writeMode, $inStream, $numBytes, self::$DEFAULT_CHUNK_SIZE); } else { $metadata = $this->_uploadFile($path, $writeMode, function(Curl $curl) use ($inStream, $numBytes) { $curl->set(CURLOPT_PUT, true); $curl->set(CURLOPT_INFILE, $inStream); $curl->set(CURLOPT_INFILESIZE, $numBytes); }); } return $metadata; } /** * Creates a file on Dropbox, using the given $data string as the file contents. * * <code> * use \Dropbox as dbx; * $client = ...; * $md = $client->uploadFileFromString("/Grocery List.txt", * dbx\WriteMode::add(), * "1. Coke\n2. Popcorn\n3. Toothpaste\n"); * print_r($md); * </code> * * @param string $path * The Dropbox path to save the file to (UTF-8). * * @param WriteMode $writeMode * What to do if there's already a file at the given path. * * @param string $data * The data to use for the contents of the file. * * @return mixed * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata * object</a> for the newly-added file. * * @throws Exception */ function uploadFileFromString($path, $writeMode, $data) { Path::checkArgNonRoot("path", $path); WriteMode::checkArg("writeMode", $writeMode); Checker::argString("data", $data); return $this->_uploadFile($path, $writeMode, function(Curl $curl) use ($data) { $curl->set(CURLOPT_CUSTOMREQUEST, "PUT"); $curl->set(CURLOPT_POSTFIELDS, $data); $curl->addHeader("Content-Type: application/octet-stream"); }); } /** * Creates a file on Dropbox, using the data from $inStream as the file contents. * * This version of <code>uploadFile</code> splits uploads the file ~4MB chunks at a time and * will retry a few times if one chunk fails to upload. Uses {@link chunkedUploadStart()}, * {@link chunkedUploadContinue()}, and {@link chunkedUploadFinish()}. * * @param string $path * The Dropbox path to save the file to (UTF-8). * * @param WriteMode $writeMode * What to do if there's already a file at the given path. * * @param resource $inStream * The data to use for the file contents. * * @param int|null $numBytes * The number of bytes available from $inStream. * You can pass in <code>null</code> if you don't know. * * @param int|null $chunkSize * The number of bytes to upload in each chunk. You can omit this (or pass in * <code>null</code> and the library will use a reasonable default. * * @return mixed * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata * object</a> for the newly-added file. * * @throws Exception */ function uploadFileChunked($path, $writeMode, $inStream, $numBytes = null, $chunkSize = null) { if ($chunkSize === null) { $chunkSize = self::$DEFAULT_CHUNK_SIZE; } Path::checkArgNonRoot("path", $path); WriteMode::checkArg("writeMode", $writeMode); Checker::argResource("inStream", $inStream); Checker::argNatOrNull("numBytes", $numBytes); Checker::argIntPositive("chunkSize", $chunkSize); return $this->_uploadFileChunked($path, $writeMode, $inStream, $numBytes, $chunkSize); } /** * @param string $path * * @param WriteMode $writeMode * What to do if there's already a file at the given path (UTF-8). * * @param resource $inStream * The source of data to upload. * * @param int|null $numBytes * You can pass in <code>null</code>. But if you know how many bytes you expect, pass in * that value and this function will do a sanity check at the end to make sure the number of * bytes read from $inStream matches up. * * @param int $chunkSize * * @return array * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata * object</a> for the newly-added file. */ private function _uploadFileChunked($path, $writeMode, $inStream, $numBytes, $chunkSize) { Path::checkArg("path", $path); WriteMode::checkArg("writeMode", $writeMode); Checker::argResource("inStream", $inStream); Checker::argNatOrNull("numBytes", $numBytes); Checker::argNat("chunkSize", $chunkSize); // NOTE: This function performs 3 retries on every call. This is maybe not the right // layer to make retry decisions. It's also awkward because none of the other calls // perform retries. assert($chunkSize > 0); $data = self::readFully($inStream, $chunkSize); $len = strlen($data); $client = $this; $uploadId = RequestUtil::runWithRetry(3, function() use ($data, $client) { return $client->chunkedUploadStart($data); }); $byteOffset = $len; while (!feof($inStream)) { $data = self::readFully($inStream, $chunkSize); $len = strlen($data); while (true) { $r = RequestUtil::runWithRetry(3, function() use ($client, $uploadId, $byteOffset, $data) { return $client->chunkedUploadContinue($uploadId, $byteOffset, $data); }); if ($r === true) { // Chunk got uploaded! $byteOffset += $len; break; } if ($r === false) { // Server didn't recognize our upload ID // This is very unlikely since we're uploading all the chunks in sequence. throw new Exception_BadResponse("Server forgot our uploadId"); } // Otherwise, the server is at a different byte offset from us. $serverByteOffset = $r; assert($serverByteOffset !== $byteOffset); // chunkedUploadContinue ensures this. // An earlier byte offset means the server has lost data we sent earlier. if ($serverByteOffset < $byteOffset) throw new Exception_BadResponse( "Server is at an ealier byte offset: us=$byteOffset, server=$serverByteOffset"); $diff = $serverByteOffset - $byteOffset; // If the server is past where we think it could possibly be, something went wrong. if ($diff > $len) throw new Exception_BadResponse( "Server is more than a chunk ahead: us=$byteOffset, server=$serverByteOffset"); // The normal case is that the server is a bit further along than us because of a // partially-uploaded chunk. Finish it off. $byteOffset += $diff; if ($diff === $len) break; // If the server is at the end, we're done. $data = substr($data, $diff); } } if ($numBytes !== null && $byteOffset !== $numBytes) throw new \InvalidArgumentException( "You passed numBytes=$numBytes but the stream had $byteOffset bytes."); $metadata = RequestUtil::runWithRetry(3, function() use ($client, $uploadId, $path, $writeMode) { return $client->chunkedUploadFinish($uploadId, $path, $writeMode); }); return $metadata; } /** * Sometimes fread() returns less than the request number of bytes (for example, when reading * from network streams). This function repeatedly calls fread until the requested number of * bytes have been read or we've reached EOF. * * @param resource $inStream * @param int $numBytes * @throws StreamReadException * @return string */ private static function readFully($inStream, $numBytes) { Checker::argNat("numBytes", $numBytes); $full = ''; $bytesRemaining = $numBytes; while (!feof($inStream) && $bytesRemaining > 0) { $part = fread($inStream, $bytesRemaining); if ($part === false) throw new StreamReadException("Error reading from \$inStream."); $full .= $part; $bytesRemaining -= strlen($part); } return $full; } /** * @param string $path * @param WriteMode $writeMode * @param callable $curlConfigClosure * @return array */ private function _uploadFile($path, $writeMode, $curlConfigClosure) { Path::checkArg("path", $path); WriteMode::checkArg("writeMode", $writeMode); Checker::argCallable("curlConfigClosure", $curlConfigClosure); $url = $this->buildUrlForGetOrPut( $this->contentHost, $this->appendFilePath("1/files_put", $path), $writeMode->getExtraParams()); $curl = $this->mkCurl($url); $curlConfigClosure($curl); $curl->set(CURLOPT_RETURNTRANSFER, true); $response = $curl->exec(); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Start a new chunked upload session and upload the first chunk of data. * * @param string $data * The data to start off the chunked upload session. * * @return array * A pair of <code>(string $uploadId, int $byteOffset)</code>. <code>$uploadId</code> * is a unique identifier for this chunked upload session. You pass this in to * {@link chunkedUploadContinue} and {@link chuunkedUploadFinish}. <code>$byteOffset</code> * is the number of bytes that were successfully uploaded. * * @throws Exception */ function chunkedUploadStart($data) { Checker::argString("data", $data); $response = $this->_chunkedUpload(array(), $data); if ($response->statusCode === 404) { throw new Exception_BadResponse("Got a 404, but we didn't send up an 'session_id'"); } $correction = self::_chunkedUploadCheckForOffsetCorrection($response); if ($correction !== null) throw new Exception_BadResponse( "Got an offset-correcting 400 response, but we didn't send an offset"); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); $uploadId = self::_chunkedUploadParse200Response($response->body); $len = strlen($data); return $uploadId; } /** * Append another chunk data to a previously-started chunked upload session. * * @param string $uploadId * The unique identifier for the chunked upload session. This is obtained via * {@link chunkedUploadStart}. * * @param int $byteOffset * The number of bytes you think you've already uploaded to the given chunked upload * session. The server will append the new chunk of data after that point. * * @param string $data * The data to append to the existing chunked upload session. * * @return int|bool * If <code>false</code>, it means the server didn't know about the given * <code>$uploadId</code>. This may be because the chunked upload session has expired * (they last around 24 hours). * If <code>true</code>, the chunk was successfully uploaded. If an integer, it means * you and the server don't agree on the current <code>$byteOffset</code>. The returned * integer is the server's internal byte offset for the chunked upload session. You need * to adjust your input to match. * * @throws Exception */ // function chunkedUploadContinue($uploadId, $byteOffset, $data) // { // Checker::argStringNonEmpty("uploadId", $uploadId); // Checker::argNat("byteOffset", $byteOffset); // Checker::argString("data", $data); // $response = $this->_chunkedUpload( // array("upload_id" => $uploadId, "offset" => $byteOffset), $data); // if ($response->statusCode === 404) { // // The server doesn't know our upload ID. Maybe it expired? // return false; // } // $correction = self::_chunkedUploadCheckForOffsetCorrection($response); // if ($correction !== null) { // list($correctedUploadId, $correctedByteOffset) = $correction; // if ($correctedUploadId !== $uploadId) throw new Exception_BadResponse( // "Corrective 400 upload_id mismatch: us=". // Util::q($uploadId)." server=".Util::q($correctedUploadId)); // if ($correctedByteOffset === $byteOffset) throw new Exception_BadResponse( // "Corrective 400 offset is the same as ours: $byteOffset"); // return $correctedByteOffset; // } // if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); // list($retUploadId, $retByteOffset) = self::_chunkedUploadParse200Response($response->body); // $nextByteOffset = $byteOffset + strlen($data); // if ($uploadId !== $retUploadId) throw new Exception_BadResponse( // "upload_id mismatch: us=".Util::q($uploadId) .", server=".Util::q($uploadId)); // if ($nextByteOffset !== $retByteOffset) throw new Exception_BadResponse( // "next-offset mismatch: us=$nextByteOffset, server=$retByteOffset"); // return true; // } /*Dropbox api 2*/ function chunkedUploadContinue($uploadId, $byteOffset, $data) { Checker::argStringNonEmpty("session_id", $uploadId); Checker::argNat("byteOffset", $byteOffset); Checker::argString("data", $data); $response = $this->_chunkedUploadContinue( array( "cursor" => array( "session_id" => $uploadId, "offset" => $byteOffset ), "close" => false ), $data ); if ($response->statusCode === 404) { // The server doesn't know our upload ID. Maybe it expired? return false; } return true; } protected function _chunkedUploadContinue($params, $data) { $url = "https://content.dropboxapi.com/2/files/upload_session/append_v2"; $curl = $this->mkCurl($url); $curl->set(CURLOPT_CUSTOMREQUEST, "POST"); $curl->set(CURLOPT_POSTFIELDS, $data); $curl->addHeader("Content-Type: application/octet-stream"); $curl->addHeader("Dropbox-API-Arg: ".json_encode($params)); $curl->set(CURLOPT_RETURNTRANSFER, true); return $curl->exec(); } /** * @param string $body * @return array */ private static function _chunkedUploadParse200Response($body) { $j = RequestUtil::parseResponseJson($body); $uploadId = self::getField($j, "session_id"); return $uploadId; } /** * @param HttpResponse $response * @return array|null */ private static function _chunkedUploadCheckForOffsetCorrection($response) { if ($response->statusCode !== 400) return null; $j = json_decode($response->body, true, 10); if ($j === null) return null; if (!array_key_exists("session_id", $j)) return null; $uploadId = $j["session_id"]; return $uploadId; } /** * Creates a file on Dropbox using the accumulated contents of the given chunked upload session. * * See <a href="https://www.dropbox.com/developers/core/docs#commit-chunked-upload">/commit_chunked_upload</a>. * * @param string $uploadId * The unique identifier for the chunked upload session. This is obtained via * {@link chunkedUploadStart}. * * @param string $path * The Dropbox path to save the file to ($path). * * @param WriteMode $writeMode * What to do if there's already a file at the given path. * * @return array|null * If <code>null</code>, it means the Dropbox server wasn't aware of the * <code>$uploadId</code> you gave it. * Otherwise, you get back the * <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a> * for the newly-created file. * * @throws Exception */ // function chunkedUploadFinish($uploadId, $path, $writeMode) // { // Checker::argStringNonEmpty("uploadId", $uploadId); // Path::checkArgNonRoot("path", $path); // WriteMode::checkArg("writeMode", $writeMode); // $params = array_merge(array("upload_id" => $uploadId), $writeMode->getExtraParams()); // $response = $this->doPost( // $this->contentHost, // $this->appendFilePath("1/commit_chunked_upload", $path), // $params); // if ($response->statusCode === 404) return null; // if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); // return RequestUtil::parseResponseJson($response->body); // } /*Dropbox api 2*/ function chunkedUploadFinish($uploadId, $path, $offset) { Checker::argStringNonEmpty("session_id", $uploadId); Path::checkArgNonRoot("path", $path); $url = "https://content.dropboxapi.com/2/files/upload_session/finish"; $params = array( "cursor" => array( "session_id" => $uploadId, "offset" => $offset ), "commit" => array( "path" => $path, "mode" => "add", "autorename" => false, "mute" => false ) ); $curl = $this->mkCurl($url); $curl->set(CURLOPT_CUSTOMREQUEST, "POST"); $curl->addHeader("Content-Type: application/octet-stream"); $curl->addHeader("Dropbox-API-Arg: ".json_encode($params)); $curl->set(CURLOPT_RETURNTRANSFER, true); $response = $curl->exec(); if ($response->statusCode === 404) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * @param array $params * @param string $data * @return HttpResponse */ // protected function _chunkedUpload($params, $data) // // Marked 'protected' so I can override it in testing. // { // $url = $this->buildUrlForGetOrPut( // $this->contentHost, "1/chunked_upload", $params); // $curl = $this->mkCurl($url); // // We can't use CURLOPT_PUT because it wants a stream, but we already have $data in memory. // $curl->set(CURLOPT_CUSTOMREQUEST, "PUT"); // $curl->set(CURLOPT_POSTFIELDS, $data); // $curl->addHeader("Content-Type: application/octet-stream"); // $curl->set(CURLOPT_RETURNTRANSFER, true); // return $curl->exec(); // } /*Dropbox api 2*/ // Marked 'protected' so I can override it in testing. protected function _chunkedUpload($params, $data) { $url = "https://content.dropboxapi.com/2/files/upload_session/start"; $curl = $this->mkCurl($url); $curl->set(CURLOPT_CUSTOMREQUEST, "POST"); $curl->set(CURLOPT_POSTFIELDS, $data); $curl->addHeader("Content-Type: application/octet-stream"); $curl->set(CURLOPT_RETURNTRANSFER, true); $response = $curl->exec(); return $response; } /** * Returns the metadata for whatever file or folder is at the given path. * * <code> * $client = ...; * $md = $client->getMetadata("/Photos/Frog.jpeg"); * print_r($md); * </code> * * @param string $path * The Dropbox path to a file or folder (UTF-8). * * @return array|null * If there is a file or folder at the given path, you'll get back the * <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a> * for that file or folder. If not, you'll get back <code>null</code>. * * @throws Exception */ function getMetadata($path) { Path::checkArg("path", $path); return $this->_getMetadata($path, array("list" => "false")); } /** * Returns the metadata for whatever file or folder is at the given path and, if it's a folder, * also include the metadata for all the immediate children of that folder. * * <code> * $client = ...; * $md = $client->getMetadataWithChildren("/Photos"); * print_r($md); * </code> * * @param string $path * The Dropbox path to a file or folder (UTF-8). * * @return array|null * If there is a file or folder at the given path, you'll get back the * <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a> * for that file or folder, along with all immediate children if it's a folder. If not, * you'll get back <code>null</code>. * * @throws Exception */ // function getMetadataWithChildren($path) // { // Path::checkArg("path", $path); // return $this->_getMetadata($path, array("list" => "true", "file_limit" => "25000")); // } /*Dropbox api 2*/ function getMetadataWithChildren($path) { Path::checkArg("path", $path); $params = array( "path" => $path, "recursive" => false, "include_media_info" => false, "include_deleted" => false, "include_has_explicit_shared_members" => false ); return $this->_getMetadata($params); } /** * @param string $path * @param array $params * @return array */ // private function _getMetadata($path, $params) // { // $response = $this->doGet( // $this->apiHost, // $this->appendFilePath("1/metadata", $path), // $params); // if ($response->statusCode === 404) return null; // if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); // $metadata = RequestUtil::parseResponseJson($response->body); // if (array_key_exists("is_deleted", $metadata) && $metadata["is_deleted"]) return null; // return $metadata; // } /*Dropbox api 2*/ private function _getMetadata($params) { $response = $this->doPost($this->apiHost, "2/files/list_folder", $params, "Content-Type: application/json"); if ($response->statusCode === 404) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); $metadata = RequestUtil::parseResponseJson($response->body); if (array_key_exists("is_deleted", $metadata) && $metadata["is_deleted"]) return null; return $metadata; } /** * If you've previously retrieved the metadata for a folder and its children, this method will * retrieve updated metadata only if something has changed. This is more efficient than * calling {@link getMetadataWithChildren} if you have a cache of previous results. * * <code> * $client = ...; * $md = $client->getMetadataWithChildren("/Photos"); * print_r($md); * assert($md["is_dir"], "expecting \"/Photos\" to be a folder"); * * sleep(10); * * // Now see if anything changed... * list($changed, $new_md) = $client->getMetadataWithChildrenIfChanged( * "/Photos", $md["hash"]); * if ($changed) { * echo "Folder changed.\n"; * print_r($new_md); * } else { * echo "Folder didn't change.\n"; * } * </code> * * @param string $path * The Dropbox path to a folder (UTF-8). * * @param string $previousFolderHash * The "hash" field from the previously retrieved folder metadata. * * @return array * A <code>list(boolean $changed, array $metadata)</code>. If the metadata hasn't changed, * you'll get <code>list(false, null)</code>. If the metadata of the folder or any of its * children has changed, you'll get <code>list(true, $newMetadata)</code>. $metadata is a * <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a>. * * @throws Exception */ function getMetadataWithChildrenIfChanged($path, $previousFolderHash) { Path::checkArg("path", $path); Checker::argStringNonEmpty("previousFolderHash", $previousFolderHash); $params = array("list" => "true", "file_limit" => "25000", "hash" => $previousFolderHash); $response = $this->doGet( $this->apiHost, $this->appendFilePath("1/metadata", $path), $params); if ($response->statusCode === 304) return array(false, null); if ($response->statusCode === 404) return array(true, null); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); $metadata = RequestUtil::parseResponseJson($response->body); if (array_key_exists("is_deleted", $metadata) && $metadata["is_deleted"]) { return array(true, null); } return array(true, $metadata); } /** * A way of letting you keep up with changes to files and folders in a user's Dropbox. * * @param string|null $cursor * If this is the first time you're calling this, pass in <code>null</code>. Otherwise, * pass in whatever cursor was returned by the previous call. * * @param string|null $pathPrefix * If <code>null</code>, you'll get results for the entire folder (either the user's * entire Dropbox or your App Folder). If you set <code>$path_prefix</code> to * "/Photos/Vacation", you'll only get results for that path and any files and folders * under it. * * @return array * A <a href="https://www.dropbox.com/developers/core/docs#delta">delta page</a>, which * contains a list of changes to apply along with a new "cursor" that should be passed into * future <code>getDelta</code> calls. If the "reset" field is <code>true</code>, you * should clear your local state before applying the changes. If the "has_more" field is * <code>true</code>, call <code>getDelta</code> immediately to get more results, otherwise * wait a while (at least 5 minutes) before calling <code>getDelta</code> again. * * @throws Exception */ function getDelta($cursor = null, $pathPrefix = null) { Checker::argStringNonEmptyOrNull("cursor", $cursor); Path::checkArgOrNull("pathPrefix", $pathPrefix); $response = $this->doPost($this->apiHost, "1/delta", array( "cursor" => $cursor, "path_prefix" => $pathPrefix)); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Gets the metadata for all the file revisions (up to a limit) for a given path. * * See <a href="https://www.dropbox.com/developers/core/docs#revisions">/revisions</a>. * * @param string path * The Dropbox path that you want file revision metadata for (UTF-8). * * @param int|null limit * The maximum number of revisions to return. * * @return array|null * A list of <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata * objects</a>, one for each file revision. The later revisions appear first in the list. * If <code>null</code>, then there were too many revisions at that path. * * @throws Exception */ function getRevisions($path, $limit = null) { Path::checkArgNonRoot("path", $path); Checker::argIntPositiveOrNull("limit", $limit); $response = $this->doGet( $this->apiHost, $this->appendFilePath("1/revisions", $path), array("rev_limit" => $limit)); if ($response->statusCode === 406) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Takes a copy of the file at the given revision and saves it over the current copy. This * will create a new revision, but the file contents will match the revision you specified. * * See <a href="https://www.dropbox.com/developers/core/docs#restore">/restore</a>. * * @param string $path * The Dropbox path of the file to restore (UTF-8). * * @param string $rev * The revision to restore the contents to. * * @return mixed * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata * object</a> * * @throws Exception */ function restoreFile($path, $rev) { Path::checkArgNonRoot("path", $path); Checker::argStringNonEmpty("rev", $rev); $response = $this->doPost( $this->apiHost, $this->appendFilePath("1/restore", $path), array("rev" => $rev)); if ($response->statusCode === 404) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Returns metadata for all files and folders whose filename matches the query string. * * See <a href="https://www.dropbox.com/developers/core/docs#search">/search</a>. * * @param string $basePath * The path to limit the search to (UTF-8). Pass in "/" to search everything. * * @param string $query * A space-separated list of substrings to search for. A file matches only if it contains * all the substrings. * * @param int|null $limit * The maximum number of results to return. * * @param bool $includeDeleted * Whether to include deleted files in the results. * * @return mixed * A list of <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata * objects</a> of files that match the search query. * * @throws Exception */ // function searchFileNames($basePath, $query, $limit = null, $includeDeleted = false) // { // Path::checkArg("basePath", $basePath); // Checker::argStringNonEmpty("query", $query); // Checker::argNatOrNull("limit", $limit); // Checker::argBool("includeDeleted", $includeDeleted); // $response = $this->doPost( // $this->apiHost, // $this->appendFilePath("1/search", $basePath), // array( // "query" => $query, // "file_limit" => $limit, // "include_deleted" => $includeDeleted, // )); // if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); // return RequestUtil::parseResponseJson($response->body); // } /*Dropbox api 2*/ function searchFileNames($basePath, $query, $limit = null, $includeDeleted = false) { Path::checkArg("basePath", $basePath); Checker::argStringNonEmpty("query", $query); Checker::argNatOrNull("limit", $limit); Checker::argBool("includeDeleted", $includeDeleted); $response = $this->doPost( $this->apiHost, "2/files/search", array( "path" => $basePath, "query" => $query, "start" => 0, "max_results" => 200, "mode" => "filename" ), "Content-Type: application/json" ); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Creates and returns a public link to a file or folder's "preview page". This link can be * used without authentication. The preview page may contain a thumbnail or some other * preview of the file, along with a download link to download the actual file. * * See <a href="https://www.dropbox.com/developers/core/docs#shares">/shares</a>. * * @param string $path * The Dropbox path to the file or folder you want to create a shareable link to (UTF-8). * * @return string * The URL of the preview page. * * @throws Exception */ function createShareableLink($path) { Path::checkArg("path", $path); $response = $this->doPost( $this->apiHost, $this->appendFilePath("1/shares", $path), array( "short_url" => "false", )); if ($response->statusCode === 404) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); $j = RequestUtil::parseResponseJson($response->body); return self::getField($j, "url"); } /** * Creates and returns a direct link to a file. This link can be used without authentication. * This link will expire in a few hours. * * See <a href="https://www.dropbox.com/developers/core/docs#media">/media</a>. * * @param string $path * The Dropbox path to a file or folder (UTF-8). * * @return array * A <code>list(string $url, \DateTime $expires)</code> where <code>$url</code> is a direct * link to the requested file and <code>$expires</code> is a standard PHP * <code>\DateTime</code> representing when <code>$url</code> will stop working. * * @throws Exception */ function createTemporaryDirectLink($path) { Path::checkArgNonRoot("path", $path); $response = $this->doPost( $this->apiHost, $this->appendFilePath("1/media", $path)); if ($response->statusCode === 404) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); $j = RequestUtil::parseResponseJson($response->body); $url = self::getField($j, "url"); $expires = self::parseDateTime(self::getField($j, "expires")); return array($url, $expires); } /** * Creates and returns a "copy ref" to a file. A copy ref can be used to copy a file across * different Dropbox accounts without downloading and re-uploading. * * For example: Create a <code>Client</code> using the access token from one account and call * <code>createCopyRef</code>. Then, create a <code>Client</code> using the access token for * another account and call <code>copyFromCopyRef</code> using the copy ref. (You need to use * the same app key both times.) * * See <a href="https://www.dropbox.com/developers/core/docs#copy_ref">/copy_ref</a>. * * @param string path * The Dropbox path of the file or folder you want to create a copy ref for (UTF-8). * * @return string * The copy ref (just a string that you keep track of). * * @throws Exception */ function createCopyRef($path) { Path::checkArg("path", $path); $response = $this->doGet( $this->apiHost, $this->appendFilePath("1/copy_ref", $path)); if ($response->statusCode === 404) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); $j = RequestUtil::parseResponseJson($response->body); return self::getField($j, "copy_ref"); } /** * Gets a thumbnail image representation of the file at the given path. * * See <a href="https://www.dropbox.com/developers/core/docs#thumbnails">/thumbnails</a>. * * @param string $path * The path to the file you want a thumbnail for (UTF-8). * * @param string $format * One of the two image formats: "jpeg" or "png". * * @param string $size * One of the predefined image size names, as a string: * <ul> * <li>"xs" - 32x32</li> * <li>"s" - 64x64</li> * <li>"m" - 128x128</li> * <li>"l" - 640x480</li> * <li>"xl" - 1024x768</li> * </ul> * * @return array|null * If the file exists, you'll get <code>list(array $metadata, string $data)</code> where * <code>$metadata</code> is the file's * <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a> * and $data is the raw data for the thumbnail image. If the file doesn't exist, you'll * get <code>null</code>. * * @throws Exception */ function getThumbnail($path, $format, $size) { Path::checkArgNonRoot("path", $path); Checker::argString("format", $format); Checker::argString("size", $size); if (!in_array($format, array("jpeg", "png"))) { throw new \InvalidArgumentException("Invalid 'format': ".Util::q($format)); } if (!in_array($size, array("xs", "s", "m", "l", "xl"))) { throw new \InvalidArgumentException("Invalid 'size': ".Util::q($format)); } $url = $this->buildUrlForGetOrPut( $this->contentHost, $this->appendFilePath("1/thumbnails", $path), array("size" => $size, "format" => $format)); $curl = $this->mkCurl($url); $metadataCatcher = new DropboxMetadataHeaderCatcher($curl->handle); $curl->set(CURLOPT_RETURNTRANSFER, true); $response = $curl->exec(); if ($response->statusCode === 404) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); $metadata = $metadataCatcher->getMetadata(); return array($metadata, $response->body); } /** * Copies a file or folder to a new location * * See <a href="https://www.dropbox.com/developers/core/docs#fileops-copy">/fileops/copy</a>. * * @param string $fromPath * The Dropbox path of the file or folder you want to copy (UTF-8). * * @param string $toPath * The destination Dropbox path (UTF-8). * * @return mixed * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata * object</a> for the new file or folder. * * @throws Exception */ function copy($fromPath, $toPath) { Path::checkArg("fromPath", $fromPath); Path::checkArgNonRoot("toPath", $toPath); $response = $this->doPost( $this->apiHost, "1/fileops/copy", array( "root" => "auto", "from_path" => $fromPath, "to_path" => $toPath, )); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Creates a file or folder based on an existing copy ref (possibly from a different Dropbox * account). * * See <a href="https://www.dropbox.com/developers/core/docs#fileops-copy">/fileops/copy</a>. * * @param string $copyRef * A copy ref obtained via the {@link createCopyRef()} call. * * @param string $toPath * The Dropbox path you want to copy the file or folder to (UTF-8). * * @return mixed * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata * object</a> for the new file or folder. * * @throws Exception */ function copyFromCopyRef($copyRef, $toPath) { Checker::argStringNonEmpty("copyRef", $copyRef); Path::checkArgNonRoot("toPath", $toPath); $response = $this->doPost( $this->apiHost, "1/fileops/copy", array( "root" => "auto", "from_copy_ref" => $copyRef, "to_path" => $toPath, ) ); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Creates a folder. * * See <a href="https://www.dropbox.com/developers/core/docs#fileops-create-folder">/fileops/create_folder</a>. * * @param string $path * The Dropbox path at which to create the folder (UTF-8). * * @return array|null * If successful, you'll get back the * <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a> * for the newly-created folder. If not successful, you'll get <code>null</code>. * * @throws Exception */ // function createFolder($path) // { // Path::checkArgNonRoot("path", $path); // $response = $this->doPost( // $this->apiHost, // "1/fileops/create_folder", // array( // "root" => "auto", // "path" => $path, // )); // if ($response->statusCode === 403) return null; // if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); // return RequestUtil::parseResponseJson($response->body); // } /*Dropbox api 2*/ function createFolder($path) { Path::checkArgNonRoot("path", $path); $response = $this->doPost( $this->apiHost, "2/files/create_folder", array( "autorename" => false, "path" => $path, ), "Content-Type: application/json" ); if ($response->statusCode == 409) { return; } if ($response->statusCode === 403) return null; if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Deletes a file or folder * * See <a href="https://www.dropbox.com/developers/core/docs#fileops-delete">/fileops/delete</a>. * * @param string $path * The Dropbox path of the file or folder to delete (UTF-8). * * @return mixed * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata * object</a> for the deleted file or folder. * * @throws Exception */ // function delete($path) // { // Path::checkArgNonRoot("path", $path); // $response = $this->doPost( // $this->apiHost, // "1/fileops/delete", // array( // "root" => "auto", // "path" => $path, // )); // if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); // return RequestUtil::parseResponseJson($response->body); // } /*Dropbox api 2*/ function delete($path) { Path::checkArgNonRoot("path", $path); $response = $this->doPost( $this->apiHost, "2/files/delete", array( "path" => $path ), "Content-Type: application/json" ); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Moves a file or folder to a new location. * * See <a href="https://www.dropbox.com/developers/core/docs#fileops-move">/fileops/move</a>. * * @param string $fromPath * The source Dropbox path (UTF-8). * * @param string $toPath * The destination Dropbox path (UTF-8). * * @return mixed * The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata * object</a> for the destination file or folder. * * @throws Exception */ function move($fromPath, $toPath) { Path::checkArgNonRoot("fromPath", $fromPath); Path::checkArgNonRoot("toPath", $toPath); $response = $this->doPost( $this->apiHost, "1/fileops/move", array( "root" => "auto", "from_path" => $fromPath, "to_path" => $toPath, )); if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response); return RequestUtil::parseResponseJson($response->body); } /** * Build a URL for making a GET or PUT request. Will add the "locale" * parameter. * * @param string $host * Either the "API" or "API content" hostname from {@link getHost()}. * @param string $path * The "path" part of the URL. For example, "/account/info". * @param array|null $params * URL parameters. For POST requests, do not put the parameters here. * Include them in the request body instead. * * @return string */ function buildUrlForGetOrPut($host, $path, $params = null) { return RequestUtil::buildUrlForGetOrPut($this->userLocale, $host, $path, $params); } /** * Perform an OAuth-2-authorized GET request to the Dropbox API. Will automatically * fill in "User-Agent" and "locale" as well. * * @param string $host * Either the "API" or "API content" hostname from {@link getHost()}. * @param string $path * The "path" part of the URL. For example, "/account/info". * @param array|null $params * GET parameters. * @return HttpResponse * * @throws Exception */ function doGet($host, $path, $params = null) { Checker::argString("host", $host); Checker::argString("path", $path); return RequestUtil::doGet($this->clientIdentifier, $this->accessToken, $this->userLocale, $host, $path, $params); } /** * Perform an OAuth-2-authorized POST request to the Dropbox API. Will automatically * fill in "User-Agent" and "locale" as well. * * @param string $host * Either the "API" or "API content" hostname from {@link getHost()}. * @param string $path * The "path" part of the URL. For example, "/commit_chunked_upload". * @param array|null $params * POST parameters. * @return HttpResponse * * @throws Exception */ function doPost($host, $path, $params = null, $headers = null) { Checker::argString("host", $host); Checker::argString("path", $path); return RequestUtil::doPost($this->clientIdentifier, $this->accessToken, $this->userLocale, $host, $path, $params, $headers); } /** * Create a {@link Curl} object that is pre-configured with {@link getClientIdentifier()}, * and the proper OAuth 2 "Authorization" header. * * @param string $url * Generate this URL using {@link buildUrl()}. * * @return Curl */ function mkCurl($url) { return RequestUtil::mkCurlWithOAuth($this->clientIdentifier, $url, $this->accessToken); } /** * Parses date/time strings returned by the Dropbox API. The Dropbox API returns date/times * formatted like: <code>"Sat, 21 Aug 2010 22:31:20 +0000"</code>. * * @param string $apiDateTimeString * A date/time string returned by the API. * * @return \DateTime * A standard PHP <code>\DateTime</code> instance. * * @throws Exception_BadResponse * Thrown if <code>$apiDateTimeString</code> isn't correctly formatted. */ static function parseDateTime($apiDateTimeString) { $dt = \DateTime::createFromFormat(self::$dateTimeFormat, $apiDateTimeString); if ($dt === false) throw new Exception_BadResponse( "Bad date/time from server: ".Util::q($apiDateTimeString)); return $dt; } private static $dateTimeFormat = "D, d M Y H:i:s T"; /** * @internal */ static function getField($j, $fieldName) { if (!array_key_exists($fieldName, $j)) throw new Exception_BadResponse( "missing field \"$fieldName\" in ".Util::q($j)); return $j[$fieldName]; } /** * Given an OAuth 2 access token, returns <code>null</code> if it is well-formed (though * not necessarily valid). Otherwise, returns a string describing what's wrong with it. * * @param string $s * * @return string */ static function getAccessTokenError($s) { if ($s === null) return "can't be null"; if (strlen($s) === 0) return "can't be empty"; if (preg_match('@[^-=_~/A-Za-z0-9\.\+]@', $s) === 1) return "contains invalid character"; return null; } /** * @internal */ static function checkAccessTokenArg($argName, $accessToken) { $error = self::getAccessTokenError($accessToken); if ($error !== null) throw new \InvalidArgumentException("'$argName' invalid: $error"); } /** * @internal */ static function getClientIdentifierError($s) { if ($s === null) return "can't be null"; if (strlen($s) === 0) return "can't be empty"; if (preg_match('@[\x00-\x1f\x7f]@', $s) === 1) return "contains control character"; return null; } /** * @internal */ static function checkClientIdentifierArg($argName, $accessToken) { $error = self::getClientIdentifierError($accessToken); if ($error !== null) throw new \InvalidArgumentException("'$argName' invalid: $error"); } }