Flysystem Dsn Bundle Laravel Package

Getting Started

• Confirm what you're installing first. webalternatif/flysystem-dsn-bundle is a Symfony bundle, not a Laravel package. It ships a Symfony Bundle class and expects config/bundles.php + config/packages/flysystem_dsn.yaml. Laravel will not auto-discover it, and there is no service provider, facade, or artisan command to rely on.

• In a Laravel app the realistic path is to use it as a reference implementation / spec for DSN-based Flysystem configuration, and wire the same idea through Laravel's own FilesystemManager. Install the pieces you actually need:

  composer require league/flysystem league/flysystem-aws-s3-v3
  

• First use case: collapse a multi-key disk config into one env var.

  FILESYSTEM_DSN=s3://KEY:SECRET@my-bucket?region=eu-west-1
  

  Then register a custom driver in AppServiceProvider::boot():

  Storage::extend('dsn', function ($app, $config) {
      $dsn = $config['dsn'];
      // parse scheme/host/user/pass/query, then build the adapter
      return new Filesystem($adapter);
  });
  

• If you genuinely are on Symfony, read the bundle's README first, then DependencyInjection/ and the DSN parser class — that parser is the only part with transferable value for Laravel.

Implementation Patterns

• DSN-per-disk with a thin driver. Keep config/filesystems.php declarative and put all parsing in one small, testable class (App\Support\Flysystem\DsnAdapterFactory) rather than inline in the closure. Return a League\Flysystem\Filesystem so the rest of Laravel (Storage::disk(), Storage::fake()) behaves normally.
• Map DSN → adapter explicitly. A match ($scheme) over s3, local, ftp, sftp, memory with a throw new InvalidArgumentException("Unsupported DSN scheme") default. Do not try to dynamically resolve adapter classes from the scheme string; that is the pattern the Symfony bundle can afford and you generally cannot.
• Per-tenant / dynamic disks. Build the DSN at runtime from a model and register a disk via config(["filesystems.disks.tenant_$id" => [...]]) before first access, or use Storage::build([...]) (Laravel 9+) which avoids polluting the config repository entirely. This is where DSN config pays off most.
• Environment matrix. Use distinct DSNs per environment but keep the shape identical, so Storage::disk('uploads') never branches on env in application code. Put the DSN in config/filesystems.php ('dsn' => env('FILESYSTEM_DSN')), never call env() at runtime.
• Testing. Point the DSN at memory:// or local:// in phpunit.xml, and still use Storage::fake('uploads') for assertions — fakes short-circuit the driver, so DSN parsing does not run in most feature tests. Add one unit test that exercises the parser directly.
• If mirroring the bundle's Symfony config in Laravel, keep a single config/flysystem_dsn.php file with a filesystems array of name => dsn, and a service provider that loops over it registering drivers. One place to audit, one place to cache.

Gotchas and Tips

• Installing it in Laravel is a dead end. Composer will pull it in, but the bundle's Extension/Configuration classes are Symfony DI constructs. You'll get unused classes and a stray Symfony dependency, not working disks. Prefer depending on league/flysystem + the specific adapter.
• Version 0.9.0 is pre-1.0. Treat the public API and DSN grammar as unstable; pin exactly ("webalternatif/flysystem-dsn-bundle": "0.9.0") and read CHANGELOG.md before every bump. The v0.9.0 release (Oct 2026) is a changelog-only pointer, so verify the diff yourself rather than assuming it's additive.
• URL-encoding bites. Secrets containing /, +, @, or ? must be percent-encoded in the userinfo/query. AWS secret keys frequently contain / and + — a "working" DSN in dev will 403 in prod. Prefer assembling the DSN with http_build_query() for the query and rawurlencode() for credentials, or sidestep it by keeping credentials in separate config keys and only DSN-ing the non-secret parts.
• Query-string options are a lowest-common-denominator surface. Adapter-specific options (S3 use_path_style_endpoint, ACL, SSE, FTP passive mode, timeouts) are often not expressible. When you hit one, add a 'options' => [...] array alongside 'dsn' and merge it over parsed values, so the DSN stays the simple path and the array is the escape hatch.
• Config caching. php artisan config:cache freezes your DSN. Any runtime-built DSN (tenant buckets) must be injected via Storage::build() or config()->set() at request time — never env() inside the parser.
• Debugging. Log the redacted parsed DSN (scheme, host, path, query keys — never userinfo) at debug level in the factory. Most failures are a typo'd scheme silently falling through to a default adapter, or a bucket name accidentally parsed as the host.
• Extension points worth copying: a scheme => callable registry so new adapters register from a service provider, and a single DsnParser value object that returns {scheme, credentials, host, path, options}. That object is the piece you can unit test and reuse; everything else in a Symfony bundle is glue you'd rewrite in Laravel anyway.