With DropLib you get a fast and easy to use PHP DropBox API Library. Unlike other implementations out there, this class does not rely on PHPs OAuth extension, which is not available at most hosting services, to authorize its API calls but uses a lightweight pure PHP class.
It allows you to up- and download, copy, move, rename and delete files, to display thumbnails of images and retrieve varius directory and account informations.
Requirements:
To use DropLib within your project, all you have to do is move the "droplib" folder somewhere inside your project path and include the file "DropLib.php".
/* This is your project file */
/* Include DropLib */
include 'path/to/droplib/DropLib.php';
$params = array(
'consumerKey' => 'yourconsumerkey',
'consumerSecret' => 'yourconsumersecret'
);
$DropLib = new DropLib($params);
/* Do something with DropLib */
Everytime DropLib encounters an error for some reason, it throws an exception of a specific type, to let you know what kind of error you have to deal with. Use $DropLibException->getMessage() for a (detailed) error message, where $DropLibException is the thrown exception instance.
Exception types:
Use the constructor to create a new instance of DropLib.
Parameters:
$params = array(
'consumerKey' => 'yourconsumerkey',
'consumerSecret' => 'yourconsumersecret',
'sslCheck' => false
);
$DropLib = new DropLib($params);
Use this if you want to change the API root directory after instantiating a DropLib object.
//set root to dropbox
$DropLib->setRoot('dropbox');
//set root to sandbox
$DropLib->setRoot('sasndbox');
For more information about the "sandbox mode" refer to: dropbox.com/developers/docs
Returns the currently set API root folder. Either "dropbox" or "sandbox".
Use this if you want to change the SSL certificate check state.
//disable SSL check $DropLib->setSslCheck(false); //enable SSL check $DropLib->setSslCheck(true);
Returns the current user token as associative array.
print_r( $DropLib->getToken() );
/* This generates:
Array
(
[key] => jo9s51fviucXXXX
[secret] => em25m7c606uXXXX
)
*/
This is an overview of the three function, which are needed for the oAuth authorization workflow and the workflow itself. For further information refer to the "Further Information" section in this documentation.
Step 1:
Step 2:
Step 3 - ∞ (Everytime you want to connect to the API with a previous authorized user):
Fetches the oAuth request token (Step 1 of the oAuth workflow), saves it internally for further use and returns the request token as an associative array:
Array
(
[key] => jo9s51fviucXXXX
[secret] => em25m7c606uXXXX
)
Get the oAuth authorization URL (Step 2 of the oAuth workflow).
After successfull authorization, DropBox will redirect the user to the URL set via $callback.
Returns the oAuth authorization URL as string.
$url = $DropLib->authorizeUrl('http://mydomain.tld/myservice/?someparam=somevalue');
/* This will return something like:
https://www.dropbox.com/0/oauth/authorize?oauth_token=jo9s51fviucXXXX&oauth_callback=http://mydomain.tld/myservice/?someparam=somevalue
*/
Fetches the oAuth accesstoken (Step 3 of the oAuth workflow), saves it internally for further use and returns the accesstoken as an associative array:
Array
(
[key] => jo9s51fviucXXXX
[secret] => em25m7c606uXXXX
)
Fetch oAuth user token by passing email adress and password. Use this to bypass the usual oAuth authorization procedure. For futher details see: https://www.dropbox.com/developers/web_docs#authentication-for-web
Returns an associative array. See getToken() within Library Functions for an example.
Note: Do not authorize the user everytime you work with the API, but rather save the returned token to a database for reuse with the DropLib constructor. The token expires, according to dropbox, after 10 years.
Note: This function is marked as deprecated an it's very likely that this function will be removed with the next major DropBox-API update. Use the full oAuth workflow instead!
Retrieves information about the users account.
Returns an associative array:
Array
(
[referral_link] => https://www.dropbox.com/referrals/NTE0MjU5NDXXXX
[display_name] => Jon Q. User
[uid] => 1425XXXX
[country] => US
[quota_info] => Array
(
[shared] => 0
[quota] => 2415919104
[normal] => 30715683
)
[email] => jon.user@provider.com
)
The createAccount functions allows you to create a new DropBox account from within your application.
Note: This function has been marked as deprecated and will possible be removed with one of the next DropBox-API updates.
Retrieves the contents of the file specified by $path.
// Get file from subfolder
$fileContents = $DropLib->download('folder/myfile.ext');
// Get file from root folder
$fileContents = DropLib->download('myfile.ext');
Returns the raw file contents as String.
Uploads the file specified by $file to the dropbox and puts it the the folder specified by $path. (Max. 300MB)
$DropLib->upload('folder/subfolder/', '/path/to/my/local/file.ext');
Returns true if the uplaod was successfull.
Note: On most hosts, you have to pass an absolute path for $file, to satisfy cURL.
Retrieve varius folder / file metadata such as filesize and -age. Also you can generate directory listings.
Parameters:
Returns an associative array:
Array
(
[hash] => 9fad35fa1c7c9cf2f20d014e6bXXXXXX
[revision] => 129
[thumb_exists] =>
[bytes] => 0
[modified] => Mon, 14 Mar 2011 18:28:33 +0000
[path] => /Testing
[is_dir] => 1
[icon] => folder
[root] => dropbox
[contents] => Array
(
[0] => Array
(
[revision] => 133
[thumb_exists] =>
[bytes] => 429848
[modified] => Mon, 14 Mar 2011 20:29:04 +0000
[path] => /Testing/file.ext
[is_dir] =>
[icon] => page_white
[mime_type] => application/octet-stream
[size] => 419.8KB
)
)
[size] => 0 bytes
)
Generates and returns a thumbnail if $path points to an image. The images will be shrinked proportional to fit the given size.
Parameters:
Returns a base64 encoded thumbnail file.
$format = 'JPEG';
$thumb = $DropLib->thumbnail('folder/myimage.jpg', 'medium', $format);
echo '<img src="data:image/' . $format . ';base64,' . $thumb . '" />';
/* this will output something like:
<img src="data:image/JPEG;base64,TWFuIGlzIGR[...]pc3Rpbmd1" />
*/
Copies a file or a directory specified by $from to $to.
$DropLib->copy('folder_a/file.ext', 'folder_b/file.ext');
Returns metadata for the file / directory at its new location (See metadata function for examples).
Create a new folder, relative to DropBox root.
$DropLib->createFolder('folder/subfolder');
Returns metadata for the new directory (See metadata function for examples).
Deletes a file or a directory.
$DropLib->delete('folder/subfolder/file.ext');
Moves a file or directory. Also, you can use this to simply rename a file / directory.
$DropLib->move('folder/subfolder', 'another/folder/subfolder');
$DropLib->move('folder/image.jpg', 'folder/me.jpg');
Returns metadata for the file / directory at its new location (See metadata function for examples).
BUGFIX: Root directory gets set correctly when set on instantiation
CHANGE: Removed size parameter validation in function thumbnail() BUGFIX: Function thumbnail() now returns correct base64 encoded data
NEW: Complete code rewrite with architectural, maintainability and perfomance improvements. NEW: Full oAuth workflow support. CHANGE: Some functions calls are not compatible to old ones. (Sorry for this one!) BUGFIX: Handle file and folder names with spaces correctly. BUGFIX: Various other minor bugfixes.
BUGFIX: Download function did not work properly, due to API-internal changes.
NEW: Initial Release
If you should encounter any further questions or you need support using or customizing this library, feel absolutely free to send a message to support@jonasdoebertin.net. I will do my very best to help and assist you as quick as possible.
Thanks:
For further information about the DropBox API visit: