Knp Gaufrette Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle & Adapters

   composer require knplabs/knp-gaufrette-bundle gaufrette gaufrette/adapter-local
   

   (Replace gaufrette/adapter-local with your preferred adapter, e.g., gaufrette/adapter-aws for S3.)

2. Configure the Bundle Add to config/packages/knp_gaufrette.yaml:

   knp_gaufrette:
       adapters:
           my_adapter:
               local:
                   directory: '%kernel.project_dir%/var/files'
       filesystems:
           my_filesystem:
               adapter: my_adapter
   

3. First Use Case: Upload a File

   use Knp\Bundle\GaufretteBundle\FilesystemMap;
   use Gaufrette\Filesystem;
   
   public function uploadFile(FilesystemMap $filesystemMap, UploadedFile $file) {
       $fs = $filesystemMap->get('my_filesystem');
       $fs->write('path/to/file.txt', $file->getContent());
   }
   

Where to Look First

• Bundle Docs (Symfony 5/6)
• Gaufrette Docs (Core functionality)
• config/packages/knp_gaufrette.yaml (Default config structure)

Implementation Patterns

Core Workflows

1. Filesystem Abstraction Use FilesystemMap to switch between adapters (e.g., local dev → AWS prod) without code changes:

   $fs = $filesystemMap->get('my_filesystem');
   $fs->writeStream('large_file.zip', fopen('local/path.zip', 'r'));
   

2. Streaming Large Files Avoid memory issues with writeStream()/readStream():

   $fs->writeStream('video.mp4', fopen('video_source.mp4', 'r'));
   

3. Metadata Handling Use getMetadata()/setMetadata() for custom attributes:

   $metadata = $fs->getMetadata('file.txt');
   $fs->setMetadata('file.txt', ['user_id' => 123]);
   

Integration Tips

• Symfony Forms: Bind Gaufrette\File\File to form fields for direct uploads.
• Flysystem Bridge: Use league/flysystem-gaufrette to integrate with Flysystem-based packages.
• Event Listeners: Hook into FilesystemEvents (e.g., preWrite, postDelete) for logging/auditing.

Example: Multi-Adapter Setup

# config/packages/knp_gaufrette.yaml
knp_gaufrette:
    adapters:
        local:
            local:
                directory: '%kernel.project_dir%/var/files'
        s3:
            aws:
                bucket: 'my-bucket'
                prefix: 'uploads/'
    filesystems:
        dev:
            adapter: local
        prod:
            adapter: s3

Gotchas and Tips

Pitfalls

1. Adapter-Specific Quirks

   • Local Adapter: Ensure directory is writable (chmod 777 if needed).
   • AWS Adapter: Configure credentials via knp_gaufrette.yaml or environment variables:

     aws:
         key: '%env(AWS_KEY)%'
         secret: '%env(AWS_SECRET)%'
         region: 'eu-west-1'
     

   • FTP Adapter: Use ftp://user:pass@host:port/path in directory config.

2. Caching Issues Clear Symfony cache after changing knp_gaufrette.yaml:

   php bin/console cache:clear
   

3. File Permissions Gaufrette doesn’t handle permissions—configure via OS (e.g., chmod) or adapter (e.g., AWS ACLs).

Debugging

• Check Adapter Status:

  $adapter = $fs->getAdapter();
  var_dump($adapter->getMetadata()); // Debug connection issues
  

• Enable Gaufrette Logging:

  # config/packages/monolog.yaml
  handlers:
      gaufrette:
          type: stream
          path: '%kernel.logs_dir%/gaufrette.log'
          level: debug
  

Extension Points

1. Custom Adapters Extend Gaufrette\Adapter\AbstractAdapter and register via config:

   adapters:
       custom:
           custom_adapter: ~ # Reference your service
   

2. Filesystem Events Subscribe to Knp\Bundle\GaufretteBundle\Event\FilesystemEvent:

   // src/EventListener/FileUploadListener.php
   public function onPreWrite(PreWriteEvent $event) {
       $event->setContent(gzcompress($event->getContent()));
   }
   

3. Symfony Messenger Dispatch Gaufrette\File\File objects as messages for async processing:

   $this->messageBus->dispatch(new HandleUpload($fs->get('file.txt')));
   

Pro Tips

• Use FilesystemInterface for Testing: Mock Gaufrette\Filesystem in tests with Gaufrette\FilesystemMap.
• Leverage Directory Objects:

  $dir = $fs->getDirectory('subfolder');
  $dir->create('new_file.txt');
  

• Symfony Uploader Integration: Pair with oneup/uploader-bundle for drag-and-drop uploads.