alsous/laravel-filepond

Laravel 12 FilePond integration — Blade component for single/multiple file uploads with old() support

dev-main 2026-05-10 12:29 UTC

Requires

• php: ^8.2
• illuminate/filesystem: ^12.0
• illuminate/routing: ^12.0
• illuminate/support: ^12.0
• illuminate/view: ^12.0

MIT

• laravel
• file-upload
• filepond
• blade-component

README

Laravel 12 package for FilePond — Blade component that handles single/multiple uploads, image previews, old() restoration, and in-form deletion.

Installation

composer require alsous/laravel-filepond

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

How it works

1. User selects files → FilePond uploads each file immediately to a temp endpoint → receives a UUID back.
2. A hidden <input> keeps the UUID(s) in the form.
3. User submits the form → your controller receives the UUID(s) → you call Filepond::getFile($id) → the file is ready to store permanently.
4. If validation fails, old() restores the UUID(s) and FilePond re-displays the files — no re-upload needed.
5. Clicking X in FilePond removes the file and sends a DELETE to the temp endpoint.

Basic usage

Single file

<form method="POST" action="{{ route('profile.update') }}">
    @csrf

    <x-filepond name="avatar" />

    <button type="submit">Save</button>
</form>

use Alsous\Filepond\Traits\InteractsWithFilepond;

class ProfileController extends Controller
{
    use InteractsWithFilepond;

    public function update(Request $request)
    {
        $request->validate([
            'avatar' => 'required|string',
        ]);

        $file = $this->filepondFile('avatar');   // FilepondFile|null
        $path = $file?->store('avatars');        // stored path

        auth()->user()->update(['avatar' => $path]);
    }
}

Multiple files

<x-filepond name="photos" multiple max-files="10" />

$files = $this->filepondFiles('photos');   // FilepondFile[]

foreach ($files as $file) {
    $path = $file->store('photos');
    Photo::create(['path' => $path, 'user_id' => auth()->id()]);
}

Component props

Prop	Type	Default	Description
name	string	—	Form field name
multiple	bool	false	Allow multiple files
max-file-size	string	—	e.g. "5MB", "500KB"
accepted-file-types	array	[]	e.g. ['image/*'], ['application/pdf']
max-files	int	—	Max files in multiple mode
image-preview	bool	true	Show thumbnail previews for images
include-assets	bool	true	Auto-inject FilePond CSS/JS from CDN
value	string|array	—	Pre-populate (UUID or array of UUIDs)
label	string	—	Custom idle label (HTML allowed)
disabled	bool	false	Disable the pond
required	bool	false	Mark as required

old() — automatic after validation failure

No extra code needed. The component reads old('fieldname') automatically.

public function store(Request $request)
{
    $request->validate([
        'document' => 'required|string',
        'title'    => 'required|string|max:255',
    ]);

    // If validation fails here, the user is redirected back.
    // The component will restore the uploaded file automatically.
}

<form method="POST" action="/documents">
    @csrf

    <input name="title" value="{{ old('title') }}">
    @error('title') <span>{{ $message }}</span> @enderror

    <x-filepond name="document" accepted-file-types='["application/pdf"]' />
    @error('document') <span>{{ $message }}</span> @enderror

    <button type="submit">Upload</button>
</form>

Pre-populate from a model (edit form)

Pass the stored UUID (or array) via :value.

{{-- Single --}}
<x-filepond name="avatar" :value="$user->avatar_temp_id" />

{{-- Multiple --}}
<x-filepond name="photos" multiple :value="$post->photo_temp_ids" />

Facade — use without the trait

use Alsous\Filepond\Facades\Filepond;

// Single
$file = Filepond::getFile($request->input('avatar'));
$path = $file?->store('avatars');

// Multiple
$files = Filepond::input($request->input('photos'));
foreach ($files as $file) {
    $file->store('photos');
}

FilepondFile API

Method	Returns	Description
store($path, $disk)	string	Store using Laravel convention
storeAs($path, $name, $disk)	string	Store with custom filename
toUploadedFile()	UploadedFile	Convert to standard Laravel upload
getFilePath()	string	Absolute filesystem path
$file->originalName	string	Original filename
$file->mimeType	string	MIME type
$file->size	int	Size in bytes

Loading your own assets

Set :include-assets="false" and load FilePond in your layout <head>:

<link rel="stylesheet" href="https://unpkg.com/filepond@^4/dist/filepond.min.css">
<link rel="stylesheet" href="https://unpkg.com/filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.css">

<script src="https://unpkg.com/filepond@^4/dist/filepond.min.js"></script>
<script src="https://unpkg.com/filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.js"></script>
<script src="https://unpkg.com/filepond-plugin-file-validate-type/dist/filepond-plugin-file-validate-type.min.js"></script>
<script src="https://unpkg.com/filepond-plugin-file-validate-size/dist/filepond-plugin-file-validate-size.min.js"></script>

<x-filepond name="avatar" :include-assets="false" />

Configuration (config/filepond.php)

'temp_disk'       => 'local',          // Storage disk for temp files
'temp_folder'     => 'filepond/temp',  // Folder inside the disk
'route_prefix'    => 'filepond',       // URL prefix: /filepond/process
'middleware'      => ['web'],           // Middleware on FilePond routes
'max_upload_size' => 102400,           // KB — 100 MB default

Add auth to middleware to require authentication on uploads:

'middleware' => ['web', 'auth'],

Artisan commands

# Publish config
php artisan vendor:publish --tag=filepond-config

# Publish views (to customise the component template)
php artisan vendor:publish --tag=filepond-views

Requirements

• PHP 8.2+
• Laravel 12