Flysystem Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require oneup/flysystem-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Oneup\FlysystemBundle\OneupFlysystemBundle::class => ['all' => true],
   ];
   

2. Configure a Filesystem Edit config/packages/oneup_flysystem.yaml:

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

3. First Use Case: Upload a File Inject the Filesystem service and use it:

   use League\Flysystem\FilesystemInterface;
   
   public function uploadFile(FilesystemInterface $filesystem, UploadedFile $file)
   {
       $filesystem->writeStream('path/to/file.txt', $file->openFile());
   }
   

Implementation Patterns

Core Workflows

1. Adapter Configuration

   • Define adapters in oneup_flysystem.yaml (supports all Flysystem adapters).
   • Example for AWS S3:

     adapters:
         s3_adapter:
             aws_s3:
                 bucket: 'my-bucket'
                 region: 'us-east-1'
                 options:
                     credentials:
                         key: '%env(AWS_KEY)%'
                         secret: '%env(AWS_SECRET)%'
     

2. Filesystem Usage

   • Write/Read Files:

     $filesystem->write('file.txt', 'Hello, Flysystem!');
     $contents = $filesystem->read('file.txt');
     

   • Streaming Large Files:

     $filesystem->writeStream('large_file.zip', fopen('local/path.zip', 'r'));
     

3. Symfony Integration

   • Twig Templates: Pass the FilesystemInterface to templates:

     <img src="{{ asset(filesystem.url('image.jpg')) }}">
     

   • Doctrine ORM: Use Oneup\FlysystemBundle\Doctrine\Types\FileType for file metadata storage.

4. Dynamic Filesystems

   • Tag services and fetch by alias:

     $filesystem = $container->get('oneup_flysystem.my_filesystem');
     

Advanced Patterns

1. Custom Adapters Extend League\Flysystem\AdapterInterface and register via config:

   adapters:
       custom_adapter:
           custom:
               class: App\Adapter\CustomAdapter
               config: { ... }
   

2. Event Listeners Listen to filesystem events (e.g., oneup_flysystem.pre_write):

   use Oneup\FlysystemBundle\Event\FilesystemEvent;
   
   public function onPreWrite(FilesystemEvent $event) {
       $event->setPath(strtolower($event->getPath()));
   }
   

3. Caching Enable caching for adapters (e.g., cache: true in local adapter config).

Gotchas and Tips

Common Pitfalls

1. Adapter-Specific Errors

   • AWS S3: Ensure AsyncAwsS3 or AwsS3 is installed (composer require async-aws/s3 or aws/aws-sdk-php).
   • SFTP: Verify phpseclib/phpseclib is installed and credentials are correct.
   • Local Filesystem: Ensure the directory path is writable (chmod -R 777 var/files).

2. Configuration Overrides

   • Avoid hardcoding paths. Use %kernel.project_dir% or environment variables (%env(FILES_DIR)%).

3. Flysystem V2/V3 Migration

   • The bundle supports both versions. Ensure your adapters match the Flysystem version (e.g., league/flysystem-aws-s3-v3 for V3).

Debugging Tips

1. Log Adapter Errors Enable debug mode and check Symfony logs for adapter-specific errors (e.g., connection timeouts).

2. Validate Config Use the oneup_flysystem:validate command to check configuration:

   php bin/console oneup_flysystem:validate
   

3. Test Locally First Start with a local adapter before switching to cloud services (e.g., S3/Azure).

Extension Points

1. Custom Metadata Use FilesystemInterface::getMetadata() and extend with adapter-specific methods.

2. Symfony Messenger Dispatch filesystem events as messages for async processing:

   $this->messageBus->dispatch(new FilesystemProcessedEvent($path));
   

3. Dependency Injection Bind custom adapters as services:

   services:
       app.custom_adapter:
           class: App\Adapter\CustomAdapter
           arguments:
               - '%env(CUSTOM_CONFIG)%'