File Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer (note: package is archived, verify compatibility with your Symfony/Laravel version):

   composer require antonioturdo/file-bundle
   

   Register the bundle in config/bundles.php (Symfony) or manually load it in Laravel via a service provider.

2. Configuration Locate the default config at config/packages/antonioturdo_file.yaml (Symfony) or adapt the config/antonioturdo_file.php structure in Laravel. Key settings:

   'upload_dir' => storage_path('app/uploads'),
   'allowed_extensions' => ['jpg', 'png', 'pdf'],
   'max_file_size' => '2M',
   

3. First Use Case: File Upload Inject the FileManager service into a controller/service:

   use AntonioTurdo\FileBundle\Service\FileManager;
   
   public function uploadFile(Request $request, FileManager $fileManager) {
       $file = $request->file('document');
       $path = $fileManager->upload($file, 'documents');
       return response()->json(['path' => $path]);
   }
   

Implementation Patterns

Core Workflows

1. File Uploads

   • Basic Upload: Use fileManager->upload($file, $directory) for direct storage.
   • Validation: Extend with custom rules via fileManager->setRules($rules) (e.g., MIME types, dimensions).
   • Naming: Override filenames with fileManager->upload($file, $directory, $customName).

2. File Management

   • Deletion: Use fileManager->delete($path) to remove files.
   • Listing: Chain fileManager->listFiles($directory) for directory scans (returned as array of paths).

3. Integration with Laravel

   • Service Provider: Bind the bundle’s services in AppServiceProvider:

     $this->app->bind('fileManager', function ($app) {
         return new \AntonioTurdo\FileBundle\Service\FileManager(
             $app['config']['antonioturdo_file.upload_dir'],
             $app['config']['antonioturdo_file.allowed_extensions']
         );
     });
     

   • Form Requests: Validate uploads in FormRequest classes:

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

4. Storage Adaptors

   • Local Storage: Default behavior (uses storage_path()).
   • Custom Storage: Extend FileManager to support S3, FTP, etc., by overriding the save() method.

Gotchas and Tips

Pitfalls

1. Archived Package

   • No active maintenance; test thoroughly in a staging environment.
   • Fork the repo if critical fixes are needed (e.g., PHP 8+ compatibility).

2. Configuration Overrides

   • Laravel’s config/antonioturdo_file.php may not auto-generate. Manually define:

     return [
         'upload_dir' => storage_path('app/uploads'),
         'allowed_extensions' => explode(',', env('ALLOWED_FILE_TYPES', 'jpg,png,pdf')),
     ];
     

3. File Validation Gaps

   • The bundle lacks built-in MIME-type verification. Use Laravel’s mimes: rule or add a custom validator:

     $fileManager->setRules([
         'mime_types' => ['image/jpeg', 'application/pdf'],
     ]);
     

4. Directory Permissions

   • Ensure storage_path('app/uploads') is writable:

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

Debugging Tips

• Log Upload Paths: Add debug logs for uploaded files:

  \Log::debug('File uploaded to:', [$path]);
  

• Check File Existence: Verify paths post-upload:

  if (!file_exists($path)) {
      throw new \RuntimeException("File not saved at {$path}");
  }
  

Extension Points

1. Custom File Naming Override the generateFilename() method in a subclass of FileManager:

   protected function generateFilename($file, $directory, $customName = null) {
       return parent::generateFilename($file, $directory, $customName ?? uniqid());
   }
   

2. Post-Upload Actions Hook into the afterUpload event by extending the service:

   $fileManager->upload($file, 'docs')->then(function ($path) {
       // Trigger additional logic (e.g., thumbnail generation)
   });
   

3. Laravel Events Dispatch custom events post-upload:

   event(new FileUploaded($path, $request->user()));