Flysystem Read Only Laravel Package

Getting Started

Install the package via Composer:

composer require league/flysystem-read-only

Immediately wrap an existing Flysystem adapter (e.g., Local, S3, FTP) with ReadOnlyStorage to enforce read-only behavior.

use League\Flysystem\ReadOnly\ReadOnlyStorage;
use League\Flysystem\LocalStorage\LocalStorage;

$storage = new LocalStorage('/var/www/public/assets');
$readOnlyStorage = new ReadOnlyStorage($storage);

// Now $readOnlyStorage permits reads but blocks writes
$content = $readOnlyStorage->read('logo.png'); // ✅ Works
$readOnlyStorage->write('new.txt', 'data'); // ❌ Throws WriteOperationDenied

First use case: Securely serve static assets (images, PDFs, etc.) from an S3 bucket or local directory without risk of accidental modification by the application.

Implementation Patterns

• Adapter Wrapping: Use ReadOnlyStorage as a thin decorator around any Flysystem adapter—no adapter-specific config changes needed. Ideal for wrapping S3Adapter, LocalAdapter, or FtpAdapter.
• Environment-Gated Wrapping: Wrap conditionally based on APP_ENV or feature flags (e.g., production read-only mode):

  $storage = match(config('app.read_only')) {
      true => new ReadOnlyStorage(new S3Adapter(...)),
      default => new S3Adapter(...),
  };
  

• Test Isolation: In integration tests, wrap adapters to simulate constrained production environments (e.g., readonly DB-backed assets or audit logs).
• Laravel Integration: Override Storage::build() or create a custom FilesystemFactory that injects ReadOnlyStorage for specific disks (e.g., assets-read-only disk).

Gotchas and Tips

• Subsplit Limitation: This is a sub-split—all issues/PRs must go to the main Flysystem repo. Expect minimal direct maintenance or rapid iteration here.
• Exception Handling: Write/delete attempts throw WriteOperationDenied (extends FilesystemException). Always catch and log these explicitly—don’t assume silent failure.
• Partial Enforcement: Operations like setVisibility() or copy() may still attempt writes depending on the underlying adapter (e.g., copy() on S3 might trigger a write). Verify behavior for your specific adapter.
• No Config File: Avoid relying on config files—this package is purely code-driven. Pair with Laravel’s config() or dotenv for environment control.
• Version Locking: Pin to stable minor versions (e.g., ^3.0)—low star count and minimal commits suggest low churn, but verify compatibility with your Flysystem version (v2 or v3).