omnidrive/dropbox API reference

Omnidrive\Dropbox

DropboxAdapter class

final class DropboxAdapter extends SpatieDropboxAdapter implements TemporaryUrlGenerator DropboxAdapter.php:33

spatie/flysystem-dropbox's adapter, where it parts from Flysystem's contract:

• deleting a file or a directory that is not there is no error (the adapter's is an exception, and for a directory not one of Flysystem's);
• a file's visibility is "not kept" (an UnableToRetrieveMetadata), not an empty attribute that Flysystem's typed visibility() cannot return;
• a checksum is the file's own (md5, sha1...: Flysystem reads the file and hashes it) - the adapter gave Dropbox's content_hash for sha256 and a hash of that hash for any other; "dropbox" asks for the content_hash itself;
• a temporary address is Dropbox's temporary link (four hours), under the drive's prefix.

Everything else is the adapter's.

const TEMPORARY_LINK_LIFETIME = 4 * 3600

How long Dropbox's temporary link serves the file.

DropboxAdapter::__construct()

public function __construct(Client $client, string $prefix = '')

DropboxAdapter::delete()

public function delete(string $path): void

DropboxAdapter::deleteDirectory()

public function deleteDirectory(string $path): void

DropboxAdapter::visibility()

public function visibility(string $path): FileAttributes

DropboxAdapter::checksum()

public function checksum(string $path, Config $config): string

DropboxAdapter::temporaryUrl()

public function temporaryUrl(string $path, \DateTimeInterface $expiresAt, Config $config): string

DropboxDriveFactory class

final class DropboxDriveFactory extends FlysystemDriveFactory DropboxDriveFactory.php:31

A folder of Dropbox, through spatie/flysystem-dropbox (spatie/dropbox-api, Guzzle):

(new DropboxDriveFactory())->create(['refresh_token' => '...', 'app_key' => '...', 'app_secret' => '...', 'prefix' => 'site']); (new DropboxDriveFactory())->create(['access_token' => '...']);

Options: refresh_token with app_key and app_secret (the access token renewed on its own: what an app is given since Dropbox's tokens expire in four hours), or access_token (as it is, until it expires); prefix (every path under it: an app folder's app is already confined to its folder); team_member_id (a team's member the requests act as), namespace_id (a team space's root); chunk_size (bytes per request of a large upload, 150 MB at most); public_url (Dropbox serves none of its own).

temporaryUrl() is Dropbox's temporary link, which serves the file four hours: asked for longer, it is refused. Dropbox keeps no visibility per file. Nothing is sent until the first operation.

Options

DropboxDriveFactory::__construct()

public function __construct(readonly ?ClientInterface $http = null)

RefreshTokenProvider class

final class RefreshTokenProvider implements RefreshableTokenProvider RefreshTokenProvider.php:19

Dropbox's short-lived access tokens (four hours since 2021), renewed from a refresh token and the app's key and secret: asked on the first request, again a minute before it expires, and when Dropbox answers 401. A refresh token Dropbox refuses, or its token endpoint out of reach, is a TokenRefusedException naming why (every drive operation then fails with it, as a DriveException).

const TOKEN_URL = 'https://api.dropboxapi.com/oauth2/token'

RefreshTokenProvider::__construct()

public function __construct(readonly string $refreshToken, readonly string $appKey, readonly string $appSecret, ?ClientInterface $http = null)

RefreshTokenProvider::getToken()

public function getToken(): string

RefreshTokenProvider::refresh()

public function refresh(ClientException $exception): bool

TokenRefusedException class

final class TokenRefusedException extends RuntimeException implements FilesystemException TokenRefusedException.php:12

Dropbox did not give an access token for the refresh token: refused (revoked, malformed, the app's key or secret wrong: {"error": "invalid_grant"...}), or its token endpoint not reached.

A Flysystem exception, so every drive operation turns it into a DriveException that names it.