Flysystem Path Prefixing Laravel Package

Getting Started

Install via Composer:

composer require league/flysystem-path-prefixing

This package provides a lightweight PrefixHandler (implementing PathPrefixingAdapterInterface) that wraps any Flysystem adapter to prepend a fixed or dynamic path prefix to all file operations. Your first use case will likely be isolating data per tenant or environment — e.g., prefixing all writes under tenants/123/ instead of touching the root of your storage bucket. Begin by wrapping your base adapter (LocalAdapter, S3Adapter, etc.) with PrefixHandler, then inject it into League\Flysystem\Filesystem. No service provider or config file needed — just instantiate and use.

Implementation Patterns

• Tenant-scoped storage: In a multi-tenant app, resolve the tenant ID from request context and build a prefix at runtime:

  $tenantPrefix = "tenants/{$tenant->id}/";
  $adapter = new PrefixHandler(new LocalAdapter(storage_path('app')), $tenantPrefix);
  $filesystem = new Filesystem($adapter);
  

• Release-versioned deployments: Prefix all uploads with a version tag (e.g., 2024.06.15/) for atomic rollbacks without stale assets:

  $prefix = config('app.release_version') . '/';
  $adapter = new PrefixHandler($s3Adapter, $prefix);
  

• Test isolation: In PHPUnit tests, generate a random, per-test prefix to avoid shared state:

  $testPrefix = "test_" . bin2hex(random_bytes(4)) . "/";
  $fs = new Filesystem(new PrefixHandler($localAdapter, $testPrefix));
  // Ensure cleanup after test via `tearDown()`
  

• Laravel integration: Extend the default FilesystemManager driver in a service provider to inject dynamic prefixes without touching Laravel’s default disks:

  $baseFs = $this->app->make('filesystem')->disk('s3'); // existing disk
  $tenantAdapter = new PrefixHandler($baseFs->getAdapter(), "tenants/{$this->app->tenantId}/");
  $this->app->instance(FilesystemInterface::class, new Filesystem($tenantAdapter));
  

• Chaining谨慎: While you can nest PrefixHandler instances, prefer a single computed prefix string for clarity (e.g., tenants/123/v2/).

Gotchas and Tips

• Trailing slash non-negotiable: A prefix like "tenant" will produce "tenantavatar.png" — always use "tenant/". Double-check via $prefixer->getPathPrefix() during debugging.
• No path normalization: Avoid absolute prefixes (/prod/) or .. — behavior depends on the underlying adapter. Stick to relative, normalized segments.
• Visibility ≠ prefix scope: Prefixing only affects paths, not visibility (e.g., Visibility::PUBLIC still applies — just to the prefixed path).
• Flysystem v3+ redundancy: This sub-split duplicates functionality now native in league/flysystem. If using league/flysystem ≥3.0, prefer the core PathPrefixingAdapter (not this package) to avoid class conflicts and ensure support.
• Debugging tip: Log or dump the actual path before critical operations (e.g., dump($filesystem->path('file.txt'))) to catch subtle prefix errors early.