In this article, we will explore accessing files in a Dropbox account by building a simple client for the Dropbox API. The client will perform some basic operations such as authentication, listing files, uploading and downloading files.
To keep the article short and readable, I will keep the code to a minimum and instead refer you to the full code available on PHPMaster's GitHub. To run the code you need a PHP Dropbox account with curl support and obviously.
Your starting point for anything related to developing with Dropbox should be the Dropbox Dev Center, where you can find its API reference for basic concepts and best practices. You can also download the official SDK, but PHP is not listed in the supported languages. There is also a link to the third-party PHP SDK on GitHub.
Our client will be structured more like the official Python client, but I noticed, especially on the OAuth part, some ideas and code from the PHP SDK above. We will have a DropboxSession object and a DropboxClient object. Take care of the hardest part first: getting and managing access credentials from Dropbox. Client object, which will then be used to perform API calls and obtain data. The session object below is a DropboxRESTClient object used to perform HTTP calls using cURL.
Tell Dropbox about your app
First, we need to register our application to obtain a unique API key pair with Dropbox. We need these keys to "import" our application and require authorization.
Log in to the Development Center and follow the "MyApps" link and select "Create an App". Dropbox will ask you for a name, description, and access type for your application.
The access type parameter specifies that your application will be able to read and write the file. The recommended value is the "Applications Folder" directory within the user's home, where a sandbox will be created. Selecting the "Full Dropbox" app will access the user's entire Dropbox.
Once your application is created, there will be an options page where you can edit its details and find its access credentials.
Newly created applications are in "development status". This lets us start development immediately and allows up to 5 other users to test it. When an app is ready for release, we can apply for production status and the Dropbox team will review it to make sure it complies with its terms and conditions and brand guidelines.
Coding Apps
I put my code in a subdirectory of my local Apache setup so that it is accessible at the URL http://localhost/mydropbox. The directory structure is:
The bootstrap.php file that performs the startup of the application will be in every front-end file, so let's get started with that.
I initialize a global configuration as an empty array variable and then specify some configuration values. The top three Dropbox-related access keys, keys, and access types from your app's details page. I then define some other useful settings: the path to the base root of the application, where some data will be saved, and the path to a PHP file that will contain the application's access token.
This access token file does not exist at the beginning of the file; it is created by the authorize.php page and populated with the credentials provided by Dropbox. This will be a standard PHP file that, if present, will be included in this script later. The content of the token file will look like:
$access_token = array (
"oauth_token_secret" => "abcdefghilmnopqr",
"oauth_token" => "stuvwxyzabcdefgh",
"uid" => "1234567"
);
oauth_token and oauth_token_secret access credentials, UID is the user's unique ID.
I set up PHP's error behavior in the next section of the bootstrap file and perform some requirement checks; in order to run the application the data directory must exist and be writable and the auth.php file must be writable if it exists. This will ensure that applications are free to do their jobs.
Finally, I include our library, initialize the PHP session, set an empty $access_token (will be filled in later), and, if it exists, include the auth.php file.
Each front-end script will run inside a main try/catch block. Before digging into the library code, we first need to understand the traffic, so I'll start with the authorization cycle.
Authorization
The first time we run our application, the index.php file will be true under the following conditions:
1
2 if (!isset($access_token)) {
3 header("Location: authorize.php");
4 exit;
5}
The access token is empty, so I redirect the user to the authorize.php page, which will manage the authorization process.
After the bootstrap phase I do another check for existing tokens. This will ensure that this script runs only when we don't have a token. To avoid infinite redirect loops, the auth.php file was removed from the script block's main catch if the error code returned was 401 (invalid token).
The first thing I do in every script is create a new DropboxSession object with our API key. When we call the script directly, the first condition is false and other blocks are executed. The session object connects to Dropbox and asks for a temporary token. The token is then parsed into an array and stored into the variable $_SESSION for the next stage.
We build a URL that is authorized to use this token. The user should be redirected or prompted to visit a URL where he will decide whether to allow or deny access to his data.
The authorization URL can contain an optional parameter that returns the URL. I'm just passing the URL of the current script, so if the user authorizes it redirects him to our script's application, which uses the time's oauth_token and UID values passed in the query string. The first condition now evaluates to true, so we can go and ask for a permanent access token.
This requested array of $tokens is this new oauth_token built with the previous oauth_token_secret, which is then passed to the obtainAccessToken() method. On success, we have our permanent (until revoked) access token. This has to be stored somewhere, the obvious choice is a database, but in this example we will export it as valid PHP code using the native var_export() function and write it to our auth.php file. Then redirect the user to the index page, this is the simplest script.
At the beginning of our try/catch block a new DropboxSession object is created, permanently this time with $access_token as the fourth parameter. This object is used to create DropboxClient objects. These two steps are common to all other scripts.
The client's public methods map to corresponding Dropbox API calls. I'm calling the AccountInfo() method, which returns an array containing the user's details: unique ID, name, email, quota information and referral link (refer to official documentation for more details).
Behind the Scenes: REST and Session Objects
Now that we have an overview of Surface Flow, allowing us to see what's going on under the hood, our Dropbox library is contained in the lib/Dropbox directory and consists of three categories.
stationary object
The lowest level class, our library is a REST client (see lib/dropbox/rest.php). This class is a simple wrapper for curl. It performs HTTP calls and returns output in raw or encoded format, or throws an exception in case of an error.
The constructor checks whether cURL is installed on the system, or throws an exception. It then tries to initialize the internal curl handler with $curlDefaults set. The handler is not set in the destructor.
() error and errno(), the () method is self-explanatory. We then have a series of utility methods, the get(), post() and put() methods that are simple wrappers around all the main requirements for the () method for it to actually work.
First, we set up the URL to get the HTTP method and required parameters, extra headers and POST (if any). Parameters are passed along the URL caller method for GET and PUT methods.
Before making the call, we need to tell curl to retrieve the entire contents, including the HTTP headers (set the option CURLOPT_HEADER), because some API methods (file_get(), of course) put their information in the headers.
The curl request being executed stores the result of curl_exec() into the response and meta-information variables are filled by curl_info() with relevant execution details. If the proposed method is used, we will also have to close the input file handle.
The meta-response content and meta-information we parse are the results and separate the HTTP headers from the body. By default, the body is returned as JSON decoded, unless the $raw parameter is set to true.
What's going on before, there is a bug check. Dropbox's API uses HTTP error codes for error notification. If the status code is greater than 400, an error has occurred and the error message is stored in the body. I extract this message and throw an exception. If there are no errors the HTTP header parsing result returns an array containing the status code, headers and body.
Session object
A basic REST client extended by the DropboxSession object to fill our needs:
Perform initial authentication/authorization traffic,
Included in every subsequent REST request to obtain validation data.
Constructs simple initializes internal variables. Another simple method is to build a temporary token authorization URL with buildAuthorizeURL(). The most important method of the class is:
obtainRequestToken() - Requests a temporary OAuth access token.
obtainAccessToken() - Access token for applications requiring permanent OAuth.
get() - performs the rest of the call, including all necessary authentication and signing parameters.
These three methods also have similar flows. First, they set up the base target URL and fill in the $params, sending the associated array with the required oauth_* key/values. Each API call must provide a timestamp and a unique randomly generated hash, $nonce parameter.
Then use the name of the HTTP method, URL, parameters to generate a signature. It then queues the $params array using the oauth_signature key. The URL is fetched with the given HTTP method and returned as part of the body of the response. For GET and PUT methods, the generated query string is appended to the URL using the local http_build_query() function.
obtainRequestToken and obtainAccessToken() are almost identical: one does not use a token and calls a GET HTTP method. The second HTTP method called a POST must include the token obtained with the previous call. This token is then used as part of the signing key for all following API calls.
The get() method performs some additional tasks. First, it requires an array named $args with any additional arguments required by the specific API, such as a list of resources or paths to upload/download files. These parameters are combined with the $params array before generating the signature. The only exception is to upload a file using the PUT method, enter the parameters in the file, extract and save, for later. A switch statement is used to tell the correct HTTP method to call.
The DropboxSession class has two utility methods, encodeParams() and getSignature(), in the above main method call encodeParams() prepares the request parameters for signature, while getSignature() generates an OAuth required signature in a given API call.
Finally the DropboxClient object
The DropboxClient object is our high-level interface to Dropbox. It exposes public API methods that use a mid-level DropboxSession object to perform API calls and return a script that handles the output of the call. In this post I have implemented a limited set of methods:
AccountInfo() - Gets the current Dropbox user details.
metadata() - Gets information about a Dropbox object (file or folder) and retrieves the folder object's content list.
GETFILE() - Downloads a file and its metadata and optionally saves it to disk.
PUTFILE() - The path to upload local files to remote Dropbox.
The session object and the URL to the base API are stored as internal variables and initialized in the constructor.
All methods follow more or less the same approach, so I'm going to point out the differences. All path handling methods must take into account the Dropbox root path for each call. The root path depends on the application's access type and can be "dropbox" if the application has full access or "sandbox" if the application has limited access. If this value does not match the application's remote settings, an error is returned.
The common steps performed by each method are:
Check and prepare parameter list.
Execute HTTP calls.
Parse and return the response.
The AccountInfo() method is simplest and calls the URL with no parameters and returns an associative array of responses.
filemetadata() method of list.php to get and display the contents of the directory. The only required parameter is the path to the file or directory to be checked, but it allows us to specify all other parameters of the corresponding API call. If the $PATH parameter is a file, the returned array contains metadata. If it is a folder, the content item contains its file list, unless the dollarlist argument is false. We can limit the size of the content with the $fileLimit parameter (up to a maximum of 25000), and we can ask for revision of a specific file or folder (see API reference for details).
It's important to note that the Dropbox API returns a hash value for each call. If we were to list the contents of a folder and provide a hash parameter that has changed since the last call to our method, the API checks to see if the output is there. If not, it returns a 301 status code (which cannot be modified). The team at Dropbox recommends caching the results and relying on these folder list values to optimize performance.
The GETFILE() method is used to retrieve files stored in the user's Dropbox. The entire file content is returned as a JSON string on a successful call to X-Dropbox's metadata, with its metadata stored in a custom HTTP header. The return value of this method is an associative array containing the name, MIME type, metadata and content. Additionally, I have added the $outfile parameter to save the file directly on disk.
The download.php file shows a demonstration of how this is done. In this example, the downloaded file is saved directly to the application's data directory, and part of the response is cleared.
The PUTFILE() method uploads files from our local storage to the user's Dropbox using the PUT HTTP method, which is preferred by the Dropbox team instead of publishing. This method checks that the local file exists and does not exceed the 150MB API limit before any other common actions.
Supported arguments for this method are in addition to the path to the source file, the destination folder, an optional alternative name and override options. If this last option is false and the remote file exists, the uploaded file is named with a progressive number (e.g. test(1).txt becomes test.txt). The API also allows an optional parent_rev parameter to manage modifications, but I decided to ignore it to keep things simple.
Summary
This is just a small part of the Dropbox API, but it can be enough as a starting point to develop your own applications. For me, it's also a great opportunity to play with OAuth. Feel free to improve and expand this article to suit your needs, and as always: Happy Coding Code!
![[Web front-end] Node.js quick start](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
