diff --git a/src/Dropbox/Dropbox.php b/src/Dropbox/Dropbox.php index b017c38..6e17b5a 100644 --- a/src/Dropbox/Dropbox.php +++ b/src/Dropbox/Dropbox.php @@ -2,6 +2,8 @@ namespace Kunnu\Dropbox; +use Kunnu\Dropbox\Exceptions\DropboxClientUnableToOpenTempFileException; +use Kunnu\Dropbox\Exceptions\DropboxClientUnableToWriteToTempException; use Kunnu\Dropbox\Models\DeletedMetadata; use Kunnu\Dropbox\Models\File; use Kunnu\Dropbox\Models\Account; @@ -50,6 +52,13 @@ class Dropbox */ const METADATA_HEADER = 'dropbox-api-result'; + /** + * Prefix for writable temporary file + * + * @const string + */ + const TMP_PREFIX = 'dropbox-temp-file'; + /** * The Dropbox App * @@ -201,8 +210,8 @@ public function getPersistentDataStore() /** * Get the Metadata for a file or folder * - * @param string $path Path of the file or folder - * @param array $params Additional Params + * @param string $path Path of the file or folder + * @param array $params Additional Params * * @return \Kunnu\Dropbox\Models\FileMetadata | \Kunnu\Dropbox\Models\FolderMetadata * @throws \Kunnu\Dropbox\Exceptions\DropboxClientException @@ -230,9 +239,9 @@ public function getMetadata($path, array $params = []) /** * Make a HTTP POST Request to the API endpoint type * - * @param string $endpoint API Endpoint to send Request to - * @param array $params Request Query Params - * @param string $accessToken Access Token to send with the Request + * @param string $endpoint API Endpoint to send Request to + * @param array $params Request Query Params + * @param string $accessToken Access Token to send with the Request * * @return \Kunnu\Dropbox\DropboxResponse */ @@ -244,19 +253,25 @@ public function postToAPI($endpoint, array $params = [], $accessToken = null) /** * Make Request to the API * - * @param string $method HTTP Request Method - * @param string $endpoint API Endpoint to send Request to - * @param string $endpointType Endpoint type ['api'|'content'] - * @param array $params Request Query Params - * @param string $accessToken Access Token to send with the Request - * @param DropboxFile $responseFile Save response to the file + * @param string $method HTTP Request Method + * @param string $endpoint API Endpoint to send Request to + * @param string $endpointType Endpoint type ['api'|'content'] + * @param array $params Request Query Params + * @param string $accessToken Access Token to send with the Request + * @param DropboxFile $responseFile Save response to the file * * @return \Kunnu\Dropbox\DropboxResponse * * @throws \Kunnu\Dropbox\Exceptions\DropboxClientException */ - public function sendRequest($method, $endpoint, $endpointType = 'api', array $params = [], $accessToken = null, DropboxFile $responseFile = null) - { + public function sendRequest( + $method, + $endpoint, + $endpointType = 'api', + array $params = [], + $accessToken = null, + DropboxFile $responseFile = null + ) { //Access Token $accessToken = $this->getAccessToken() ? $this->getAccessToken() : $accessToken; @@ -298,7 +313,7 @@ public function setAccessToken($accessToken) /** * Make Model from DropboxResponse * - * @param DropboxResponse $response + * @param DropboxResponse $response * * @return \Kunnu\Dropbox\Models\ModelInterface * @@ -320,12 +335,12 @@ public function makeModelFromResponse(DropboxResponse $response) /** * Get the contents of a Folder * - * @param string $path Path to the folder. Defaults to root. - * @param array $params Additional Params + * @param string $path Path to the folder. Defaults to root. + * @param array $params Additional Params * + * @return \Kunnu\Dropbox\Models\MetadataCollection * @link https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder * - * @return \Kunnu\Dropbox\Models\MetadataCollection */ public function listFolder($path = null, array $params = []) { @@ -349,12 +364,12 @@ public function listFolder($path = null, array $params = []) * Paginate through all files and retrieve updates to the folder, * using the cursor retrieved from listFolder or listFolderContinue * - * @param string $cursor The cursor returned by your + * @param string $cursor The cursor returned by your * last call to listFolder or listFolderContinue * + * @return \Kunnu\Dropbox\Models\MetadataCollection * @link https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder-continue * - * @return \Kunnu\Dropbox\Models\MetadataCollection */ public function listFolderContinue($cursor) { @@ -367,8 +382,8 @@ public function listFolderContinue($cursor) /** * Get a cursor for the folder's state. * - * @param string $path Path to the folder. Defaults to root. - * @param array $params Additional Params + * @param string $path Path to the folder. Defaults to root. + * @param array $params Additional Params * * @return string The Cursor for the folder's state * @@ -407,12 +422,12 @@ public function listFolderLatestCursor($path, array $params = []) /** * Get Revisions of a File * - * @param string $path Path to the file - * @param array $params Additional Params + * @param string $path Path to the file + * @param array $params Additional Params * + * @return \Kunnu\Dropbox\Models\ModelCollection * @link https://www.dropbox.com/developers/documentation/http/documentation#files-list_revisions * - * @return \Kunnu\Dropbox\Models\ModelCollection */ public function listRevisions($path, array $params = []) { @@ -442,13 +457,13 @@ public function listRevisions($path, array $params = []) /** * Search a folder for files/folders * - * @param string $path Path to search - * @param string $query Search Query - * @param array $params Additional Params + * @param string $path Path to search + * @param string $query Search Query + * @param array $params Additional Params * + * @return \Kunnu\Dropbox\Models\SearchResults * @link https://www.dropbox.com/developers/documentation/http/documentation#files-search * - * @return \Kunnu\Dropbox\Models\SearchResults */ public function search($path, $query, array $params = []) { @@ -472,8 +487,8 @@ public function search($path, $query, array $params = []) /** * Create a folder at the given path * - * @param string $path Path to create - * @param boolean $autorename Auto Rename File + * @param string $path Path to create + * @param boolean $autorename Auto Rename File * * @return \Kunnu\Dropbox\Models\FolderMetadata * @@ -502,7 +517,7 @@ public function createFolder($path, $autorename = false) /** * Delete a file or folder at the given path * - * @param string $path Path to file/folder to delete + * @param string $path Path to file/folder to delete * * @return \Kunnu\Dropbox\Models\DeletedMetadata * @@ -533,8 +548,8 @@ public function delete($path) /** * Move a file or folder to a different location * - * @param string $fromPath Path to be moved - * @param string $toPath Path to be moved to + * @param string $fromPath Path to be moved + * @param string $toPath Path to be moved to * * @return \Kunnu\Dropbox\Models\DeletedMetadata|\Kunnu\Dropbox\Models\FileMetadata * @@ -560,8 +575,8 @@ public function move($fromPath, $toPath) /** * Copy a file or folder to a different location * - * @param string $fromPath Path to be copied - * @param string $toPath Path to be copied to + * @param string $fromPath Path to be copied + * @param string $toPath Path to be copied to * * @return \Kunnu\Dropbox\Models\DeletedMetadata|\Kunnu\Dropbox\Models\FileMetadata * @@ -587,8 +602,8 @@ public function copy($fromPath, $toPath) /** * Restore a file to the specific version * - * @param string $path Path to the file to restore - * @param string $rev Revision to store for the file + * @param string $path Path to the file to restore + * @param string $rev Revision to store for the file * * @return \Kunnu\Dropbox\Models\DeletedMetadata|\Kunnu\Dropbox\Models\FileMetadata|\Kunnu\Dropbox\Models\FolderMetadata * @@ -617,7 +632,7 @@ public function restore($path, $rev) /** * Get Copy Reference * - * @param string $path Path to the file or folder to get a copy reference to + * @param string $path Path to the file or folder to get a copy reference to * * @return \Kunnu\Dropbox\Models\CopyReference * @@ -644,8 +659,8 @@ public function getCopyReference($path) /** * Save Copy Reference * - * @param string $path Path to the file or folder to get a copy reference to - * @param string $copyReference Copy reference returned by getCopyReference + * @param string $path Path to the file or folder to get a copy reference to + * @param string $copyReference Copy reference returned by getCopyReference * * @return \Kunnu\Dropbox\Models\FileMetadata|\Kunnu\Dropbox\Models\FolderMetadata * @@ -662,7 +677,8 @@ public function saveCopyReference($path, $copyReference) } //Save Copy Reference - $response = $this->postToAPI('/files/copy_reference/save', ['path' => $path, 'copy_reference' => $copyReference]); + $response = $this->postToAPI('/files/copy_reference/save', + ['path' => $path, 'copy_reference' => $copyReference]); $body = $response->getDecodedBody(); //Response doesn't have Metadata @@ -677,7 +693,7 @@ public function saveCopyReference($path, $copyReference) /** * Get a temporary link to stream contents of a file * - * @param string $path Path to the file you want a temporary link to + * @param string $path Path to the file you want a temporary link to * * https://www.dropbox.com/developers/documentation/http/documentation#files-get_temporary_link * @@ -702,8 +718,8 @@ public function getTemporaryLink($path) /** * Save a specified URL into a file in user's Dropbox * - * @param string $path Path where the URL will be saved - * @param string $url URL to be saved + * @param string $path Path where the URL will be saved + * @param string $url URL to be saved * * @return string Async Job ID * @@ -769,13 +785,13 @@ public function checkJobStatus($asyncJobId) /** * Upload a File to Dropbox * - * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file - * @param string $path Path to upload the file to - * @param array $params Additional Params + * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file + * @param string $path Path to upload the file to + * @param array $params Additional Params * + * @return \Kunnu\Dropbox\Models\FileMetadata * @link https://www.dropbox.com/developers/documentation/http/documentation#files-upload * - * @return \Kunnu\Dropbox\Models\FileMetadata */ public function upload($dropboxFile, $path, array $params = []) { @@ -792,13 +808,42 @@ public function upload($dropboxFile, $path, array $params = []) return $this->simpleUpload($dropboxFile, $path, $params); } + + /** + * Make DropboxFile Object using the given $data string as the file contents. + * @param $path + * @param $data + * @return DropboxFile + * @throws DropboxClientException + * @throws DropboxClientUnableToWriteToTempException + */ + public function makeDropboxFileFromString($path, $data) + { + //create a temp file with a prefix + $tmpfname = tempnam(sys_get_temp_dir(), static::TMP_PREFIX); + + if (!is_writable($tmpfname)) { // Test if the file is writable + throw new DropboxClientUnableToWriteToTempException("Cannot write to {$tmpfname}"); + } + + $handle = fopen($tmpfname, DropboxFile::MODE_WRITE); + + if (!is_resource($handle)) { // Test if PHP could open the file + throw new DropboxClientUnableToOpenTempFileException("Could not open {$tmpfname} on writing mode."); + } + + fwrite($handle, $data); + + return DropboxFile::createByStream($path, $handle, DropboxFile::MODE_WRITE); + } + /** * Make DropboxFile Object * - * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file - * @param int $maxLength Max Bytes to read from the file - * @param int $offset Seek to specified offset before reading - * @param string $mode The type of access + * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file + * @param int $maxLength Max Bytes to read from the file + * @param int $offset Seek to specified offset before reading + * @param string $mode The type of access * * @return \Kunnu\Dropbox\DropboxFile */ @@ -829,17 +874,17 @@ public function makeDropboxFile($dropboxFile, $maxLength = null, $offset = null, /** * Upload file in sessions/chunks * - * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file - * @param string $path Path to save the file to, on Dropbox - * @param int $fileSize The size of the file - * @param int $chunkSize The amount of data to upload in each chunk - * @param array $params Additional Params + * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file + * @param string $path Path to save the file to, on Dropbox + * @param int $fileSize The size of the file + * @param int $chunkSize The amount of data to upload in each chunk + * @param array $params Additional Params * - * @link https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-start + * @return \Kunnu\Dropbox\Models\FileMetadata * @link https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-finish * @link https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-append_v2 * - * @return \Kunnu\Dropbox\Models\FileMetadata + * @link https://www.dropbox.com/developers/documentation/http/documentation#files-upload_session-start */ public function uploadChunked($dropboxFile, $path, $fileSize = null, $chunkSize = null, array $params = array()) { @@ -894,9 +939,9 @@ public function uploadChunked($dropboxFile, $path, $fileSize = null, $chunkSize /** * Start an Upload Session * - * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file - * @param int $chunkSize Size of file chunk to upload - * @param boolean $close Closes the session for "appendUploadSession" + * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file + * @param int $chunkSize Size of file chunk to upload + * @param boolean $close Closes the session for "appendUploadSession" * * @return string Unique identifier for the upload session * @@ -932,10 +977,10 @@ public function startUploadSession($dropboxFile, $chunkSize = -1, $close = false /** * Make a HTTP POST Request to the Content endpoint type * - * @param string $endpoint Content Endpoint to send Request to - * @param array $params Request Query Params - * @param string $accessToken Access Token to send with the Request - * @param DropboxFile $responseFile Save response to the file + * @param string $endpoint Content Endpoint to send Request to + * @param array $params Request Query Params + * @param string $accessToken Access Token to send with the Request + * @param DropboxFile $responseFile Save response to the file * * @return \Kunnu\Dropbox\DropboxResponse */ @@ -947,11 +992,11 @@ public function postToContent($endpoint, array $params = [], $accessToken = null /** * Append more data to an Upload Session * - * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file - * @param string $sessionId Session ID returned by `startUploadSession` - * @param int $offset The amount of data that has been uploaded so far - * @param int $chunkSize The amount of data to upload - * @param boolean $close Closes the session for futher "appendUploadSession" calls + * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file + * @param string $sessionId Session ID returned by `startUploadSession` + * @param int $offset The amount of data that has been uploaded so far + * @param int $chunkSize The amount of data to upload + * @param boolean $close Closes the session for futher "appendUploadSession" calls * * @return string Unique identifier for the upload session * @@ -996,12 +1041,12 @@ public function appendUploadSession($dropboxFile, $sessionId, $offset, $chunkSiz /** * Finish an upload session and save the uploaded data to the given file path * - * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file - * @param string $sessionId Session ID returned by `startUploadSession` - * @param int $offset The amount of data that has been uploaded so far - * @param int $remaining The amount of data that is remaining - * @param string $path Path to save the file to, on Dropbox - * @param array $params Additional Params + * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file + * @param string $sessionId Session ID returned by `startUploadSession` + * @param int $offset The amount of data that has been uploaded so far + * @param int $remaining The amount of data that is remaining + * @param string $path Path to save the file to, on Dropbox + * @param array $params Additional Params * * @return \Kunnu\Dropbox\Models\FileMetadata * @@ -1044,13 +1089,13 @@ public function finishUploadSession($dropboxFile, $sessionId, $offset, $remainin /** * Upload a File to Dropbox in a single request * - * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file - * @param string $path Path to upload the file to - * @param array $params Additional Params + * @param string|DropboxFile $dropboxFile DropboxFile object or Path to file + * @param string $path Path to upload the file to + * @param array $params Additional Params * + * @return \Kunnu\Dropbox\Models\FileMetadata * @link https://www.dropbox.com/developers/documentation/http/documentation#files-upload * - * @return \Kunnu\Dropbox\Models\FileMetadata */ public function simpleUpload($dropboxFile, $path, array $params = []) { @@ -1072,9 +1117,9 @@ public function simpleUpload($dropboxFile, $path, array $params = []) /** * Get a thumbnail for an image * - * @param string $path Path to the file you want a thumbnail to - * @param string $size Size for the thumbnail image ['thumb','small','medium','large','huge'] - * @param string $format Format for the thumbnail image ['jpeg'|'png'] + * @param string $path Path to the file you want a thumbnail to + * @param string $size Size for the thumbnail image ['thumb','small','medium','large','huge'] + * @param string $format Format for the thumbnail image ['jpeg'|'png'] * * @return \Kunnu\Dropbox\Models\Thumbnail * @@ -1099,7 +1144,8 @@ public function getThumbnail($path, $size = 'small', $format = 'jpeg') $size = $this->getThumbnailSize($size); //Get Thumbnail - $response = $this->postToContent('/files/get_thumbnail', ['path' => $path, 'format' => $format, 'size' => $size]); + $response = $this->postToContent('/files/get_thumbnail', + ['path' => $path, 'format' => $format, 'size' => $size]); //Get file metadata from response headers $metadata = $this->getMetadataFromResponseHeaders($response); @@ -1114,7 +1160,7 @@ public function getThumbnail($path, $size = 'small', $format = 'jpeg') /** * Get thumbnail size * - * @param string $size Thumbnail Size + * @param string $size Thumbnail Size * * @return string */ @@ -1134,7 +1180,7 @@ protected function getThumbnailSize($size) /** * Get metadata from response headers * - * @param DropboxResponse $response + * @param DropboxResponse $response * * @return array */ @@ -1170,8 +1216,8 @@ protected function getMetadataFromResponseHeaders(DropboxResponse $response) /** * Download a File * - * @param string $path Path to the file you want to download - * @param null|string|DropboxFile $dropboxFile DropboxFile object or Path to target file + * @param string $path Path to the file you want to download + * @param null|string|DropboxFile $dropboxFile DropboxFile object or Path to target file * * @return \Kunnu\Dropbox\Models\File * @@ -1225,9 +1271,9 @@ public function getCurrentAccount() * * @param string $account_id Account ID of the account to get details for * + * @return \Kunnu\Dropbox\Models\Account * @link https://www.dropbox.com/developers/documentation/http/documentation#users-get_account * - * @return \Kunnu\Dropbox\Models\Account */ public function getAccount($account_id) { @@ -1244,9 +1290,9 @@ public function getAccount($account_id) * * @param array $account_ids IDs of the accounts to get details for * + * @return \Kunnu\Dropbox\Models\AccountList * @link https://www.dropbox.com/developers/documentation/http/documentation#users-get_account_batch * - * @return \Kunnu\Dropbox\Models\AccountList */ public function getAccounts(array $account_ids = []) { diff --git a/src/Dropbox/Exceptions/DropboxClientUnableToOpenTempFileException.php b/src/Dropbox/Exceptions/DropboxClientUnableToOpenTempFileException.php new file mode 100644 index 0000000..0aeef28 --- /dev/null +++ b/src/Dropbox/Exceptions/DropboxClientUnableToOpenTempFileException.php @@ -0,0 +1,10 @@ +