Laravel Filepond Laravel Package

Getting Started

Minimal Steps

1. Installation

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

2. Frontend Setup Include FilePond JS/CSS in your view 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 Create a form with a file input and submit it to a controller:

   <form action="{{ route('upload') }}" method="post" enctype="multipart/form-data">
       @csrf
       <input type="file" name="filepond">
       <button type="submit">Upload</button>
   </form>
   

4. Controller Processing Validate and move the file:

   use RahulHaque\Filepond\Facades\Filepond;
   
   public function upload(Request $request) {
       $request->validate([
           'filepond' => ['required', Rule::filepond(['image', 'max:2000'])]
       ]);
   
       $fileInfo = Filepond::field($request->filepond)
           ->moveTo('uploads/' . time());
   
       return redirect()->back()->with('success', 'Uploaded!');
   }
   

Where to Look First

• Configuration: config/filepond.php (temporary storage, validation rules, middleware).
• Facade Methods: Filepond::field() as the entry point for all operations.
• Validation: Rule::filepond() for custom validation rules.
• Artisan Commands: php artisan filepond:clear for cleanup.

Implementation Patterns

Core Workflow

1. Frontend Integration

   • Use FilePond’s JS library with the package’s server endpoint.
   • Configure chunked uploads for large files:

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

2. Backend Processing

   • Single File:

     $fileInfo = Filepond::field($request->file)
         ->moveTo('path/to/file');
     

   • Multiple Files:

     $fileInfos = Filepond::field($request->files)
         ->moveTo('path/to/files');
     

3. Validation

   • Global rules in config/filepond.php (applies to all uploads).
   • Field-specific rules in controllers or FormRequest:

     $request->validate([
         'filepond' => ['required', Rule::filepond(['mimes:jpg,png', 'max:5120'])]
     ]);
     

4. Storage Handling

   • Default Disk: Uses Laravel’s public disk for permanent storage.
   • Custom Disk: Override per operation:

     Filepond::field($request->file)
         ->moveTo('path/to/file', 's3');
     

5. Chunked Uploads

   • Enable in FilePond JS (chunkUploads: true).
   • Package handles resume/retries automatically for S3 and local storage.

Integration Tips

• Laravel Nova: Use the moveTo() method in Nova tool actions for file attachments.
• Inertia/Vue: Pass file metadata (e.g., fileInfo.url) to the frontend for preview.
• API Responses: Return fileInfo for direct client-side use:

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

• Soft Deletes: Track files in the filepond table for auditing:

  $file = Filepond::field($request->file)->getFile()->getModel();
  

Common Use Cases

Gotchas and Tips

Pitfalls

1. Temporary Storage Location

   • If temp_disk is set to a cloud provider (e.g., S3), controller validation fails because files aren’t locally accessible.
   • Fix: Use local disk for temporary storage and validate before moving.

2. File Ownership Checks

   • checkOwnership: true in field() prevents unauthorized access to temporary files.
   • Gotcha: If a user uploads a file unauthenticated, they can’t retrieve it later.
   • Fix: Use sessions or tokens for temporary file access.

3. Chunked Uploads Without S3

   • Local chunked uploads require manual cleanup of partial files.
   • Fix: Use php artisan filepond:clear to purge expired chunks.

4. Debugging Missing Files

   • Files disappear after moveTo()? Check:
     • Disk permissions (storage:link for local storage).
     • soft_delete config (default true).
     • Artisan command logs (php artisan filepond:clear).

5. Validation Rule Conflicts

   • Rule::filepond() overrides global rules but fails silently if the file isn’t found (e.g., cloud temp storage).
   • Fix: Validate before moving or use getFile() to check existence.

Debugging Tips

• Log File Info:

  $file = Filepond::field($request->file)->getFile();
  \Log::info($file->getClientOriginalName());
  

• Check Temporary Files:

  ls storage/temp_filepond/
  

• Verify Disk Config:

  \Log::info(config('filepond.temp_disk')); // Should be 'local' for validation
  

• Test Chunked Uploads:
  • Simulate a slow connection to test resume:

    FilePond.setOptions({ chunkSize: 1024 * 1024 }); // 1MB chunks
    

Extension Points

1. Custom Validation Rules Extend the Rule::filepond() logic in app/Providers/AppServiceProvider:

   use RahulHaque\Filepond\Rules\Filepond;
   
   Filepond::extend('custom', function ($attribute, $value, $parameters) {
       return $value->getClientSize() < 10 * 1024 * 1024; // 10MB max
   });
   

2. Override File Naming Modify the moveTo() behavior by binding to the filepond.moving event:

   Filepond::field($request->file)->moveTo('uploads/')
       ->then(function ($fileInfo) {
           // Rename or process further
       });
   

3. Add Metadata Use the filepond-plugin-file-metadata plugin and store metadata in the filepond table:

   $file = Filepond::field($request->file)->getFile()->getModel();
   $file->metadata = json_encode(['exif' => $exifData]);
   $file->save();
   

4. Webhook Triggers Dispatch events after file processing:

   event(new FileUploaded($fileInfo));
   

   Listen in EventServiceProvider:

   protected $listen = [
       FileUploaded::class => [FileUploadHandler::class],
   ];
   

Configuration Quirks

• server.url in Config: Must match your route (default: /filepond/process). Update if using a custom route:

  config(['filepond.server.url' => '/custom/process']);
  

• temp_folder Permissions: Ensure the directory is writable:

  chmod -R 755 storage/temp_filepond/
  

• S3 Multipart Uploads: Requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in .env:

  AWS_DEFAULT_REGION=us-east-1
  

• Soft Delete Tradeoff: Disabling soft_delete skips the filepond table but loses audit logs.

Performance Tips

• Large Files:
  • Use S3 for temporary storage to avoid local disk I/O.
  • Set chunkSize in FilePond JS (e.g., 5MB for slow connections).
• Batch Processing: Queue moveTo() operations for async handling:

  Filepond::field($request->files)
      ->moveTo('uploads/')
      ->then