Dropbox Php Sdk Laravel Package

Getting Started

This is a minimal maintenance fork of the Dropbox PHP SDK, not a Laravel-first package. Treat it as a thin, dependency-light HTTP client for the Dropbox API v2 that you wire into Laravel yourself.

Install and pin

composer require <vendor>/dropbox-php-sdk:"^0.5"

Because the fork is on 0.x semver, only patch releases (0.5.x) are guaranteed non-breaking. Pin to ^0.5 and let Composer take 0.5.1, but do not float to ^0.6 blindly — the maintainers explicitly reserve the right to change things between minor versions.

Verify the runtime fit first

v0.5.1 targets PHP 8.1–8.5 and guzzlehttp/guzzle:^7. Check php -v and composer show guzzlehttp/guzzle before anything else; if you are still on Guzzle 6 or PHP 8.0, this release is not for you.

Where to look first

1. composer.json in the package — confirm the supported PHP/Guzzle matrix.
2. The README's "maintenance scope" section — it tells you what won't get fixed.
3. The upstream SDK docs (kunalvarma05/dropbox-php-sdk) — the public API is intentionally preserved, so upstream examples still apply.

First use case: a signed-URL file drop

The most common Laravel use is small, server-side file operations — upload a generated PDF, or list/read a folder. Bind the client once in a service provider:

// config/services.php
'dropbox' => [
    'client_id'     => env('DROPBOX_CLIENT_ID'),
    'client_secret' => env('DROPBOX_CLIENT_SECRET'),
    'access_token'  => env('DROPBOX_ACCESS_TOKEN'),
],

// app/Providers/AppServiceProvider.php
$this->app->singleton(DropboxClient::class, fn () => new DropboxClient(
    config('services.dropbox.client_id'),
    config('services.dropbox.client_secret'),
    config('services.dropbox.access_token'),
));

Then inject it into a job or controller. That is the whole integration — there is no service provider, facade, or config file shipped by the package.

Implementation Patterns

Wrap it, don't sprinkle it. The SDK throws its own exception hierarchy and returns its own model objects. Put a single DropboxStorage-style class in app/Services that owns the client and translates to Illuminate-friendly types (arrays, Storage-like methods, RuntimeException). This is your upgrade firewall: if 0.6 shifts a signature, you change one class.

Push uploads onto the queue. Dropbox round trips are 200–2000 ms and can rate-limit. A job with $tries = 3, backoff = [10, 60, 300] and failed() logging is the right shape. The SDK has no built-in retry, so Laravel's job retries are your retry mechanism.

class UploadToDropbox implements ShouldQueue
{
    use Queueable, InteractsWithQueue;

    public int $tries = 3;
    public array $backoff = [10, 60, 300];

    public function __construct(public string $localPath, public string $remotePath) {}

    public function handle(DropboxStorage $dropbox): void
    {
        $dropbox->upload($this->localPath, $this->remotePath);
        @unlink($this->localPath);
    }
}

Use chunked/session upload for anything over ~150 MB. The single-shot upload endpoint has a hard size cap; the SDK exposes the upload-session calls for this. Stream from Storage::readStream() rather than file_get_contents() so you don't blow memory_limit on a queue worker.

Don't expect a Flysystem disk. This SDK is not a league/flysystem adapter, so Storage::disk('dropbox') will not work out of the box. If you want the Laravel filesystem API, either pair this SDK with a separate Flysystem Dropbox adapter, or write a small custom driver that delegates to your wrapper service. Don't try to make the SDK pretend to be a disk — the semantics (paths vs. IDs, cursors vs. listing) diverge.

elFinder integration is the reference use case. The fork exists largely to keep elFinder's Dropbox volume alive. If you run a file manager in a Laravel admin panel, that is the supported path; everything else is "works, but you own it."

Token handling belongs to you. The SDK takes an access token string. Short-lived tokens (the default for new Dropbox apps) need a refresh flow — implement refresh_token → new access token → cache in Cache::remember with a TTL slightly below expiry, and a RefreshDropboxToken listener or a wrapping client that refreshes on 401. The fork will not do this for you.

Testing: Http::fake() does nothing here — the SDK uses Guzzle directly, bypassing Laravel's HTTP client. Inject a GuzzleHttp\Client with a MockHandler, or (better) bind a fake DropboxStorage interface in the container and assert on your job, not on Dropbox.

Gotchas and Tips

0.x semver is the biggest risk. 0.5.1 is safe as a patch. The maintainers state plainly that the scope is "compatibility and stability over new features" — which is good for you, but also means a CVE or a Dropbox API change may sit unfixed. Have an exit plan: your wrapper service should be thin enough to swap to the official Dropbox SDK or raw HTTP in a day.

PHP 8.4 nullable fixes are the headline — and they only cover the package's own code. If you have subclasses or calls that extend SDK classes, re-run your test suite on 8.4/8.5; implicit-nullable deprecations can still surface from your signatures. Enable E_DEPRECATED in a staging run rather than discovering it in production logs.

Guzzle ^7 only. If another dependency pins guzzlehttp/guzzle:^6, Composer will either fail or silently keep you on an older SDK version. Run composer why guzzlehttp/guzzle when resolution gets weird.

Exceptions are not Laravel exceptions. Catch the SDK's own types, not Illuminate\Http\Client\RequestException. Distinguish at minimum: auth failure (refresh token, don't retry), rate limit / 429 (retry with backoff), path-not-found (permanent, fail the job), conflict (write mode), and transient 5xx (retry). A blanket catch (\Exception $e) will retry auth failures forever and burn your queue.

Rate limits are real and per-app. Bulk jobs that fan out hundreds of uploads will hit 429 quickly. Throttle the job middleware (RateLimited('dropbox')) or serialize with a WithoutOverlapping lock keyed on the account.

Path semantics bite. Dropbox paths are case-insensitive, must start with /, and differ from the display path when the app uses an app-folder scoped permission. Normalize in your wrapper — one normalizePath() used everywhere.

Large-file listing uses cursors. listFolder is paginated; a naive call returns a partial result set. Loop until has_more is false or you will silently miss files in sync jobs.

Debugging: the SDK has no logging hooks. Attach a Guzzle middleware (Middleware::log() with a PSR-3 logger, redacting Authorization) at the point you construct the client, and guard it behind config('app.debug'). Without this you get opaque failures.

Config quirks: nothing is auto-discovered. Cache config:cache is fine, but never read env() outside config/ — the token will come back null in production and produce a confusing 401 rather than an obvious missing-config error.

Extension points to prefer: (1) your wrapper service, (2) a Guzzle middleware stack, (3) a container binding for the client. Avoid patching the vendor directory — the fork's whole value proposition is that it stays close to upstream, so a local patch will conflict on the next 0.5.x bump.