Flysystem Dropbox Laravel Package

Getting Started

Before writing a line of code, confirm you actually need this package. league/flysystem-dropbox was archived in 2015, targets Flysystem 1.x, and wraps the retired Dropbox API v1 PHP SDK (dropbox/dropbox-sdk v1). Against today’s Dropbox it will not authenticate or list files — expect 400/401/410 responses before you ever reach your own logic.

Where to look first:

1. composer.json / composer.lock in the host project. If you see league/flysystem-dropbox, note the pinned Flysystem version (^1.0) — that constraint will fight every other package you try to upgrade.
2. The code that instantiates League\Flysystem\Filesystem and League\Flysystem\Dropbox\DropboxAdapter. That is the only place you need to change for a migration.
3. Any Storage::disk('dropbox') calls — these do not need to change if you keep the disk name.

First use case (for a legacy app still holding this dependency): replace the adapter, don’t fight it. The drop-in successor is spatie/flysystem-dropbox, which speaks Dropbox API v2 and works with Flysystem 1.x and 3.x.

composer remove league/flysystem-dropbox
composer require spatie/flysystem-dropbox

Then swap the adapter class in your service provider:

// before
use League\Flysystem\Dropbox\DropboxAdapter;
use Dropbox\Client;

$adapter = new DropboxAdapter(new Client($token, $appName));

// after
use Spatie\Dropbox\Client;
use Spatie\FlysystemDropbox\DropboxAdapter;

$adapter = new DropboxAdapter(new Client($token));

Implementation Patterns

Legacy instantiation (what you’ll find in inherited code). Flysystem 1.x adapters are constructed directly and passed to Filesystem:

$client  = new Dropbox\Client($accessToken, 'my-app');
$adapter = new DropboxAdapter($client);
$filesystem = new League\Flysystem\Filesystem($adapter);

$filesystem->write('reports/2024-q1.pdf', $contents);
$filesystem->read('reports/2024-q1.pdf');
$filesystem->listContents('reports', true);

Laravel disk registration. Laravel 5.x projects typically register a custom driver in a service provider so Storage::disk('dropbox') works:

Storage::extend('dropbox', function ($app, $config) {
    $client  = new \Dropbox\Client($config['token'], $config['app']);
    return new \League\Flysystem\Filesystem(new DropboxAdapter($client));
});

Keep the disk name and driver key identical when migrating — only the adapter and client classes change. Everything downstream (Storage::disk('dropbox')->put(...), ->url(), ->exists()) stays put.

Migration pattern that minimizes risk. Isolate the adapter construction in one factory or service provider method. Then the migration is a single-file change, and you can run the old and new adapter side-by-side against the same Dropbox account in a staging environment before cutting over.

Testing pattern. Never hit Dropbox in unit tests. Use League\Flysystem\Memory or League\Flysystem\Local adapters behind the same Filesystem interface, and reserve the Dropbox adapter for a smoke test in CI/staging that exercises write, read, listContents, delete. Because the abandoned adapter and the Spatie replacement share the same public Flysystem API, your tests do not need to change when you migrate.

Filesystem-as-abstraction tip. Any code that only calls Filesystem methods is portable. Any code that type-hints DropboxAdapter or touches $adapter->getClient() is not. Grep for those before migrating.

Gotchas and Tips

• The API is dead, not just the package. The bundled dropbox/dropbox-sdk v1 talks to Dropbox API v1, which Dropbox shut down in 2017. This is why the package cannot be “revived” with a composer update — the protocol itself changed. Migration to an API v2 client is mandatory, not optional.
• Composer deadlock. league/flysystem-dropbox requires flysystem ^1.0. If any other dependency needs Flysystem 3, Composer will refuse to install. You cannot simply bump Flysystem; you must swap the adapter. spatie/flysystem-dropbox supports both 1.x and 3.x, so it is the escape hatch.
• No security patches. Archived since 2015 means no PHP 8 compatibility, no PSR-4 fixes, no dependency updates. Treat any use as a supply-chain risk.
• Metadata shape differences. Flysystem 1.x listContents() returns arrays with type, path, timestamp, size. Flysystem 3.x returns FileAttributes objects. If you migrate and upgrade Flysystem, audit every listContents consumer — that is where most migration bugs hide.
• Dropbox path quirks. Dropbox paths are case-insensitive but case-preserving, and root paths differ ('' vs '/'). The old adapter does not normalise consistently; the Spatie adapter is stricter. Run a path-normalisation smoke test after migration.
• Debugging the old adapter. Enable Flysystem’s Logger plugin, or point Guzzle’s HTTP client at a debug middleware, to see the actual request/response. A 401 from write() almost always means the SDK/app credentials, not your code.
• Extension points. Flysystem plugins (mount manager, caching, path-prefixing) port cleanly because they sit above the adapter. Anything that reaches into $adapter->getClient() or the raw Dropbox SDK will not port — rewrite those to go through Filesystem instead.
• Dependents count is zero. There is no community to lean on for this package. When something breaks, the Spatie package’s issue tracker and Dropbox’s API v2 docs are your real references.