Storage Mechanisms
To ensure we don't attempt to obtain an access token for each user request, we must store them. This is the job of Storage Mechanisms. There are several handlers provided with the library and you can also roll your own. Implementations of each are described below.
Use of the Encrypter object is not mandatory but it is advised that you use it in production. OAuth access tokens should be handled sensitively and never in plain text. Access tokens allow your application (or an attacker) to interact with the Service Provider on behalf of the user the token is obtained for and should be handled as sensitively as a username/password combination.
This library does not provide any method of storing encryption keys. The examples provided store the key in a variable which is accessible to anyone who obtains your source. This is NOT a suitable production implementation.
The session storage handler uses PHP sessions to provide transient storage for access tokens. Whilst this is not suitable for applications that require permanent storage it is used internally by the mechanisms that do provide permanent storage to reduce overheads on subsequent calls (e.g. database queries).
// Instantiate the Encrypter, passing it a 32-byte key
$key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$encrypter = new \Dropbox\OAuth\Storage\Encrypter($key);
// Instantiate the storage object, passing it the Encrypter
$storage = new \Dropbox\OAuth\Storage\Session($encrypter);
The PDO handler uses a MySQL database to provide persistent storage for access tokens. It allows the library to be used in an application where a user system already exists, without the need to modify it in any way. Once a token is retrieved from the database it is stored in the user's session to prevent any unnecessary database overhead.
// Instantiate the Encrypter, passing it a 32-byte key
$key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$encrypter = new \Dropbox\OAuth\Storage\Encrypter($key);
// Instantiate the storage object, passing it the Encrypter and the user ID
$userID = 1; // The authenticated user's ID e.g. $_SESSION['userID']
$storage = new \Dropbox\OAuth\Storage\PDO($encrypter, $userID);
// Connect to the database, optionally specifying a non-default port as the 5th argument
$storage->connect('hostname', 'database', 'username', 'password', 3306);
The handler will use the table dropbox_oauth_tokens by default. You can change this by calling $storage->setTable('my_table_name'). In either case, if the table does not exist it will be created auto-magically providing your database user has the correct permissions. If your user does not have the permissions required to create a table, the schema is defined in TableSchema.sql.
The Filesystem handler stores access tokens on disk. A popular example of where this mechanism is used is to provide access to a specific Dropbox where no user system is currently present or required (e.g. upload files directly to Dropbox from a web form).
Tokens should be stored in a non-web-facing directory, and for this reason there is no default storage directory set. When using this handler you MUST call $storage->setDirectory($dir). Failure to do so will result in a \Dropbox\Exception being thrown.
// Instantiate the Encrypter, passing it a 32-byte key
$key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$encrypter = new \Dropbox\OAuth\Storage\Encrypter($key);
// Instantiate the storage object, passing it the Encrypter and identifier
$identifier = 1; // Fixed identifier for single-user system OR authenticated user ID
$storage = new \Dropbox\OAuth\Storage\Filesystem($encrypter, $identifier);
$storage->setDirectory('/outside/web/root/tokens');
Thanks to @jschmid for this contribution.
Writing your own storage handler is easy - write a class that implements the Dropbox\OAuth\Storage\StorageInterface. Any contributed mechanisms must extend the session handler and use it to store tokens after initial retrieval (see Filesystem/PDO for reference).