Methods summary
public
Dropbox\Config
|
#
getConfig( )
The config used when making requests to the Dropbox server.
The config used when making requests to the Dropbox server.
Returns
|
public
Dropbox\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
|
public
|
#
__construct( Dropbox\Config $config, Dropbox\AccessToken $accessToken )
Constructor.
use \Dropbox as dbx;
$config = new Config(...);
list($accessToken, $dropboxUserId) = $webAuth->finish(...);
$client = new dbx\Client($config, $accessToken);
Parameters
|
public
array
|
#
getAccountInfo( )
Returns a basic account and quota information.
Returns a 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 = ...;
$metadata = $client->getFile("/Photos/Frog.jpeg",
fopen("./Frog.jpeg", "wb"));
print_r($metadata);
Parameters
- $path
string
$path The path to the file on Dropbox (UTF-8).- $outStream
resource
$outStream If the file exists, the file contents will be written to this stream.- $rev
string|null
$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|arrayThe 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 = ...;
$md1 = $client->uploadFile("/Photos/Frog.jpeg",
dbx\WriteMode::add(),
fopen("./frog.jpeg", "rb"));
print_r($md1);
$md2 = $client->uploadFile("/Photos/Frog.jpeg",
dbx\WriteMode::update($md1["rev"]),
fopen("./frog-new.jpeg", "rb"));
print_r($md2);
Parameters
- $path
string
$path The Dropbox path to save the file to (UTF-8).- $writeMode
Dropbox\WriteMode
$writeMode What to do if there's already a file at the given path.- $inStream
resource
$inStream- $numBytes
integer|null
$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
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->uploadFile("/Grocery List.txt",
dbx\WriteMode::add(),
"1. Coke\n2. Popcorn\n3. Toothpaste\n");
print_r($md);
Parameters
- $path
string
$path The Dropbox path to save the file to (UTF-8).- $writeMode
Dropbox\WriteMode
$writeMode What to do if there's already a file at the given path.- $data
string
$data The data to use for the contents of the file. Returns
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
string
$path The Dropbox path to save the file to (UTF-8).- $writeMode
Dropbox\WriteMode
$writeMode What to do if there's already a file at the given path.- $inStream
resource
$inStream- $numBytes
integer|null
$numBytes The number of bytes available from $inStream. You can pass in
null if you don't know.- $chunkSize
integer|null
$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
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
string
$data The data to start off the chunked upload session. Returns
arrayA 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
string
$uploadId The unique identifier for the chunked upload session. This is obtained
via Dropbox\Client::chunkedUploadStart().- $byteOffset
integer
$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
string
$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.
Parameters
- $uploadId
string
$uploadId The unique identifier for the chunked upload session. This is obtained
via Dropbox\Client::chunkedUploadStart().- $path
string
$path The Dropbox path to save the file to ($path).- $writeMode
Dropbox\WriteMode
$writeMode What to do if there's already a file at the given path. Returns
array|nullIf 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
string
$path The Dropbox path to a file or folder (UTF-8). Returns
array|nullIf 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
string
$path The Dropbox path to a file or folder (UTF-8). Returns
array|nullIf 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
string
$path The Dropbox path to a folder (UTF-8).- $previousFolderHash
string
$previousFolderHash The "hash" field from the previously retrieved folder
metadata. Returns
arrayA 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 )
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
string|null
$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. Returns
arrayA 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
string
path The Dropbox path that you want file revision metadata for (UTF-8).- $limit
integer|null
limit The maximum number of revisions to return. Returns
array|nullA list of 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
string
$path The Dropbox path of the file to restore (UTF-8).- $rev
string
$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.
Parameters
- $basePath
string
$basePath The path to limit the search to (UTF-8). Pass in "/" to search
everything.- $query
string
$query A space-separated list of substrings to search for. A file matches only
if it contains all the substrings.- $limit
integer|null
$limit The maximum number of results to return.- $includeDeleted
boolean
$includeDeleted Whether to include deleted files in the results. Returns
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
string
$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.
Parameters
- $path
string
$path The Dropbox path to a file or folder (UTF-8). Returns
array
A list(string $url, \DateTime $expires)
where <code>$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.)
Parameters
- $path
string
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.
Parameters
- $path
string
$path The path to the file you want a thumbnail for (UTF-8).- $format
string
$format One of the two image formats: "jpeg" or "png".- $size
string
$size One of the predefined image size names, as a string:
- "xs" - 32x32
- "s" - 64x64
- "m" - 128x128
- "l" - 640x480
- "xl" - 1024x768
Returns
array|nullIf 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
Parameters
- $fromPath
string
$fromPath The Dropbox path of the file or folder you want to copy (UTF-8).- $toPath
string
$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).
Parameters
- $copyRef
string
$copyRef A copy ref obtained via the Dropbox\Client::createCopyRef() call.- $toPath
string
$toPath The Dropbox path you want to copy the file or folder to (UTF-8). Returns
Throws
|
public
array|null
|
#
createFolder( string $path )
Creates a folder.
Parameters
- $path
string
$path The Dropbox path at which to create the folder (UTF-8). Returns
array|nullIf 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
string
$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
string
$fromPath The source Dropbox path (UTF-8).- $toPath
string
$toPath The destination Dropbox path (UTF-8). Returns
Throws
|
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
string
$apiDateTimeString A date/time string returned by the API. Returns
DateTime
A standard PHP \DateTime instance.
Throws
|