Livewire Filepond Chunks Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require zentnova-libs/livewire-filepond-chunks
   npm install filepond @filepond/core @filepond/plugin-file-validate-type @filepond/plugin-image-preview @filepond/plugin-image-crop @filepond/plugin-image-resize @filepond/plugin-image-exif @filepond/plugin-file-encode
   npm run dev
   

2. Publish Config & Assets

   php artisan vendor:publish --provider="Zentnova\LivewireFilepondChunks\FilepondChunksServiceProvider" --tag="filepond-chunks-config"
   php artisan vendor:publish --provider="Zentnova\LivewireFilepondChunks\FilepondChunksServiceProvider" --tag="filepond-chunks-assets"
   

3. Basic Livewire Component

   use Zentnova\LivewireFilepondChunks\FilepondChunks;
   
   public function mount()
   {
       $this->filepond = new FilepondChunks(
           config('filepond-chunks.storage'),
           config('filepond-chunks.allowed_mime_types')
       );
   }
   
   public function render()
   {
       return view('livewire.your-component', [
           'filepond' => $this->filepond
       ]);
   }
   

4. Blade View

   <div wire:ignore>
       {!! $filepond->render() !!}
   </div>
   

First Use Case: Simple File Upload

Configure config/filepond-chunks.php:

'storage' => 's3', // or 'local'
'allowed_mime_types' => ['image/jpeg', 'image/png'],
's3_bucket' => 'your-bucket',
's3_key' => 'your-key',
's3_secret' => 'your-secret',
's3_region' => 'us-east-1',

Implementation Patterns

Workflow: Chunked Uploads with Validation

1. Component Initialization

   public function mount()
   {
       $this->filepond = new FilepondChunks(
           's3',
           ['image/jpeg', 'image/png'],
           ['max-file-size' => '10MB']
       );
   }
   

2. Handling Upload Events

   protected $listeners = [
       'filepond-chunks::uploaded' => 'handleUploaded',
       'filepond-chunks::error' => 'handleError'
   ];
   
   public function handleUploaded($event)
   {
       $this->dispatch('file-uploaded', $event->file);
   }
   
   public function handleError($event)
   {
       $this->addError('upload', $event->message);
   }
   

3. Custom Validation

   public function validateFile($file)
   {
       $validator = Validator::make($file->toArray(), [
           'file' => [
               'required',
               'mimes:' . implode(',', $this->filepond->allowedMimeTypes),
               'max:10240' // 10MB
           ]
       ]);
   
       if ($validator->fails()) {
           throw new \Exception($validator->errors()->first());
       }
   }
   

Integration with Laravel Storage

• Local Storage: Files saved to storage/app/public/uploads.
• S3 Storage: Configure AWS credentials in .env:

  AWS_ACCESS_KEY_ID=your-key
  AWS_SECRET_ACCESS_KEY=your-secret
  AWS_DEFAULT_REGION=us-east-1
  AWS_BUCKET=your-bucket
  

Extending Functionality

• Custom File Processing

  public function processFile($file)
  {
      $path = $file->getClientOriginalPath();
      // Custom logic (e.g., image optimization)
      return $path;
  }
  

• Dynamic Allowed MIME Types

  public function mount()
  {
      $this->filepond = new FilepondChunks(
          's3',
          $this->getAllowedMimeTypes() // Fetch from DB or API
      );
  }
  

Gotchas and Tips

Common Pitfalls

1. CORS Issues

   • Ensure your S3 bucket has CORS configured for POST requests:

     <CORSConfiguration>
         <CORSRule>
             <AllowedOrigin>*</AllowedOrigin>
             <AllowedMethod>POST</AllowedMethod>
         </CORSRule>
     </CORSConfiguration>
     

2. Chunk Size Limits

   • Default chunk size is 5MB. Adjust in config:

     'chunk_size' => '2MB',
     

3. Livewire Wire:Ignore

   • Always wrap FilePond in wire:ignore to prevent Livewire from interfering with its event system.

4. Filepond JS Initialization

   • Ensure filepond.js is loaded after Livewire’s Alpine.js to avoid conflicts.

Debugging Tips

• Check Network Tab: Verify chunk uploads are reaching the server.
• Log Events: Use filepond-chunks::* events to debug:

  protected $listeners = [
      'filepond-chunks::*' => 'logEvent'
  ];
  
  public function logEvent($event)
  {
      \Log::info('FilePond Event', $event->toArray());
  }
  

Configuration Quirks

• Local Storage Permissions: Ensure storage/app/public is writable:

  chmod -R 775 storage/app/public
  

• S3 ACLs: Set bucket policy to allow uploads:

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Principal": "*",
              "Action": ["s3:PutObject"],
              "Resource": "arn:aws:s3:::your-bucket/uploads/*"
          }
      ]
  }
  

Extension Points

1. Custom Storage Adapter Override Zentnova\LivewireFilepondChunks\Storage\StorageInterface for custom backends (e.g., FTP, Google Cloud).

2. Pre/Post Upload Hooks Extend FilepondChunks class to add logic before/after upload:

   class CustomFilepondChunks extends FilepondChunks
   {
       public function beforeUpload($file)
       {
           // Custom logic
       }
   
       public function afterUpload($file)
       {
           // Custom logic
       }
   }
   

3. Dynamic Filepond Options Pass dynamic options via Livewire properties:

   public $maxFileSize = '10MB';
   
   public function getFilepondOptions()
   {
       return [
           'maxFileSize' => $this->maxFileSize,
           // Other dynamic options
       ];
   }