Gaufrette Filesystem Bridge Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require bengor-file/gaufrette-filesystem-bridge-bundle
   

   Ensure FileBundle and GaufretteFilesystemBridge are also installed (this bundle bridges them).

2. Enable in config/bundles.php

   return [
       // ...
       BenGorFile\GaufretteFilesystemBridgeBundle\BenGorFileGaufretteFilesystemBridgeBundle::class => ['all' => true],
   ];
   

3. Configure in config/packages/bengor_file_gaufrette_filesystem_bridge.yaml

   bengor_file_gaufrette_filesystem_bridge:
       filesystem: 'my_gaufrette_filesystem'  # Matches your Gaufrette config
       adapter: 'file'  # or 's3', 'rackspace', etc.
   

4. First Use Case: File Upload Inject the bridged filesystem into a service/controller:

   use BenGorFile\GaufretteFilesystemBridgeBundle\Filesystem\FilesystemBridge;
   
   class UploadController extends AbstractController
   {
       public function upload(FilesystemBridge $filesystemBridge)
       {
           $file = $this->get('request')->files->get('file');
           $filesystem = $filesystemBridge->getFilesystem('my_gaufrette_filesystem');
           $filesystem->write('path/to/file.txt', fopen($file->getPathname(), 'r'));
       }
   }
   

Implementation Patterns

Core Workflow: File Operations

1. Bridge Filesystem Access Use FilesystemBridge to abstract Gaufrette operations:

   $filesystem = $filesystemBridge->getFilesystem('my_gaufrette_filesystem');
   $filesystem->write('file.txt', $content);  // Write
   $content = $filesystem->read('file.txt');  // Read
   $filesystem->delete('file.txt');          // Delete
   

2. Leverage Gaufrette Adapters Configure Gaufrette adapters (e.g., local, s3, ftp) in config/packages/gaufrette.yaml:

   gaufrette:
       filesystems:
           my_gaufrette_filesystem:
               adapter: gaufrette\adapter\local
               options:
                   directory: '%kernel.project_dir%/var/files'
   

3. Integration with FileBundle Use File entities from FileBundle and map them to Gaufrette:

   $fileEntity = new File();
   $fileEntity->setPath('path/to/file.txt');
   $filesystemBridge->saveFile($fileEntity);  // Persists to Gaufrette
   

4. Streaming Large Files Use Gaufrette’s streaming capabilities for efficiency:

   $filesystem->write('large_file.zip', fopen($file->getPathname(), 'r'), true);
   

5. Symfony Events Hook into file.pre_upload/file.post_upload events to validate/process files before/after Gaufrette operations.

Advanced Patterns

1. Custom Metadata Handling Extend File entity to store Gaufrette-specific metadata (e.g., size, mime_type):

   $fileEntity->setMetadata([
       'gaufrette_size' => $filesystem->size('file.txt'),
       'gaufrette_mtime' => $filesystem->mtime('file.txt'),
   ]);
   

2. Dynamic Filesystem Routing Route filesystems dynamically based on request context:

   $filesystemName = $request->get('env') === 'prod' ? 's3_prod' : 'local_dev';
   $filesystem = $filesystemBridge->getFilesystem($filesystemName);
   

3. Flysystem Compatibility Use league/flysystem adapters via Gaufrette’s FlysystemAdapter for broader storage support.

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies

   • The bundle was last updated in 2017 and may not support newer Symfony/Laravel versions (though Laravel can use Symfony bundles via symfony/flex).
   • Workaround: Use symfony/flex to install Symfony components and manually bridge Gaufrette with Laravel’s Storage facade.

2. Configuration Overrides

   • Gaufrette configs in gaufrette.yaml must match the filesystem key in bengor_file_gaufrette_filesystem_bridge.yaml.
   • Fix: Validate keys with dump($filesystemBridge->getAvailableFilesystems()).

3. File Permissions

   • Gaufrette adapters (e.g., local) require proper filesystem permissions.
   • Tip: Use chmod or ACLs to ensure Laravel’s storage directory is writable:

     chmod -R 775 %kernel.project_dir%/var/files
     

4. Circular Dependencies

   • Avoid injecting FilesystemBridge into FileBundle services directly. Use Symfony’s container.get() or Laravel’s app() for lazy loading.

5. No Laravel-Specific Features

   • The bundle is Symfony-only. For Laravel, wrap it in a service provider:

     // app/Providers/GaufretteServiceProvider.php
     public function register()
     {
         $this->app->singleton('gaufrette.filesystem', function ($app) {
             return new FilesystemBridge($app['gaufrette.filesystem']);
         });
     }
     

Debugging Tips

1. Check Filesystem Availability

   dd($filesystemBridge->getAvailableFilesystems());  // Verify configured namespaces.
   

2. Log Gaufrette Errors Enable Gaufrette’s debug mode:

   gaufrette:
       debug: true
   

3. Validate File Writes Use filesystem->exists() and filesystem->size() to confirm writes:

   if (!$filesystem->exists('file.txt')) {
       throw new \RuntimeException('File not written to Gaufrette.');
   }
   

Extension Points

1. Custom Adapters Extend Gaufrette’s AdapterInterface and register via gaufrette.yaml:

   gaufrette:
       adapters:
           custom_adapter:
               class: App\Adapter\CustomAdapter
   

2. Event Listeners Subscribe to file.pre_upload to validate files before Gaufrette operations:

   $event->setAborted(true);  // Abort upload if invalid.
   

3. Laravel Integration Publish the bundle’s configs and override defaults:

   php artisan vendor:publish --provider="BenGorFile\GaufretteFilesystemBridgeBundle\BenGorFileGaufretteFilesystemBridgeBundle"