Gaufrette Laravel Package

Getting Started

First Steps

1. Installation:

   composer require knplabs/gaufrette
   

   • Note: Added .gitattributes to optimize Composer installs by reducing unnecessary file downloads (v0.11.1+).

2. Basic Setup:

   use Gaufrette\Filesystem;
   use Gaufrette\Adapter\Local;
   
   $adapter = new Local('/path/to/storage');
   $filesystem = new Filesystem($adapter);
   

   • Where to look first: Gaufrette Documentation (especially the "Adapters" section).
   • First use case: Replace direct filesystem operations (e.g., file_put_contents, unlink) with Gaufrette’s methods like:

     $filesystem->write('file.txt', 'Hello, Gaufrette!');
     $filesystem->delete('file.txt');
     

Implementation Patterns

Core Workflows

1. Adapter Abstraction:

   • Use built-in adapters (Local, Flysystem, S3, Azure, etc.) or extend with custom ones.
   • Azure Adapter Fix: Stream-based operations (e.g., large file uploads/downloads) now work correctly in v0.11.1. Example:

     $adapter = new \Gaufrette\Adapter\Azure(
         $connectionString,
         $containerName,
         $blobName
     );
     $filesystem = new Filesystem($adapter);
     $filesystem->write('large-file.zip', fopen('php://input', 'r')); // Stream works reliably
     

2. Laravel Integration:

   • Filesystem Disks: Bind Gaufrette to Laravel’s Storage facade:

     use Illuminate\Support\Facades\Storage;
     use Gaufrette\Filesystem;
     
     Storage::extend('gaufrette', function ($app) {
         $adapter = new \Gaufrette\Adapter\Local(storage_path('app'));
         return new Filesystem($adapter);
     });
     

   • Now use Storage::disk('gaufrette')->put('file.txt', 'content');.

3. Common Operations:

   • Uploads: Stream files directly to avoid memory issues (critical for Azure/S3):

     $filesystem->write('large-file.zip', fopen('php://input', 'r'));
     

   • Metadata: Use getMetadata() and setMetadata() for custom file attributes.
   • Directories: Mimic mkdir/rmdir with:

     $filesystem->createDirectory('subfolder');
     $filesystem->deleteDirectory('subfolder');
     

4. Event Listeners:

   • Hook into file operations via Filesystem::addListener():

     $filesystem->addListener('update', function ($file, $event) {
         logger()->info("File {$file->getKey()} was updated!");
     });
     

Gotchas and Tips

Pitfalls

1. Adapter-Specific Quirks:

   • Local Adapter: Paths are relative to the adapter’s root. Use absolute paths or resolve them via realpath().
   • Azure Adapter: Stream operations (e.g., large files) now work correctly in v0.11.1, but ensure:
     • Connection strings are valid.
     • Blob containers exist and are accessible.
     • Test with small files first to validate permissions.
   • Cloud Adapters (S3/Azure): Secure credentials (use Laravel’s config or environment variables). Monitor API call quotas.

2. Memory Management:

   • Avoid loading entire files into memory with read() or get(). Use streams (fopen) or chunked reads:

     $filesystem->read('large-file.log', null, 0, 1024); // Read first 1KB
     

3. Race Conditions:

   • Gaufrette doesn’t support atomic operations. For critical files, implement locks (e.g., flock or Laravel’s Semaphore).

4. Metadata Conflicts:

   • Custom metadata keys must be strings. Non-string keys (e.g., arrays) serialize to JSON, which may cause issues.

Debugging Tips

• Enable Adapter Logging: Wrap adapters in a logging layer:

  $adapter = new \Gaufrette\Adapter\Local(storage_path('app'));
  $adapter = new \Gaufrette\Adapter\LoggingAdapter($adapter, new \Monolog\Logger('gaufrette'));
  

• Check File Existence: Use has() before operations to avoid Gaufrette\Exception\FileNotFound:

  if (!$filesystem->has('file.txt')) {
      throw new \RuntimeException('File missing!');
  }
  

• Azure-Specific Debugging: If streams fail post-v0.11.1, verify:
  • The Azure adapter is initialized with a valid connection string.
  • The blob container exists and is writable.

Extension Points

1. Custom Adapters:

   • Extend Gaufrette\Adapter\BaseAdapter for new storage backends. Example:

     class DatabaseAdapter extends BaseAdapter {
         public function write($file, $content) {
             // Save to DB...
         }
         // Implement other required methods (read, delete, etc.)
     }
     

2. Middleware:

   • Create decorators for pre/post-processing:

     class CompressingFilesystem extends Filesystem {
         public function write($file, $content) {
             $compressed = gzcompress($content);
             parent::write($file, $compressed);
         }
     }
     

3. Laravel Service Providers:

   • Bind multiple Gaufrette filesystems dynamically:

     $this->app->bind('gaufrette', function ($app) {
         return new Filesystem(new Local(storage_path('app')));
     });
     $this->app->bind('gaufrette-backups', function ($app) {
         return new Filesystem(new Local(storage_path('backups')));
     });