Filestorage Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require daemon/filestorage-bundle
   

   Add to config/bundles.php:

   return [
       Daemon\FilestorageBundle\FilestorageBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console daemon:filestorage:install
   

   Edit config/packages/daemon_filestorage.yaml to define storage paths (e.g., storage_path: '%kernel.project_dir%/storage/files').

3. First Upload Use the FilestorageManager service in a controller:

   use Daemon\FilestorageBundle\Manager\FilestorageManager;
   
   public function upload(Request $request, FilestorageManager $manager)
   {
       $file = $request->file('file');
       $path = $manager->store($file, 'user_uploads'); // 'user_uploads' is a configured storage key
       return response()->json(['path' => $path]);
   }
   

Key Files to Review

• config/packages/daemon_filestorage.yaml: Storage configurations (keys, paths, permissions).
• src/Manager/FilestorageManager.php: Core logic for file operations.
• src/EventListener/FilestorageListener.php: Event hooks (e.g., post-upload).

Implementation Patterns

Workflows

1. File Uploads

   • Use FilestorageManager::store() for saving files to a specific storage key:

     $path = $manager->store($request->file('document'), 'documents');
     

   • Retrieve the full path or URL via FilestorageManager::getPath()/getUrl().

2. File Deletion

   • Delete files by path or storage key + filename:

     $manager->delete('documents', 'report.pdf');
     // or
     $manager->deleteByPath($fullPath);
     

3. Custom Storage Keys

   • Define dynamic storage paths in config:

     daemon_filestorage:
         storages:
             user_avatars: '%kernel.project_dir%/storage/avatars/%user_id%'
     

   • Pass a user_id context to resolve paths:

     $path = $manager->store($file, 'user_avatars', ['user_id' => 123]);
     

4. Events

   • Listen for filestorage.pre_store/filestorage.post_store:

     // config/services.yaml
     Daemon\FilestorageBundle\EventListener\FilestorageListener:
         tags:
             - { name: kernel.event_listener, event: filestorage.pre_store, method: onPreStore }
     

Integration Tips

• Symfony Uploader Integration Pair with VichUploaderBundle for entity-based file handling:

  use Daemon\FilestorageBundle\Annotation as Filestorage;
  
  class User {
      #[Filestorage\Uploadable('user_avatars', context: ['user_id' => 'id'])]
      private $avatar;
  }
  

• Validation Validate file types/sizes before upload:

  $file = $request->validate()->file('file')->assertMimes(['image/jpeg']);
  

• Symlinks for Web Access Create a symlink from public/uploads to your storage path for direct web access:

  ln -s %kernel.project_dir%/storage/files %kernel.project_dir%/public/uploads
  

Gotchas and Tips

Pitfalls

1. Permissions

   • Ensure the storage directory is writable by the web server:

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

   • Debug permission issues with FilestorageManager::checkPermissions().

2. Path Resolution

   • Context Variables: Forgetting to pass required context variables (e.g., user_id) will break path resolution. Fix: Validate context keys in config or use defaults:

     storages:
         user_files: '%kernel.project_dir%/storage/files/%user_id%/%default%'
     

3. Overwriting Files

   • By default, files with duplicate names overwrite existing files. Use FilestorageManager::storeUnique() to append hashes:

     $path = $manager->storeUnique($file, 'documents');
     

4. Event Order

   • pre_store events can modify the file (e.g., resize) but must not call store() recursively to avoid infinite loops.

5. Symlink Caveats

   • If using symlinks, ensure the target path is absolute and the symlink is created in a web-accessible directory.

Debugging

• Log Storage Events Enable debug mode in config/packages/daemon_filestorage.yaml:

  debug: true
  

  Logs will appear in var/log/dev.log.

• Check Paths Use FilestorageManager::getStoragePath() to verify resolved paths:

  $path = $manager->getStoragePath('documents', ['user_id' => 123]);
  

Extension Points

1. Custom Storage Handlers Implement Daemon\FilestorageBundle\Storage\StorageInterface for S3, FTP, etc.:

   class S3Storage implements StorageInterface {
       public function store(File $file, string $path): string { /* ... */ }
   }
   

   Register in config/services.yaml:

   Daemon\FilestorageBundle\Storage\S3Storage:
       arguments:
           - '@aws.s3.client'
       tags: { name: daemon_filestorage.storage, alias: 's3' }
   

2. File Processing Extend the FilestorageListener to add pre/post-processing:

   public function onPreStore(PreStoreEvent $event) {
       $file = $event->getFile();
       // Resize image, etc.
       $event->setFile($processedFile);
   }
   

3. Dynamic Config Override storage paths at runtime using FilestorageManager::setStoragePath():

   $manager->setStoragePath('temp_uploads', '/tmp/uploads');