File Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Since the package is archived, verify compatibility with your Laravel/Symfony version (if hybrid use is intended). Install via Composer:

   composer require bordeux/file-bundle
   

   Note: If using Laravel, wrap Symfony components in a bridge (e.g., symfony/http-foundation) or use a Laravel-compatible alternative like spatie/laravel-medialibrary.

2. First Use Case: File Upload Register the bundle in config/bundles.php (Symfony) or manually bootstrap in Laravel’s AppServiceProvider:

   // Laravel: Manually register (if no Symfony kernel)
   $this->app->register(\Bordeux\FileBundle\FileBundle::class);
   

   Define a basic upload route:

   use Bordeux\FileBundle\Controller\FileController;
   
   Route::post('/upload', [FileController::class, 'upload']);
   

3. Configuration Locate config/packages/bordeux_file.yaml (Symfony) or adapt to Laravel’s config/file.php:

   // Laravel: Example config
   'upload_dir' => storage_path('app/uploads'),
   'allowed_types' => ['jpg', 'png', 'pdf'],
   'max_size' => 5 * 1024 * 1024, // 5MB
   

Implementation Patterns

Core Workflows

1. Handling Uploads Use the FileUploader service to process files:

   $uploader = $this->container->get('bordeux_file.uploader');
   $filePath = $uploader->upload($request->file('document'), [
       'dir' => 'invoices',
       'rename' => true,
   ]);
   

2. File Management List, delete, or retrieve files via FileManager:

   $manager = $this->container->get('bordeux_file.manager');
   $files = $manager->listFiles('uploads');
   $manager->deleteFile($filePath);
   

3. Integration with Forms Symfony Twig integration (if using Symfony):

   {{ form_start(form) }}
       {{ form_widget(form.file) }}
       <button type="submit">Upload</button>
   {{ form_end(form) }}
   

   Laravel Alternative: Use Laravel Collective’s Form::file() with custom validation.

4. Validation Rules Extend Symfony’s validator or use Laravel’s built-in rules:

   // Laravel: Form Request
   public function rules() {
       return [
           'file' => 'required|file|mimes:jpg,png,pdf|max:5048',
       ];
   }
   

5. Storage Adapters Override the default storage (e.g., S3) by binding a custom FileStorage service:

   $this->app->bind('bordeux_file.storage', function () {
       return new \Bordeux\FileBundle\Storage\S3Adapter();
   });
   

Gotchas and Tips

Pitfalls

1. Archived Package Risks

   • No active maintenance; test thoroughly for edge cases (e.g., race conditions in file naming).
   • Consider forking or migrating to alternatives like spatie/laravel-medialibrary or intervention/image.

2. Symfony-Laravel Mismatches

   • Dependency Conflicts: Symfony’s HttpFoundation may clash with Laravel’s Illuminate\Http. Resolve via:

     composer require symfony/http-foundation:^5.4 --with-all-dependencies
     

   • Service Container: Laravel’s DI container differs from Symfony’s. Use SymfonyBridge or manual binding.

3. File Naming Collisions The bundle’s default rename option uses uniqid(). For production, implement a custom strategy (e.g., UUID + timestamp):

   $uploader->upload($file, ['rename' => function ($name) {
       return Str::uuid() . '-' . time() . '.' . $file->getClientOriginalExtension();
   }]);
   

4. Permission Issues Ensure upload_dir is writable:

   chmod -R 775 storage/app/uploads
   

   For shared hosting, use public_path('uploads') instead.

5. Validation Bypass Always validate files before processing:

   if (!$request->hasFile('file') || !$request->file('file')->isValid()) {
       throw new \InvalidArgumentException('Invalid file upload.');
   }
   

Debugging Tips

1. Log Uploads Enable debug mode in config/packages/bordeux_file.yaml:

   debug: true
   

   Laravel: Use Laravel’s logging:

   \Log::debug('File uploaded', ['path' => $filePath]);
   

2. Check Storage Paths Verify paths with:

   dd($uploader->getStoragePath());
   

3. Test with Small Files Start with 1KB files to rule out size/permission issues.

Extension Points

1. Custom Storage Implement Bordeux\FileBundle\Storage\StorageInterface for cloud storage:

   class GoogleDriveAdapter implements StorageInterface {
       public function save(File $file, string $path) { /* ... */ }
   }
   

2. Event Listeners Dispatch events for post-upload actions (e.g., thumbnail generation):

   $dispatcher->addListener('bordeux_file.uploaded', function ($event) {
       // Generate thumbnail
   });
   

3. Twig Extensions (Symfony) Create a custom Twig extension for file URLs:

   $twig->addExtension(new class extends \Twig\Extension\AbstractExtension {
       public function getFunctions() {
           return [
               new \Twig\TwigFunction('file_url', [$this, 'getFileUrl']),
           ];
       }
       public function getFileUrl(string $path) { /* ... */ }
   });