Symfony Filesystem Bridge Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   Add the bundle to config/bundles.php:

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

2. First Use Case: Inject the bridge service into a controller/service to leverage Symfony's Filesystem component with FileBundle's abstractions:

   use BenGorFile\SymfonyFilesystemBridgeBundle\Service\FilesystemBridge;
   
   class MyController extends AbstractController
   {
       public function __construct(private FilesystemBridge $filesystemBridge) {}
   
       public function uploadFile()
       {
           $filesystem = $this->filesystemBridge->getFilesystem();
           $filesystem->mkdir('/path/to/dir'); // Uses Symfony's Filesystem
       }
   }
   

3. Key Entry Point: The FilesystemBridge service bridges FileBundle's FileManager with Symfony's Filesystem component. Check services.yaml for autowiring configurations.

Implementation Patterns

Core Workflows

1. File Operations: Use the bridge to abstract filesystem operations (e.g., mkdir, copy, remove) while maintaining FileBundle's file management logic:

   $filesystem = $this->filesystemBridge->getFilesystem();
   $filesystem->dumpFile('/path/to/file.txt', 'Content');
   

2. Integration with FileBundle: Leverage FileBundle's FileManager for metadata/validation, then delegate filesystem tasks to Symfony's Filesystem:

   $fileManager = $this->filesystemBridge->getFileManager();
   $file = $fileManager->find('/path/to/file'); // FileBundle logic
   $filesystem = $this->filesystemBridge->getFilesystem();
   $filesystem->chmod($file->getPath(), 0755); // Symfony Filesystem
   

3. Dependency Injection: Prefer constructor injection for the FilesystemBridge service to ensure testability:

   class FileService {
       public function __construct(private FilesystemBridge $bridge) {}
   }
   

4. Configuration-Driven Paths: Use Symfony's parameter bag (%kernel.project_dir%) or FileBundle's config to resolve paths dynamically:

   # config/packages/bengor_file.yaml
   bengor_file:
       filesystem:
           root_dir: '%kernel.project_dir%/uploads'
   

Advanced Patterns

• Event Listeners: Attach listeners to FileBundle's events (e.g., FileUploadEvent) and use the bridge to handle filesystem operations:

  use BenGorFile\SymfonyFilesystemBridgeBundle\Event\FileUploadEvent;
  
  class FileOptimizerListener {
      public function __construct(private FilesystemBridge $bridge) {}
  
      public function onUpload(FileUploadEvent $event) {
          $filesystem = $this->bridge->getFilesystem();
          $filesystem->chmod($event->getFile()->getPath(), 0644);
      }
  }
  

• Custom Filesystem Adapters: Extend the bridge to support cloud storage (e.g., S3) by implementing Symfony's Filesystem interface:

  class S3FilesystemBridge extends FilesystemBridge {
      public function getFilesystem() {
          return new S3Filesystem(); // Custom implementation
      }
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies:

   • The package targets Symfony 2.8+ and PHP 5.5+, but FileBundle (v1.x) may have outdated dependencies. Audit for compatibility if using newer Symfony/Laravel versions.
   • Workaround: Fork the bundle or use a wrapper to isolate dependencies.

2. Missing Documentation:

   • The README lacks examples for FileBundle integration. Refer to FileBundle's docs for file management logic.
   • Tip: Use php bin/console debug:container BenGorFile\SymfonyFilesystemBridgeBundle to inspect available services.

3. Stateful Filesystem: Symfony's Filesystem is not thread-safe. Avoid sharing instances across requests or long-running processes.

   • Fix: Re-inject the bridge per request or use a stateless adapter.

4. Path Resolution:

   • Paths are resolved relative to FileBundle's root directory. Hardcoded paths (e.g., /tmp) may fail.
   • Tip: Use FileBundle's PathResolver or Symfony's %kernel.project_dir% for consistency.

Debugging

1. Filesystem Operations: Enable Symfony's debug toolbar to log filesystem operations:

   # config/packages/dev/debug.yaml
   framework:
       profiler: { only_exceptions: false }
   

2. Permission Issues:

   • Symfony's Filesystem throws RuntimeException on failures. Wrap operations in try-catch:

   try {
       $filesystem->mkdir($path);
   } catch (\RuntimeException $e) {
       $this->addFlash('error', 'Failed to create directory: '.$e->getMessage());
   }
   

Extension Points

1. Custom Filesystem: Override the bridge's getFilesystem() method to inject a custom adapter (e.g., for testing):

   class TestFilesystemBridge extends FilesystemBridge {
       public function getFilesystem() {
           return new InMemoryFilesystem(); // Use a mock for tests
       }
   }
   

2. Event Subscribers: Extend FileBundle's events to trigger filesystem actions:

   use BenGorFile\FileBundle\Event\FileDeleteEvent;
   
   class CleanupSubscriber implements EventSubscriberInterface {
       public function onDelete(FileDeleteEvent $event) {
           $this->bridge->getFilesystem()->remove($event->getFile()->getPath());
       }
   }
   

3. Configuration Overrides: Customize the bridge's behavior via config/packages/bengor_file.yaml:

   bengor_file:
       filesystem_bridge:
           adapter: 'local' # or 's3', 'ftp', etc.
           options:
               base_path: '%kernel.project_dir%/custom_path'
   

Pro Tips

• Laravel Integration: Use the bridge in Laravel via Symfony's HttpKernel or a custom facade:

  // app/Providers/AppServiceProvider.php
  public function register() {
      $this->app->singleton('filesystem.bridge', function ($app) {
          return new FilesystemBridge(
              $app->make('file.manager'),
              new SymfonyFilesystem() // Laravel's Filesystem
          );
      });
  }
  

• Performance: Batch filesystem operations (e.g., mkdir + chmod) to reduce I/O calls:

  $filesystem = $this->bridge->getFilesystem();
  $filesystem->mkdir($path);
  $filesystem->chmod($path, 0755);
  

• Testing: Mock the FilesystemBridge in PHPUnit:

  $mockFilesystem = $this->createMock(\Symfony\Component\Filesystem\Filesystem::class);
  $mockFilesystem->method('mkdir')->willReturn(true);
  
  $bridge = $this->createPartialMock(FilesystemBridge::class, ['getFilesystem']);
  $bridge->method('getFilesystem')->willReturn($mockFilesystem);