Laravel Filepond Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require rahulhaque/laravel-filepond
   php artisan vendor:publish --provider="RahulHaque\Filepond\FilepondServiceProvider"
   php artisan migrate
   

2. Frontend Setup Include FilePond JS/CSS and configure the server endpoint:

   FilePond.setOptions({
       server: {
           url: "{{ config('filepond.server.url') }}",
           headers: { 'X-CSRF-TOKEN': "{{ csrf_token() }}" }
       }
   });
   FilePond.create(document.querySelector('input[type="file"]'));
   

3. First Upload

   <form method="POST" action="{{ route('upload') }}">
       @csrf
       <input type="file" name="files[]" multiple>
       <button type="submit">Upload</button>
   </form>
   

4. Backend Processing

   use RahulHaque\Filepond\Facades\Filepond;
   
   public function upload(Request $request) {
       $files = Filepond::field($request->files)->moveTo('uploads/');
       // $files now contains array of moved file info
   }
   

Where to Look First

• Configuration: config/filepond.php (temporary storage, validation rules, disk settings)
• Validation: Rule::filepond() for custom validation
• API Endpoints: /filepond/process (handles uploads), /filepond/patch, /filepond/head, etc.

Implementation Patterns

Core Workflow

1. Temporary Storage

   • Files land in storage/temp/filepond (configurable) during upload.
   • Use Filepond::field()->getFile() to inspect metadata before moving.

2. Validation

   • Global: Configure validation_rules in config/filepond.php (e.g., ['max:10M', 'mimes:jpg,png']).
   • Per-Request: Use Rule::filepond() in FormRequests or controllers:

     $this->validate($request, [
         'files.*' => Rule::filepond(['max:5M', 'image'])
     ]);
     

3. Permanent Storage

   • Single File:

     $fileInfo = Filepond::field($request->file)->moveTo('avatars/user1.jpg');
     

   • Multiple Files:

     $fileInfos = Filepond::field($request->files)->moveTo('gallery/');
     // Files auto-named as `gallery-1.jpg`, `gallery-2.jpg`, etc.
     

4. Chunked Uploads

   • Enable in FilePond JS:

     FilePond.create(input, { chunkUploads: true });
     

   • Configure chunk_size in config/filepond.php (default: 5MB).

5. AWS S3 Integration

   • Set temp_disk to s3 in config (files upload directly to S3).
   • Use moveTo('s3:bucket-name/path') to specify S3 paths.

Integration Tips

• Laravel Media Library:

  $file = Filepond::field($request->file)->moveTo('media/');
  $model->addMedia($file['url'])->toMediaCollection('images');
  

• Inertia/Vue: Return file URLs from backend to populate frontend state:

  return response()->json($fileInfos);
  

• Dynamic Paths: Use closures for dynamic paths:

  $fileInfo = Filepond::field($request->file)
      ->moveTo(fn($file) => "users/{auth()->id()}/{$file['basename']}");
  

Common Use Cases

Gotchas and Tips

Pitfalls

1. Third-Party Storage Quirks

   • Issue: Files uploaded directly to S3/GCS bypass local validation.
   • Fix: Use Rule::filepond() only with local temp_disk. For cloud storage, validate client-side or use API constraints.

2. Permission Errors

   • Symptom: Uploads fail silently or filepond:clear doesn’t work.
   • Fix:

     chmod -R 775 storage/temp/filepond
     chown -R www-data:www-data storage/temp/filepond  # Adjust user as needed
     

3. CSRF Token Mismatch

   • Cause: FilePond’s X-CSRF-TOKEN header not set correctly.
   • Fix: Ensure csrf_token() matches your frontend framework (e.g., Inertia/Vue may need laravel.csrfToken).

4. Large File Timeouts

   • Issue: Chunked uploads time out during processing.
   • Fix: Increase PHP max_execution_time and memory_limit in php.ini.

5. Soft Delete Confusion

   • Gotcha: moveTo() respects soft_delete config (default: true).
   • Fix: Set soft_delete: false in config if you want immediate deletion.

Debugging

• Check Temporary Files:

  ls -la storage/temp/filepond
  

• Log Upload Events: Add to config/filepond.php:

  'log_uploads' => true, // Logs to storage/logs/filepond.log
  

• Validate Filepond Model:

  $file = Filepond::find($fileId);
  dd($file->file); // Inspect stored metadata
  

Extension Points

1. Custom Validation Rules Extend the Rule::filepond() validator:

   use RahulHaque\Filepond\Rules\Filepond;
   
   $validator = Validator::make($request->all(), [
       'file' => ['required', new Filepond(['custom_rule' => true])]
   ]);
   

2. Override Storage Logic Bind a custom filesystem to the Filepond facade:

   Filepond::setDisk('s3-custom');
   

3. Hook into Upload Events Publish the event listeners:

   php artisan vendor:publish --tag=filepond-events
   

   Then extend FilepondUploaded event in app/Listeners.

4. Custom Filepond Model Extend the Filepond model to add fields:

   php artisan make:model FilepondExtension --extend=RahulHaque\Filepond\Models\Filepond
   

   Add fields like user_id or metadata.

Pro Tips

• Auto-Generate Filenames: Use moveTo() with a closure to generate unique names:

  $fileInfo = Filepond::field($request->file)
      ->moveTo(fn($file) => "uploads/{Str::uuid()}.{$file['extension']}");
  

• Preserve Original Filenames: Pass false to moveTo()’s second parameter:

  $fileInfo = Filepond::field($request->file)->moveTo('uploads/', false);
  

• Cleanup Schedule: Add to app/Console/Kernel.php:

  $schedule->command('filepond:clear')->daily();
  

• Metadata Handling: Use filepond-plugin-file-metadata with the Filepond facade:

  $metadata = Filepond::field($request->file)->getMetadata();