Methods summary
public
AccessToken
|
#
getAccessToken( )
The access token used by this client to make authenticated API calls. You can get an
access token via Dropbox\WebAuth.
The access token used by this client to make authenticated API calls. You can get an
access token via Dropbox\WebAuth.
Returns
AccessToken
|
public
string
|
#
getClientIdentifier( )
An identifier for the API client, typically of the form "Name/Version".
This is used to set the HTTP User-Agent header when making API requests.
Example: "PhotoEditServer/1.3"
An identifier for the API client, typically of the form "Name/Version".
This is used to set the HTTP User-Agent header when making API requests.
Example: "PhotoEditServer/1.3"
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:
"PhotoEditServer/1.3 FilePicker/0.1-beta"
The exact format of the User-Agent header is described in
section 3.8 of the HTTP specification.
Note that underlying HTTP client may append other things to the User-Agent, such as
the name of the library being used to actually make the HTTP request (such as cURL).
Returns
string
|
public
null|string
|
#
getUserLocale( )
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.
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.
Returns
null|string
|
public
Host
|
#
getHost( )
The Host object that determines the hostnames we make requests to.
The Host object that determines the hostnames we make requests to.
Returns
Host
|
public
|
#
__construct( string $accessToken, string $clientIdentifier, null|string $userLocale = null )
|
public
string
|
#
appendFilePath( string $base, string $path )
Given a $base 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.
Given a $base 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.
Parameters
Returns
string
|
public
|
#
disableAccessToken( )
Make an API call to disable the access token that you constructed this Client
with. After calling this, API calls made with this Client will fail.
Make an API call to disable the access token that you constructed this Client
with. After calling this, API calls made with this Client will fail.
See /disable_access_token.
Throws
|
public
array
|
#
getAccountInfo( )
Make an API call to get basic account and quota information.
Make an API call to get basic account and quota information.
$client = ...
$accountInfo = $client->getAccountInfo();
print_r($accountInfo);
Returns
Throws
|
public
null|array
|
#
getFile( string $path, resource $outStream, string|null $rev = null )
Downloads a file from Dropbox. The file's contents are written to the
given $outStream and the file's metadata is returned.
Downloads a file from Dropbox. The file's contents are written to the
given $outStream and the file's metadata is returned.
$client = ...;
$fd = fopen("./Frog.jpeg", "wb");
$metadata = $client->getFile("/Photos/Frog.jpeg", $fd);
fclose($fd);
print_r($metadata);
Parameters
- $path
- The path to the file on Dropbox (UTF-8).
- $outStream
- If the file exists, the file contents will be written to this stream.
- $rev
If you want the latest revision of the file at the given path, pass in null.
If you want a specific version of a file, pass in value of the file metadata's "rev" field. Returns
null|array The metadata
object for the file at the given $path and $rev, or null if the file
doesn't exist,
Throws
|
public
mixed
|
#
uploadFile( string $path, Dropbox\WriteMode $writeMode, resource $inStream, integer|null $numBytes = null )
Creates a file on Dropbox, using the data from $inStream for the file contents.
Creates a file on Dropbox, using the data from $inStream for the file contents.
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"];
$fd = fopen("./frog-new.jpeg", "rb");
$md2 = $client->uploadFile("/Photos/Frog.jpeg",
dbx\WriteMode::update($rev), $fd);
fclose($fd);
print_r($md2);
Parameters
- $path
- The Dropbox path to save the file to (UTF-8).
- $writeMode
- What to do if there's already a file at the given path.
- $inStream
- The data to use for the file contents.
- $numBytes
You can pass in null 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. Returns
mixed The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
object for the newly-added file.
Throws
|
public
mixed
|
#
uploadFileFromString( string $path, Dropbox\WriteMode $writeMode, string $data )
Creates a file on Dropbox, using the given $data string as the file contents.
Creates a file on Dropbox, using the given $data string as the file contents.
use \Dropbox as dbx;
$client = ...;
$md = $client->uploadFileFromString("/Grocery List.txt",
dbx\WriteMode::add(),
"1. Coke\n2. Popcorn\n3. Toothpaste\n");
print_r($md);
Parameters
- $path
- The Dropbox path to save the file to (UTF-8).
- $writeMode
- What to do if there's already a file at the given path.
- $data
- The data to use for the contents of the file.
Returns
mixed The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
object for the newly-added file.
Throws
|
public
mixed
|
#
uploadFileChunked( string $path, Dropbox\WriteMode $writeMode, resource $inStream, integer|null $numBytes = null, integer|null $chunkSize = null )
Creates a file on Dropbox, using the data from $inStream as the file contents.
Creates a file on Dropbox, using the data from $inStream as the file contents.
This version of uploadFile splits uploads the file ~4MB chunks at a time and
will retry a few times if one chunk fails to upload. Uses Dropbox\Client::chunkedUploadStart(),
Dropbox\Client::chunkedUploadContinue(), and Dropbox\Client::chunkedUploadFinish().
Parameters
- $path
- The Dropbox path to save the file to (UTF-8).
- $writeMode
- What to do if there's already a file at the given path.
- $inStream
- The data to use for the file contents.
- $numBytes
The number of bytes available from $inStream.
You can pass in null if you don't know. - $chunkSize
The number of bytes to upload in each chunk. You can omit this (or pass in
null and the library will use a reasonable default. Returns
mixed The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
object for the newly-added file.
Throws
|
public
array
|
#
chunkedUploadStart( string $data )
Start a new chunked upload session and upload the first chunk of data.
Start a new chunked upload session and upload the first chunk of data.
Parameters
- $data
- The data to start off the chunked upload session.
Returns
array A pair of (string $uploadId, int $byteOffset). $uploadId
is a unique identifier for this chunked upload session. You pass this in to
Dropbox\Client::chunkedUploadContinue() and chuunkedUploadFinish. $byteOffset
is the number of bytes that were successfully uploaded.
Throws
|
public
integer|boolean
|
#
chunkedUploadContinue( string $uploadId, integer $byteOffset, string $data )
Append another chunk data to a previously-started chunked upload session.
Append another chunk data to a previously-started chunked upload session.
Parameters
- $uploadId
The unique identifier for the chunked upload session. This is obtained via
Dropbox\Client::chunkedUploadStart(). - $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. - $data
- The data to append to the existing chunked upload session.
Returns
integer|boolean If false, it means the server didn't know about the given
$uploadId. This may be because the chunked upload session has expired
(they last around 24 hours).
If true, the chunk was successfully uploaded. If an integer, it means
you and the server don't agree on the current $byteOffset. The returned
integer is the server's internal byte offset for the chunked upload session. You need
to adjust your input to match.
Throws
|
public
array|null
|
#
chunkedUploadFinish( string $uploadId, string $path, Dropbox\WriteMode $writeMode )
Creates a file on Dropbox using the accumulated contents of the given chunked upload session.
Creates a file on Dropbox using the accumulated contents of the given chunked upload session.
See /commit_chunked_upload.
Parameters
- $uploadId
The unique identifier for the chunked upload session. This is obtained via
Dropbox\Client::chunkedUploadStart(). - $path
- The Dropbox path to save the file to.
- $writeMode
- What to do if there's already a file at the given path.
Returns
array|null If null, it means the Dropbox server wasn't aware of the
$uploadId you gave it.
Otherwise, you get back the
metadata object
for the newly-created file.
Throws
|
public
array|null
|
#
getMetadata( string $path )
Returns the metadata for whatever file or folder is at the given path.
Returns the metadata for whatever file or folder is at the given path.
$client = ...;
$md = $client->getMetadata("/Photos/Frog.jpeg");
print_r($md);
Parameters
- $path
- The Dropbox path to a file or folder (UTF-8).
Returns
array|null If there is a file or folder at the given path, you'll get back the
metadata object
for that file or folder. If not, you'll get back null.
Throws
|
public
array|null
|
#
getMetadataWithChildren( string $path )
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.
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.
$client = ...;
$md = $client->getMetadataWithChildren("/Photos");
print_r($md);
Parameters
- $path
- The Dropbox path to a file or folder (UTF-8).
Returns
array|null If there is a file or folder at the given path, you'll get back the
metadata object
for that file or folder, along with all immediate children if it's a folder. If not,
you'll get back null.
Throws
|
public
array
|
#
getMetadataWithChildrenIfChanged( string $path, string $previousFolderHash )
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 Dropbox\Client::getMetadataWithChildren() if you have a cache of previous results.
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 Dropbox\Client::getMetadataWithChildren() if you have a cache of previous results.
$client = ...;
$md = $client->getMetadataWithChildren("/Photos");
print_r($md);
assert($md["is_dir"], "expecting \"/Photos\" to be a folder");
sleep(10);
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";
}
Parameters
- $path
- The Dropbox path to a folder (UTF-8).
- $previousFolderHash
- The "hash" field from the previously retrieved folder metadata.
Returns
array A list(boolean $changed, array $metadata). If the metadata hasn't changed,
you'll get list(false, null). If the metadata of the folder or any of its
children has changed, you'll get list(true, $newMetadata). $metadata is a
metadata object.
Throws
|
public
array
|
#
getDelta( string|null $cursor = null, string|null $pathPrefix = null )
A way of letting you keep up with changes to files and folders in a user's Dropbox.
A way of letting you keep up with changes to files and folders in a user's Dropbox.
Parameters
- $cursor
If this is the first time you're calling this, pass in null. Otherwise,
pass in whatever cursor was returned by the previous call. - $pathPrefix
If null, you'll get results for the entire folder (either the user's
entire Dropbox or your App Folder). If you set $path_prefix to
"/Photos/Vacation", you'll only get results for that path and any files and folders
under it. Returns
array A delta page, which
contains a list of changes to apply along with a new "cursor" that should be passed into
future getDelta calls. If the "reset" field is true, you
should clear your local state before applying the changes. If the "has_more" field is
true, call getDelta immediately to get more results, otherwise
wait a while (at least 5 minutes) before calling getDelta again.
Throws
|
public
array|null
|
#
getRevisions( string $path, integer|null $limit = null )
Gets the metadata for all the file revisions (up to a limit) for a given path.
Gets the metadata for all the file revisions (up to a limit) for a given path.
See /revisions.
Parameters
- $path
- The Dropbox path that you want file revision metadata for (UTF-8).
- $limit
- The maximum number of revisions to return.
Returns
array|null A list of <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
objects, one for each file revision. The later revisions appear first in the list.
If null, then there were too many revisions at that path.
Throws
|
public
mixed
|
#
restoreFile( string $path, string $rev )
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.
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 /restore.
Parameters
- $path
- The Dropbox path of the file to restore (UTF-8).
- $rev
- The revision to restore the contents to.
Returns
Throws
|
public
mixed
|
#
searchFileNames( string $basePath, string $query, integer|null $limit = null, boolean $includeDeleted = false )
Returns metadata for all files and folders whose filename matches the query string.
Returns metadata for all files and folders whose filename matches the query string.
See /search.
Parameters
- $basePath
- The path to limit the search to (UTF-8). Pass in "/" to search everything.
- $query
A space-separated list of substrings to search for. A file matches only if it contains
all the substrings. - $limit
- The maximum number of results to return.
- $includeDeleted
- Whether to include deleted files in the results.
Returns
mixed A list of <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
objects of files that match the search query.
Throws
|
public
string
|
#
createShareableLink( string $path )
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.
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 /shares.
Parameters
- $path
- The Dropbox path to the file or folder you want to create a shareable link to (UTF-8).
Returns
string
The URL of the preview page.
Throws
|
public
array
|
#
createTemporaryDirectLink( string $path )
Creates and returns a direct link to a file. This link can be used without authentication.
This link will expire in a few hours.
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 /media.
Parameters
- $path
- The Dropbox path to a file or folder (UTF-8).
Returns
array A list(string $url, \DateTime $expires) where $url is a direct
link to the requested file and $expires is a standard PHP
\DateTime representing when $url will stop working.
Throws
|
public
string
|
#
createCopyRef( string $path )
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.
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 Client using the access token from one account and call
createCopyRef. Then, create a Client using the access token for
another account and call copyFromCopyRef using the copy ref. (You need to use
the same app key both times.)
See /copy_ref.
Parameters
- $path
- The Dropbox path of the file or folder you want to create a copy ref for (UTF-8).
Returns
string
The copy ref (just a string that you keep track of).
Throws
|
public
array|null
|
#
getThumbnail( string $path, string $format, string $size )
Gets a thumbnail image representation of the file at the given path.
Gets a thumbnail image representation of the file at the given path.
See /thumbnails.
Parameters
- $path
- The path to the file you want a thumbnail for (UTF-8).
- $format
- One of the two image formats: "jpeg" or "png".
- $size
One of the predefined image size names, as a string:
- "xs" - 32x32
- "s" - 64x64
- "m" - 128x128
- "l" - 640x480
- "xl" - 1024x768
Returns
array|null If the file exists, you'll get list(array $metadata, string $data) where
$metadata is the file's
metadata object
and $data is the raw data for the thumbnail image. If the file doesn't exist, you'll
get null.
Throws
|
public
mixed
|
#
copy( string $fromPath, string $toPath )
Copies a file or folder to a new location
Copies a file or folder to a new location
See /fileops/copy.
Parameters
- $fromPath
- The Dropbox path of the file or folder you want to copy (UTF-8).
- $toPath
- The destination Dropbox path (UTF-8).
Returns
Throws
|
public
mixed
|
#
copyFromCopyRef( string $copyRef, string $toPath )
Creates a file or folder based on an existing copy ref (possibly from a different Dropbox
account).
Creates a file or folder based on an existing copy ref (possibly from a different Dropbox
account).
See /fileops/copy.
Parameters
Returns
Throws
|
public
array|null
|
#
createFolder( string $path )
Creates a folder.
See /fileops/create_folder.
Parameters
- $path
- The Dropbox path at which to create the folder (UTF-8).
Returns
array|null If successful, you'll get back the
metadata object
for the newly-created folder. If not successful, you'll get null.
Throws
|
public
mixed
|
#
delete( string $path )
Deletes a file or folder
See /fileops/delete.
Parameters
- $path
- The Dropbox path of the file or folder to delete (UTF-8).
Returns
Throws
|
public
mixed
|
#
move( string $fromPath, string $toPath )
Moves a file or folder to a new location.
Moves a file or folder to a new location.
See /fileops/move.
Parameters
- $fromPath
- The source Dropbox path (UTF-8).
- $toPath
- The destination Dropbox path (UTF-8).
Returns
Throws
|
public
string
|
#
buildUrlForGetOrPut( string $host, string $path, array|null $params = null )
Build a URL for making a GET or PUT request. Will add the "locale"
parameter.
Build a URL for making a GET or PUT request. Will add the "locale"
parameter.
Parameters
- $host
- Either the "API" or "API content" hostname from
Dropbox\Client::getHost().
- $path
- The "path" part of the URL. For example, "/account/info".
- $params
URL parameters. For POST requests, do not put the parameters here.
Include them in the request body instead. Returns
string
|
public
HttpResponse
|
#
doGet( string $host, string $path, array|null $params = null )
Perform an OAuth-2-authorized GET request to the Dropbox API. Will automatically
fill in "User-Agent" and "locale" as well.
Perform an OAuth-2-authorized GET request to the Dropbox API. Will automatically
fill in "User-Agent" and "locale" as well.
Parameters
- $host
- Either the "API" or "API content" hostname from
Dropbox\Client::getHost().
- $path
- The "path" part of the URL. For example, "/account/info".
- $params
- GET parameters.
Returns
HttpResponse
Throws
|
public
HttpResponse
|
#
doPost( string $host, string $path, array|null $params = null )
Perform an OAuth-2-authorized POST request to the Dropbox API. Will automatically
fill in "User-Agent" and "locale" as well.
Perform an OAuth-2-authorized POST request to the Dropbox API. Will automatically
fill in "User-Agent" and "locale" as well.
Parameters
- $host
- Either the "API" or "API content" hostname from
Dropbox\Client::getHost().
- $path
- The "path" part of the URL. For example, "/commit_chunked_upload".
- $params
- POST parameters.
Returns
HttpResponse
Throws
|
public
Curl
|
#
mkCurl( string $url )
Create a Curl object that is pre-configured with Dropbox\Client::getClientIdentifier(),
and the proper OAuth 2 "Authorization" header.
Parameters
- $url
- Generate this URL using buildUrl().
Returns
Curl
|
public static
DateTime
|
#
parseDateTime( string $apiDateTimeString )
Parses date/time strings returned by the Dropbox API. The Dropbox API returns date/times
formatted like: "Sat, 21 Aug 2010 22:31:20 +0000".
Parses date/time strings returned by the Dropbox API. The Dropbox API returns date/times
formatted like: "Sat, 21 Aug 2010 22:31:20 +0000".
Parameters
- $apiDateTimeString
- A date/time string returned by the API.
Returns
DateTime
A standard PHP \DateTime instance.
Throws
|
public static
string
|
#
getAccessTokenError( string $s )
Given an OAuth 2 access token, returns null if it is well-formed (though
not necessarily valid). Otherwise, returns a string describing what's wrong with it.
Given an OAuth 2 access token, returns null if it is well-formed (though
not necessarily valid). Otherwise, returns a string describing what's wrong with it.
Parameters
Returns
string
|