Flysystem Gridfs Laravel Package

Getting Started

Start by installing the package and ensuring required extensions:

composer require league/flysystem-gridfs

Verify mongodb extension (v1.3+ or v2+) is enabled via php -m | grep mongodb. Then instantiate the adapter and Flysystem client:

use League\Flysystem\Filesystem;
use League\Flysystem\GridFS\GridFsAdapter;

$client = new MongoDB\Client('mongodb://localhost:27017');
$adapter = new GridFsAdapter($client, 'myapp', 'fs'); // DB name + collection prefix
$filesystem = new Filesystem($adapter);

The first use case is typically replacing Storage::put()-style operations with GridFS-backed storage—ideal for large or frequently duplicated assets in clustered environments.

Implementation Patterns

• Uniform storage layer: Use FilesystemManager::extend() in Laravel to register GridFS as a disk ('gridfs'), enabling seamless swapping between disks via Storage::disk('gridfs').
• Streaming large binaries: Prefer writeStream()/readStream() for files >16MB to avoid memory exhaustion:

  $stream = fopen($request->file('upload')->getRealPath(), 'r');
  $filesystem->writeStream('uploads/' . $uuid, $stream);
  

• Metadata enrichment: Attach custom metadata via $filesystem->write($path, $contents, ['metadata' => ['version' => 3]]). GridFS stores this in fs.files, queryable via standard MongoDB tools.
• Hybrid workflows: Combine with LocalAdapter (e.g., serve small files directly, offload large ones to GridFS) using a dispatcher or conditional logic based on file size.

Gotchas and Tips

• Index pitfalls: GridFS relies on compound indexes (files_id, n) for chunk lookups. Run db.fs.chunks.createIndex({ files_id: 1, n: 1 }) manually—missing indexes cause catastrophic slowdowns with large datasets.
• Naming collisions: The prefix (e.g., fs) prepended to files/chunks collections. Avoid reuse across apps/databases unless intentional (e.g., prod_fs, staging_fs).
• Driver version mismatches: The adapter uses mongodb/mongodb (v1.x), which aligns with ext-mongodb v2.x. Avoid legacy mongo (pecl-mongo) apps—migration requires full overhaul of MongoDB connections.
• No fallback for corrupted chunks: GridFS doesn’t auto-repair malformed chunk chains. Implement health checks (e.g., verify chunkCount() ≈ ceil(fileSize / chunkSize)) and alert on discrepancies.
• Laravel caching trap: Don’t cache Filesystem instances across requests—MongoDB\Client isn’t serializable. Re-instantiate per request or use Laravel’s service container with lazy resolution.