Getting Started

Minimal Setup

Installation:

composer require spatie/livewire-filepond

Publish the config (optional):

php artisan vendor:publish --provider="Spatie\LivewireFilepond\LivewireFilepondServiceProvider"

First Use Case:

In a Livewire component, add the upload field:
```
<x-filepond::upload wire:model="file" />
```

Define the property in your Livewire component:

public $file;

public function mount()
{
    $this->file = null;
}

Handle the upload in a rule or method:

public function rules()
{
    return [
        'file' => 'nullable|file|max:10240', // 10MB
    ];
}

Where to Look First:
- README for basic usage.
- Configuration for customizing Filepond behavior.
- Livewire Docs for wire:model integration.

Implementation Patterns

Common Workflows

Basic File Upload:

Use <x-filepond::upload wire:model="file" /> for single-file uploads.

Validate and process the file in Livewire rules/methods:

public function updatedFile()
{
    $this->validate(['file' => 'required|file|mimes:pdf,jpg,png']);
    if ($this->file) {
        $path = $this->file->store('uploads');
        // Process $path (e.g., save to DB)
    }
}

Multiple Files:

Use wire:model="files" (array) and loop through the results:
```
<x-filepond::upload wire:model="files" multiple />
```

Handle in Livewire:

public $files = [];

public function updatedFiles()
{
    $this->validate([
        'files.*' => 'file|max:10240',
    ]);
    if (!empty($this->files)) {
        foreach ($this->files as $file) {
            $path = $file->store('uploads');
            // Process each file
        }
    }
}

Custom Filepond Options:
- Pass options via options prop:
```
<x-filepond::upload
    wire:model="file"
    :options="['allowFileType' => ['image/jpeg', 'image/png']]"
/>
```
- Or publish the config and override defaults in config/livewire-filepond.php.

Integration with Storage:

Use Laravel’s Storage facade to handle files:

use Illuminate\Support\Facades\Storage;

public function updatedFile()
{
    if ($this->file) {
        Storage::disk('s3')->putFile('uploads', $this->file);
    }
}

Progress Tracking:

Use Livewire’s wire:ignore to show a progress bar:

<div wire:ignore>
    <progress wire:model="uploadProgress"></progress>
</div>

Update progress in Livewire:

public $uploadProgress = 0;

public function updatedFile()
{
    $this->uploadProgress = 100; // Example
}

Reusable Components:

Create a custom Livewire component for file uploads:

php artisan make:livewire FileUpload

<!-- resources/views/livewire/file-upload.blade.php -->
<x-filepond::upload wire:model="file" />

// App\Http\Livewire\FileUpload
public $file;
public function mount($model = null) { ... }

Gotchas and Tips

Pitfalls

File Validation Timing:
- updatedFile fires before validation, so validate in rules() or updatedFile:
```
public function rules()
{
    return ['file' => 'nullable|file|max:10240'];
}
```
- Avoid silent failures by validating in updatedFile if needed.
Filepond JS Conflicts:
- If Filepond doesn’t render, ensure:
  - No duplicate script inclusions (check vendor.js).
  - No CSS conflicts (Filepond requires filepond.css).
- Clear browser cache or use ?v=2 to bust cache.
Large File Handling:
- For files >10MB, use chunked uploads:
```
<x-filepond::upload wire:model="file" chunkUploads />
```
- Configure chunk size in config/livewire-filepond.php:
```
'chunk_size' => '5MB',
```
Livewire State Persistence:
- Files are not persisted across requests by default. Use $this->persist() or session storage if needed:
```
protected $persistFiles = true; // Add to Livewire component
```

Server-Side Processing:

Filepond sends files to /livewire/update, not a custom endpoint. For custom logic, use a form submission:

<form wire:submit.prevent="customUpload">
    <x-filepond::upload wire:model="file" />
    <button type="submit">Upload</button>
</form>

public function customUpload()
{
    $this->validate(['file' => 'required']);
    // Custom logic here
}

Debugging Tips

Check Livewire Logs:
- Enable Livewire logging in config/livewire.php:
```
'log' => env('APP_DEBUG'),
```
- Look for errors in storage/logs/livewire.php.
Filepond Console Errors:
- Open browser dev tools (F12) and check the Console tab for Filepond errors (e.g., missing plugins).
Network Requests:
- Inspect the Network tab to verify files are being sent to /livewire/update.
Common Errors:
- "Filepond is not defined": Missing filepond.js or filepond.css.
- CORS Issues: Ensure your Livewire endpoint (/livewire/update) is accessible.
- CSRF Token Mismatch: Add @csrf to your Blade template if using standalone forms.

Extension Points

Custom Plugins:

Extend Filepond with plugins (e.g., FilePondPluginImagePreview):

<x-filepond::upload
    wire:model="file"
    :options="[
        'plugins' => [
            'FilePondPluginImagePreview',
            'FilePondPluginFileValidateType',
        ],
    ]"
/>

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

Dynamic Configuration:

Pass dynamic options from Livewire:

<x-filepond::upload
    wire:model="file"
    :options="['maxFiles' => $this->maxFiles]"
/>

Event Listeners:

Listen to Filepond events (e.g., init, addfile) via JavaScript:

<script>
    document.addEventListener('livewire:init', () => {
        Livewire.on('filepond-init', () => {
            console.log('Filepond initialized!');
        });
    });
</script>

Emit events from Livewire:
```
$this->dispatch('filepond-init');
```

Custom Storage Engines:

Override file handling by extending the component:

use Spatie\LivewireFilepond\LivewireFilepond;

class CustomFilepond extends LivewireFilepond
{
    public function storeFile($file)
    {
        return Storage::disk('s3')->put('custom-path', file_get_contents($file));
    }
}

Livewire::component('filepond.upload', CustomFilepond::class);

Localization:

Customize Filepond labels/errors via config/livewire-filepond.php:

'labels' => [
    'fileTypeNotAllowed' => 'This file type is not allowed.',
],

Livewire Filepond Laravel Package