Laravel Filepond Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sopamo/laravel-filepond
   

   Publish the config file:

   php artisan vendor:publish --provider="Sopamo\Filepond\FilepondServiceProvider" --tag="filepond-config"
   

2. Configure Storage Edit config/filepond.php to define:

   • disk (default: public)
   • path (e.g., uploads/filepond)
   • allowed_mime_types (e.g., ['image/*', 'application/pdf'])
   • max_file_size (e.g., 10MB)
   • Laravel 13 Compatibility: Ensure your config/app.php includes Laravel 13's updated service provider and alias configurations if migrating.

3. First Upload Endpoint Add the route in routes/web.php:

   use Sopamo\Filepond\FilepondController;
   
   Route::post('/filepond-upload', [FilepondController::class, 'upload']);
   

4. Frontend Integration Include FilePond CSS/JS in your Blade view:

   <link href="https://unpkg.com/filepond@^4/dist/filepond.css" rel="stylesheet">
   <script src="https://unpkg.com/filepond@^4/dist/filepond.js"></script>
   

   Initialize FilePond with the upload endpoint:

   FilePond.registerPlugin(
     FilePondPluginImagePreview,
     FilePondPluginImageExifOrientation,
     FilePondPluginFileValidateType
   );
   
   FilePond.setOptions({
     server: {
       process: '/filepond-upload',
       revert: '/filepond-revert',
       load: '/filepond-load',
     },
   });
   

Implementation Patterns

Workflow: Handling File Uploads

1. Basic Upload Use the default FilepondController for simple drag-and-drop uploads. The package handles:

   • File validation (mime type, size).
   • Storage disk configuration.
   • Response formatting for FilePond’s frontend.
   • Laravel 13 Note: Ensure your app/Providers/AppServiceProvider.php boot method is compatible with Laravel 13’s updated container binding syntax.

2. Custom Validation Extend the FilepondController to add business logic:

   // app/Http/Controllers/CustomFilepondController.php
   use Sopamo\Filepond\FilepondController;
   
   class CustomFilepondController extends FilepondController
   {
       public function upload(Request $request)
       {
           $this->validate($request, [
               'file' => ['required', 'mimes:jpeg,png,pdf', 'max:10240'],
               'user_id' => 'required|exists:users,id',
           ]);
   
           return parent::upload($request);
       }
   }
   

3. Chunked Uploads (Large Files) Configure FilePond for chunked uploads in config/filepond.php:

   'chunk_size' => '5MB',
   'chunk_upload_url' => '/filepond-chunk-upload',
   

   Implement the chunk handler in your controller:

   public function chunkUpload(Request $request)
   {
       // Logic to handle chunks (e.g., using `league/flysystem`).
   }
   

4. File Processing Post-Upload Use Laravel’s stored event to process files:

   // app/Providers/AppServiceProvider.php
   use Sopamo\Filepond\Events\FileUploaded;
   
   public function boot()
   {
       FileUploaded::listen(function ($event) {
           // Resize images, generate thumbnails, etc.
           // Access file path: $event->filePath
       });
   }
   

Integration Tips

• Laravel Mix/Vite: Bundle FilePond plugins with your assets:

  // resources/js/app.js
  import FilePond from 'filepond';
  import 'filepond/dist/filepond.min.css';
  import FilePondPluginImagePreview from 'filepond-plugin-image-preview';
  

• Form Requests: Use Laravel’s FormRequest for reusable validation:

  // app/Http/Requests/FileUploadRequest.php
  public function rules()
   {
       return [
           'file' => ['required', 'mimes:jpeg,png', 'max:5120'],
       ];
   }
  

• Storage Adapters: Leverage league/flysystem for cloud storage (S3, etc.):

  // config/filepond.php
  'disk' => 's3',
  

• Laravel 13 Migration: If upgrading from an older Laravel version, ensure your config/filesystems.php is updated to match Laravel 13’s default configurations.

Gotchas and Tips

Pitfalls

1. CORS Issues

   • If using FilePond with a frontend on a different domain, ensure your Laravel app’s CORS middleware allows the frontend’s origin:

     // app/Http/Middleware/Cors.php
     $allowedOrigins = ['http://your-frontend.com'];
     

2. File Overwrites

   • By default, FilePond uses UUIDs for filenames. To customize:

     // config/filepond.php
     'filename_generator' => function ($file, $folder, $format, $options) {
         return 'custom_' . time() . '.' . $file->getClientOriginalExtension();
     },
     

3. Missing Revert/Load Endpoints

   • FilePond expects /filepond-revert and /filepond-load routes. Add them in routes/web.php:

     Route::post('/filepond-revert', [FilepondController::class, 'revert']);
     Route::get('/filepond-load', [FilepondController::class, 'load']);
     

4. Large File Timeouts

   • Increase PHP’s max_execution_time and memory_limit if uploading large files:

     // config/filepond.php
     'chunk_upload_timeout' => 300, // 5 minutes
     

5. Laravel 13 Compatibility

   • Ensure your composer.json and config/app.php are updated to reflect Laravel 13’s requirements. Pay attention to any changes in service provider bootstrapping or middleware handling.

Debugging Tips

• Log Upload Errors: Add logging in the controller:

  public function upload(Request $request)
  {
      try {
          return parent::upload($request);
      } catch (\Exception $e) {
          \Log::error('FilePond upload failed: ' . $e->getMessage());
          return response()->json(['error' => 'Upload failed'], 500);
      }
  }
  

• Validate FilePond JS Console: Check for errors like 413 Payload Too Large (adjust client_max_body_size in Nginx/Apache).
• Test with Postman: Manually test the /filepond-upload endpoint to isolate backend issues.
• Laravel 13 Artisan Commands: If using custom Artisan commands, ensure they are updated to use Laravel 13’s command structure.

Extension Points

1. Custom Storage Logic Override the storeFile method in your controller:

   protected function storeFile($request, $file)
   {
       $path = $this->getFilePath($file);
       Storage::disk($this->config['disk'])->put($path, file_get_contents($file));
       return $path;
   }
   

2. Pre-Signed URLs (S3) Generate pre-signed URLs for direct uploads to S3:

   use Aws\S3\S3Client;
   
   public function upload(Request $request)
   {
       $s3 = new S3Client([...]);
       $url = $s3->getObjectUrl('your-bucket', 'uploads/' . $request->file('file')->getClientOriginalName());
       return response()->json(['url' => $url]);
   }
   

3. Webhook Triggers Dispatch events after upload:

   event(new \App\Events\FileUploaded($filePath, $request->user()));
   

4. Laravel 13 Event System Ensure your event listeners are registered correctly in Laravel 13’s updated event system:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Sopamo\Filepond\Events\FileUploaded::class => [
           \App\Listeners\ProcessUploadedFile::class,
       ],
   ];