File Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coka/file-bundle
   

   Add the bundle to your config/bundles.php (Symfony) or manually register it in AppServiceProvider (Laravel via Symfony bridge):

   // config/app.php (if using Laravel/Symfony bridge)
   'extra.bundles' => [
       CedrickOka\OkaFileBundle\OkaFileBundle::class => ['all' => true],
   ];
   

2. Publish Config:

   php artisan vendor:publish --provider="CedrickOka\OkaFileBundle\OkaFileBundle" --tag="config"
   

   This generates config/oka_file.php. Key settings:

   return [
       'storage' => [
           'path' => storage_path('app/oka_files'),
           'url'  => env('APP_URL').'/storage/oka_files',
       ],
       'allowed_mime_types' => ['image/jpeg', 'image/png', 'application/pdf'],
   ];
   

3. First Use Case: Upload a file via a controller:

   use CedrickOka\OkaFileBundle\Service\FileManager;
   
   public function upload(Request $request, FileManager $fileManager) {
       $file = $request->file('file');
       $path = $fileManager->upload($file, 'user_uploads');
       return response()->json(['path' => $path]);
   }
   

Implementation Patterns

Core Workflows

1. File Uploads:

   • Use FileManager service for handling uploads with validation:

     $fileManager->upload($file, 'folder_name', [
         'max_size' => '10M',
         'mime_types' => ['image/*'],
     ]);
     

   • Supports chunked uploads (for large files) via ChunkedFileManager.

2. File Retrieval:

   • Stream files directly to users:

     return $fileManager->stream('folder/file.pdf');
     

   • Generate signed URLs for temporary access:

     $url = $fileManager->getSignedUrl('folder/file.pdf', now()->addHours(1));
     

3. File Management:

   • List files in a directory:

     $files = $fileManager->listFiles('folder_name');
     

   • Delete files:

     $fileManager->delete('folder/file.pdf');
     

4. Integration with Laravel:

   • Form Requests: Extend Illuminate\Foundation\Http\FormRequest to validate files:

     public function rules() {
         return [
             'file' => 'required|file|mimes:jpeg,png,pdf|max:10240',
         ];
     }
     

   • Storage Disk: Use the bundle’s disk via config('oka_file.storage.path') in filesystems.php:

     'disks' => [
         'oka_files' => [
             'driver' => 'local',
             'root' => config('oka_file.storage.path'),
         ],
     ],
     

5. Event Handling:

   • Listen for file upload events:

     // In EventServiceProvider
     protected $listen = [
         'CedrickOka\OkaFileBundle\Event\FileUploaded' => [
             'App\Listeners\LogUploadedFile',
         ],
     ];
     

Gotchas and Tips

Pitfalls

1. Symfony Dependency:

   • The bundle is Symfony-first. In Laravel, you’ll need to:
     • Manually register the bundle in AppServiceProvider if not using Symfony bridge.
     • Handle kernel events differently (e.g., use Laravel’s Event facade instead of Symfony’s EventDispatcher).

2. Configuration Overrides:

   • The bundle does not auto-publish config in Laravel by default. Always run php artisan vendor:publish to avoid runtime errors.

3. Mime Type Validation:

   • The default allowed_mime_types in config is strict. Extend it in your config:

     'allowed_mime_types' => [
         'image/jpeg', 'image/png', 'image/gif',
         'application/pdf', 'application/msword',
     ],
     

4. Storage Permissions:

   • Ensure the storage_path('app/oka_files') directory is writable:

     mkdir -p storage/app/oka_files && chmod -R 775 storage/app/oka_files
     

5. Chunked Uploads:

   • Chunked uploads require client-side support (e.g., Tus or custom JS). The bundle provides the backend but lacks frontend examples.

Debugging Tips

1. Log File Operations:

   • Enable debug mode in config/oka_file.php:

     'debug' => env('APP_DEBUG', false),
     

   • Logs file operations to storage/logs/oka_file.log.

2. Validate File Paths:

   • Use FileManager::getAbsolutePath('folder/file') to debug paths. Always escape user input to prevent directory traversal:

     $safePath = $fileManager->sanitizePath($userInput);
     

3. Symfony Container Issues:

   • If services fail to resolve, ensure the bundle is loaded after Laravel’s core services:

     // In AppServiceProvider boot()
     $this->app->register(CedrickOka\OkaFileBundle\OkaFileBundle::class);
     

Extension Points

1. Custom Storage Drivers:

   • Extend CedrickOka\OkaFileBundle\Storage\StorageInterface to support S3, FTP, etc.:

     class S3Storage implements StorageInterface {
         public function save($file, $path) { ... }
         // Implement other methods
     }
     

   • Bind your driver in AppServiceProvider:

     $this->app->bind(
         StorageInterface::class,
         S3Storage::class
     );
     

2. File Filters:

   • Create a custom filter to process files post-upload:

     use CedrickOka\OkaFileBundle\Event\FileUploaded;
     
     public function handle(FileUploaded $event) {
         $filePath = $event->getPath();
         // Resize images, convert formats, etc.
     }
     

3. API Responses:

   • Override the default JSON response for file metadata:

     // In a controller
     $metadata = $fileManager->getMetadata('folder/file.pdf');
     return response()->json([
         'path' => $metadata['path'],
         'size' => $metadata['size'],
         'mime' => $metadata['mime'],
         'custom_field' => 'your_data',
     ]);