Filament Uppy Upload Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spykapps/filament-uppy-upload
   

   Publish config (if needed):

   php artisan vendor:publish --provider="SpykApps\FilamentUppyUpload\FilamentUppyUploadServiceProvider"
   

2. First Use Case: Add the field to a Filament resource/form:

   use SpykApps\FilamentUppyUpload\Fields\UppyUploadField;
   
   UppyUploadField::make('document')
       ->disk('s3') // or 'public', 'local', etc.
       ->directory('user_uploads/{user_id}') // Dynamic paths supported
       ->maxSize(100) // in MB
       ->maxFiles(5)
   

3. Where to Look First:

   • README.md for feature highlights.
   • config/filament-uppy-upload.php for default settings (e.g., chunk size, allowed MIME types).
   • vendor/spykapps/filament-uppy-upload/src/Fields/UppyUploadField.php for method signatures and options.

Implementation Patterns

Core Workflows

1. Basic File Uploads:

   UppyUploadField::make('profile_picture')
       ->disk('public')
       ->imageEditor() // Enable Uppy's image editor
       ->required()
   

2. Remote Source Integration:

   UppyUploadField::make('external_file')
       ->disk('s3')
       ->remoteSources(['google-drive', 'dropbox'])
       ->allowedFileExtensions(['pdf', 'docx'])
   

3. Dynamic Directories: Use closures for runtime paths:

   UppyUploadField::make('resume')
       ->disk('s3')
       ->directory(fn ($record) => "resumes/{$record->user_id}/{$record->job_id}")
   

4. Validation & Processing: Override handleUploadedFiles in your resource:

   protected function handleUploadedFiles(array $files): void
   {
       foreach ($files as $file) {
           // Process metadata, rename, or trigger events
           $file->update(['processed_at' => now()]);
       }
   }
   

5. Chunked Uploads with Custom Logic: Configure chunk size in config/filament-ppy-upload.php:

   'chunk_size' => 5, // MB
   

   Handle chunked uploads via UppyUploadField::make()->chunkedUploads(true).

Integration Tips

• Filament Panels/Resources: Use in both Form and Table contexts (for bulk uploads):

  // In a Table column:
  UppyUploadField::make('attachment')
      ->disk('s3')
      ->onlyUploadButton() // Hide file list
  

• Event Listeners: Listen for upload events (e.g., UppyUploaded):

  use SpykApps\FilamentUppyUpload\Events\UppyUploaded;
  
  event(new UppyUploaded($file, $record));
  

• Custom Uppy Plugins: Extend Uppy’s core via uppyOptions:

  UppyUploadField::make('video')
      ->uppyOptions([
          'plugins' => [
              new UppyWebcam({
                  target: 'webcam-container',
                  targetBackground: '#f0f0f0',
              }),
          ],
      ])
  

• Testing: Use mocks in tests:

  $field->fakeUpload('test.pdf', 'public', 'test.pdf');
  

Gotchas and Tips

Pitfalls

1. Chunked Uploads:

   • Ensure your web server (Nginx/Apache) supports chunked uploads with the correct client_max_body_size (e.g., 100M).
   • For S3, verify your bucket’s multipart_copy permissions.

2. File Overwrites:

   • By default, duplicate filenames overwrite. Use ->uniqueFilename() to append timestamps:

     ->uniqueFilename(fn ($file) => now()->format('YmdHis').'-'.$file->getClientOriginalName())
     

3. Remote Source Quotas:

   • Google Drive/OneDrive APIs have rate limits. Cache tokens or implement retries for 429 errors.

4. Large File Timeouts:

   • Increase PHP’s max_execution_time and memory_limit for processing large uploads.

5. Filament 5 Migration:

   • Some method names changed (e.g., disk() → storageDisk()). Check the upgrade guide.

Debugging

1. Uppy Console Logs: Enable Uppy’s debug mode in uppyOptions:

   ->uppyOptions(['debug' => true])
   

   Check browser console for errors (e.g., CORS, plugin failures).

2. Laravel Logs:

   • Enable UPLOAD_LOGGING in config to log file operations:

     'logging' => [
         'enabled' => true,
         'channel' => 'single',
     ],
     

3. Common Errors:

   • FileNotFoundException: Verify disk/directory permissions.
   • InvalidArgumentException: Check allowedFileExtensions or maxSize.
   • CORS Issues: Ensure your Uppy endpoint (/filament-uppy-upload) is whitelisted.

Extension Points

1. Custom Storage Handlers: Extend SpykApps\FilamentUppyUpload\Services\StorageHandler to support non-Laravel storage (e.g., FTP):

   class CustomStorageHandler extends StorageHandler {
       public function saveFile($file, $path) {
           // Custom logic
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(SpykApps\FilamentUppyUpload\Contracts\StorageHandler::class, CustomStorageHandler::class);
   

2. Post-Processing: Use afterUpload callback:

   ->afterUpload(function ($file, $record) {
       // Trigger a job or update related models
       ProcessVideoJob::dispatch($file->path);
   })
   

3. UI Customization: Override Uppy’s template via uppyOptions:

   ->uppyOptions([
       'metaFields' => [
           { id: 'custom_field', name: 'Custom Field', placeholder: 'Enter value' },
       ],
   ])
   

4. Bulk Operations: For tables, use ->bulkUpload() and handle UppyBulkUploaded events:

   UppyUploadField::make('documents')
       ->bulkUpload()
       ->directory('bulk_uploads/{date:Y-m-d}')