Files Uploader Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dev-farm/files-uploader-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       DevFarm\FilesUploaderBundle\FilesUploaderBundle::class => ['all' => true],
   ];
   

2. Publish Config

   php artisan vendor:publish --provider="DevFarm\FilesUploaderBundle\FilesUploaderBundle" --tag="config"
   

   Edit config/files_uploader.php to define:

   • storage (local, s3, etc.)
   • allowed_mime_types
   • max_file_size

3. First Use Case: Basic Upload

   use DevFarm\FilesUploaderBundle\Services\FileUploader;
   
   // In a controller or service
   $uploader = app(FileUploader::class);
   $result = $uploader->upload(
       request()->file('file_input'),
       'user_uploads' // target directory
   );
   

   Returns an array with:

   [
       'path' => 'user_uploads/filename.ext',
       'url' => '/storage/user_uploads/filename.ext',
       'original_name' => 'original_filename.ext',
       'mime_type' => 'image/jpeg',
   ]
   

Implementation Patterns

Core Workflows

1. Multi-File Uploads

   $files = request()->file('files');
   $results = $uploader->uploadMultiple($files, 'batch_uploads');
   

   Returns an array of upload results.

2. Custom Storage Paths

   // Dynamic paths (e.g., user-specific)
   $path = "users/{$user->id}/documents";
   $result = $uploader->upload($file, $path);
   

3. Validation Integration

   use DevFarm\FilesUploaderBundle\Rules\FileType;
   
   $request->validate([
       'file' => ['required', 'file', new FileType(['jpg', 'png'])],
   ]);
   

Integration Tips

• Symfony Forms Use DevFarm\FilesUploaderBundle\Form\Type\FileType for form fields:

  $builder->add('document', FileType::class, [
      'label' => 'Upload File',
      'allowed_types' => ['pdf', 'docx'],
  ]);
  

• Event Listeners Subscribe to FilesUploaderBundleEvents::FILE_UPLOADED:

  public function handleFileUploaded(FileUploadedEvent $event) {
      // Log, notify, or process the uploaded file
  }
  

• Queueing Large Uploads Dispatch a job for async processing:

  dispatch(new ProcessUploadJob($file, $path));
  

Gotchas and Tips

Pitfalls

1. Storage Permissions

   • Ensure storage/app/ is writable (chmod -R 775 storage/).
   • For S3, verify AWS credentials in .env and config.

2. Mime Type Validation

   • Default allowed_mime_types may block legitimate files. Extend via config:

     'allowed_mime_types' => [
         'images' => ['jpg', 'png', 'gif', 'webp'],
         'documents' => ['pdf', 'docx', 'xlsx'],
     ],
     

3. File Size Limits

   • PHP’s upload_max_filesize and post_max_size must exceed max_file_size in config.
   • Test with large files early to avoid runtime errors.

4. Overwriting Files

   • By default, duplicate filenames append a hash (e.g., file_123abc.ext).
   • Disable via config:

     'overwrite_strategy' => 'replace', // or 'skip'
     

Debugging

• Log Uploads Enable debug mode in config:

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

  Logs appear in storage/logs/laravel.log.

• Check Disk Space Use php artisan storage:link if symlinks fail, and verify disk space:

  df -h
  

Extension Points

1. Custom Storage Adapters Implement DevFarm\FilesUploaderBundle\Contracts\StorageAdapter for new backends (e.g., FTP):

   class FtpAdapter implements StorageAdapter {
       public function save($file, $path) { ... }
       public function getUrl($path) { ... }
   }
   

   Register in config:

   'adapters' => [
       'ftp' => \App\Services\FtpAdapter::class,
   ],
   

2. Pre/Post-Processing Use events to modify files:

   // Example: Resize images
   $event->getFile()->resize(800, 600);
   

3. Metadata Extraction Access EXIF/IPTC data via:

   $metadata = $result['metadata']; // e.g., ['width' => 1920, 'height' => 1080]