Livewire Filepond

https://github.com/spatie/livewire-filepond
Admin
A Livewire component that integrates the Filepond JavaScript library for easy file uploads in...
Tokens:21,604
Snippets:157
Trust Score:10
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install livewire-filepond via Composer

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Install the package via Composer.

```bash
composer require spatie/livewire-filepond
```

--------------------------------

### Manual usage example for revert

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Shows how to call revert manually from a method, as used in the FilePond revert flow.

```php
// Called by the FilePond revert flow in the blade component; manual usage:
public function cancelUpload(string $filename): void
{
    $this->revert('file', $filename);
}
```

--------------------------------

### Full customization of the x-filepond::upload component

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/upload-component.md

This example demonstrates how to configure the upload component with multiple file support, limits, custom messages, and image resizing. The accepted-file-types and image-resize-target-width attributes are forwarded to FilePond as camelCased options.

```bladehtml
<x-filepond::upload
    wire:model="photos"
    multiple
    max-files="5"
    maxfilesmsg="Ce fichier est en double"
    placeholder="Drop your files here"
    accepted-file-types="image/jpeg, image/png"
    image-resize-target-width="800"
    class="mt-4"
/>
```

--------------------------------

### Blade component and Livewire class for remove() example

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Shows the blade component and the Livewire component class used in the basic remove() example. The blade component triggers remove() via FilePond's server.remove request.

```bladehtml
<x-filepond::upload wire:model="photos" multiple />
```

```php
use Livewire\Component;
use Spatie\LivewireFilepond\WithFilePond;

class Gallery extends Component
{
    use WithFilePond;

    public array $photos = [];
}
```

--------------------------------

### Example layout using @filepondScripts

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/livewire-filepond-service-provider.md

Example layout usage showing the @filepondScripts directive placed in the <head> section of a Blade layout, alongside a @livewire('profile') component in the body.

```bladehtml
<!DOCTYPE html>
<html>
<head>
    ...
    @filepondScripts
</head>
<body>
    @livewire('profile')
</body>
</html>
```

--------------------------------

### GET /_filepond/scripts

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/endpoints.md

Documentation for the GET /_filepond/scripts endpoint that serves the FilePond JavaScript bundle.

```APIDOC
## GET /_filepond/scripts

### Description
Serves the compiled FilePond JavaScript bundle from the package's `resources/dist` directory. This route is used by the `@filepondScripts` directive to load the FilePond library in the browser.

### Method
GET

### Endpoint
/_filepond/scripts

### Parameters
#### Query Parameters
- **v** (string) - Optional - Cache buster appended by the `@filepondScripts` directive (e.g., `?v=1.8.0`).

### Response
#### Success Response (200)
- **body** (file) - The compiled JavaScript bundle `resources/dist/filepond.js`, served as a JavaScript module.

#### Response Example
(JavaScript file content)

### Notes
- Route name: `livewire-filepond.scripts`
- No authentication required.
- No request body.
- If the bundle is missing, file-not-found semantics apply.
```

--------------------------------

### GET /_filepond/styles

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/endpoints.md

Documentation for the GET /_filepond/styles endpoint that serves the FilePond CSS stylesheet.

```APIDOC
## GET /_filepond/styles

### Description
Serves the compiled FilePond CSS stylesheet from the package's `resources/dist` directory. This route is used by the `@filepondScripts` directive to load the FilePond styles in the browser.

### Method
GET

### Endpoint
/_filepond/styles

### Parameters
#### Query Parameters
- **v** (string) - Optional - Cache buster appended by the `@filepondScripts` directive (e.g., `?v=1.8.0`).

### Response
#### Success Response (200)
- **body** (file) - The CSS file `resources/dist/filepond.css`, served with content type `text/css`.

#### Response Example
(CSS file content)

### Notes
- Route name: `livewire-filepond.styles`
- No authentication required.
- No request body.
- If the bundle is missing, file-not-found semantics apply.
```

--------------------------------

### Register livewire-filepond.styles route

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/endpoints.md

Registers the GET /_filepond/styles route that serves the filepond.css bundle with an explicit text/css content type. No middleware or authentication is declared, and the route is public.

```php
Route::get('_filepond/styles', function () {
    return Utils::pretendResponseIsFile(__DIR__.'/../resources/dist/filepond.css', 'text/css');
})->name('livewire-filepond.styles');
```

--------------------------------

### Register FilePond script and style routes

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/livewire-filepond-service-provider.md

Registers two GET routes to serve the built FilePond JavaScript and CSS bundles from the package's resources/dist directory using Livewire's Utils::pretendResponseIsFile(). The routes are named livewire-filepond.scripts and livewire-filepond.styles, and are used to dynamically load assets when they haven't been published.

```php
Route::get('_filepond/scripts', function () {
    return Utils::pretendResponseIsFile(__DIR__.'/../resources/dist/filepond.js');
})->name('livewire-filepond.scripts');

Route::get('_filepond/styles', function () {
    return Utils::pretendResponseIsFile(__DIR__.'/../resources/dist/filepond.css', 'text/css');
})->name('livewire-filepond.styles');
```

--------------------------------

### clearPhoto method using resetFilePond

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Example usage of resetFilePond to clear the 'file' property and reset the FilePond instance.

```php
public function clearPhoto(): void
{
    $this->resetFilePond('file');
}
```

--------------------------------

### Register livewire-filepond.scripts route

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/endpoints.md

Registers the GET /_filepond/scripts route that serves the compiled filepond.js bundle using Livewire's pretendResponseIsFile. No middleware or authentication is declared, and the route is public.

```php
Route::get('_filepond/scripts', function () {
    return Utils::pretendResponseIsFile(__DIR__.'/../resources/dist/filepond.js');
})->name('livewire-filepond.scripts');
```

--------------------------------

### Profile component with Laravel validation and validateUploadedFile

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Example component using WithFilePond with Laravel validation. The rules() method defines validation rules for the file property, and validateUploadedFile() calls $this->validate() before returning true to accept the file.

```php
use Livewire\Component;
use Spatie\LivewireFilepond\WithFilePond;

class Profile extends Component
{
    use WithFilePond;

    public $file;

    public function rules(): array
    {
        return [
            'file' => 'required|mimetypes:image/jpg,image/jpeg,image/png|max:3000',
        ];
    }

    public function validateUploadedFile(): bool
    {
        $this->validate();

        return true;
    }
}
```

--------------------------------

### Override filePondRemovalRoots to add extra root

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Example override that returns the public directory plus an additional absolute path, for apps that link directories into the public dir without registering them in filesystems.links.

```php
/** @return array<int, string> */
protected function filePondRemovalRoots(): array
{
    return [public_path(), '/absolute/path/to/extra-root'];
}
```

--------------------------------

### HTML output of @filepondScripts (non-hot)

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/livewire-filepond-service-provider.md

Shows the HTML output of the @filepondScripts directive in non-hot mode. The {style-url} and {script-url} placeholders are replaced with the resolved asset URLs, and the {version} placeholder is the installed package version used as a cache buster.

```html
<link rel="stylesheet" type="text/css" href="{style-url}?v={version}">
<script type="module" src="{script-url}?v={version}" data-navigate-once defer data-navigate-track></script>
```

--------------------------------

### Default canRemoveFile implementation

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Default implementation that always returns true, allowing deletion of any file. Override to narrow the deletable scope. The given path is relative to the public directory and always starts with a slash.

```php
/**
 * Default returns true, override in your component to narrow down
 * which files may be deleted from disk. The given path is relative
 * to the public directory and always starts with a slash.
 */
protected function canRemoveFile(string $path): bool
{
    return true;
}
```

--------------------------------

### Restrict file deletion with canRemoveFile

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Override canRemoveFile to restrict which files may be deleted when a user removes a loaded file. The $path argument is relative to the public directory and always starts with a slash. Only files that are attached to the wired property and live inside the public directory (or symlinked directories) are deleted by default.

```php
use Livewire\Component;
use Spatie\LivewireFilepond\WithFilePond;

class MyLivewireComponent extends Component
{
    use WithFilePond;

    public $file;

    protected function canRemoveFile(string $path): bool
    {
        return str_starts_with($path, '/uploads/');
    }
}
```

--------------------------------

### Publish livewire-filepond views

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Publish the package views for customization.

```bash
php artisan vendor:publish --tag="livewire-filepond-views"
```

--------------------------------

### packageBooted(): void

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/livewire-filepond-service-provider.md

Runs after the package is booted; registers routes, the Blade component alias, and the Blade directive.

```APIDOC
## `packageBooted(): void`

### Description
Runs after the package is booted; registers routes, the Blade component alias, and the Blade directive.

### Method
`packageBooted`

### Signature
`packageBooted(): void`

### Parameters
None.

### Return Type
`void`

### Behavior
- Registers two GET routes for serving the built FilePond bundle.
- Aliases the anonymous Blade component `livewire-filepond::upload` as `filepond::upload`.
- Defines the `@filepondScripts` Blade directive.

### Route Registration
```php
Route::get('_filepond/scripts', function () {
    return Utils::pretendResponseIsFile(__DIR__.'/../resources/dist/filepond.js');
})->name('livewire-filepond.scripts');

Route::get('_filepond/styles', function () {
    return Utils::pretendResponseIsFile(__DIR__.'/../resources/dist/filepond.css', 'text/css');
})->name('livewire-filepond.styles');
```

### Blade Component Registration
```php
Blade::component('livewire-filepond::upload', 'filepond::upload');
```

### @filepondScripts Blade Directive

| Directive | Usage |
|-----------|-------|
| `@filepondScripts` | Render the FilePond stylesheet link and module script in a layout or view |

**Output resolution order:**
1. **Hot (Vite dev server)**: when `resources/hot` exists, its URL is read and two `<script type="module">` tags are emitted — `{url}/resources/js/filepond.js` and `{url}/@vite/client` — both with `defer data-navigate-track`.
2. **Published static assets**: if `public_path('vendor/livewire-filepond/filepond.js')` exists, `asset('/vendor/livewire-filepond/filepond.js')` is used; likewise for `filepond.css`.
3. **Dynamic package routes (default)**: `route('livewire-filepond.scripts')` and `route('livewire-filepond.styles')` are used.

In non-hot mode the output is:
```html
<link rel="stylesheet" type="text/css" href="{style-url}?v={version}">
<script type="module" src="{script-url}?v={version}" data-navigate-once defer data-navigate-track></script>
```

The `?v=` query string is the installed package version from `Composer\InstalledVersions::getPrettyVersion('spatie/livewire-filepond')` and acts as a cache buster.

**Example — layout usage:**
```bladehtml
<!DOCTYPE html>
<html>
<head>
    ...
    @filepondScripts
</head>
<body>
    @livewire('profile')
</body>
</html>
```
```

--------------------------------

### Create a FilePond instance with LivewireFilePond.create

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Creates a FilePond instance from a DOM element using the LivewireFilePond global. The returned instance supports setOptions(), addFiles(), removeFiles(), and on().

```javascript
const pond = LivewireFilePond.create($refs.input);
```

--------------------------------

### window.LivewireFilePond

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Global namespace exposing the full filepond module. The `create` factory is used to instantiate a FilePond instance.

```APIDOC
## `window.LivewireFilePond`

### Description
Exposes the full `filepond` module namespace as a global. In practice the blade component uses the `create` factory to instantiate a FilePond instance.

### Method
`create(element, options?)`

### Parameters
- **element** (HTMLElement) - Required - The input element to attach FilePond to.
- **options** (object) - Optional - FilePond configuration options.

### Returns
A `FilePond` instance with `setOptions()`, `addFiles()`, `removeFiles()`, and `on()` methods. All FilePond v4 API surface remains available.

### Example
```js
const pond = LivewireFilePond.create($refs.input);
```
```

--------------------------------

### Register FilePond plugins in resources/js/filepond.js

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Imports FilePond core, its CSS, and six plugins, then registers each plugin. Because plugins are registered here, their options can be passed as kebab-case attributes on <x-filepond::upload> and are forwarded to pond.setOptions().

```javascript
import * as FilePond from 'filepond';
import 'filepond/dist/filepond.css';
import 'filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css';

import FilePondPluginImagePreview from 'filepond-plugin-image-preview';
import FilePondPluginFileValidateSize from 'filepond-plugin-file-validate-size';
import FilePondPluginFileValidateType from 'filepond-plugin-file-validate-type';
import FilePondPluginImageCrop from 'filepond-plugin-image-crop';
import FilePondPluginImageTransform from 'filepond-plugin-image-transform';
import FilePondPluginImageResize from 'filepond-plugin-image-resize';

FilePond.registerPlugin(FilePondPluginImagePreview);
FilePond.registerPlugin(FilePondPluginFileValidateSize);
FilePond.registerPlugin(FilePondPluginFileValidateType);
FilePond.registerPlugin(FilePondPluginImageCrop);
FilePond.registerPlugin(FilePondPluginImageResize);
FilePond.registerPlugin(FilePondPluginImageTransform);
```

--------------------------------

### window.URLtoFile

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Fetches a file from a URL or public-relative path and converts it into a FilePond file-init object, marking it as a locally stored file. Useful for preloading existing files into a FilePond instance.

```APIDOC
## `window.URLtoFile` — `URLtoFile(path): Promise<FilePondFileInit>`

### Description
Fetches a file from a URL or public-relative path and converts it into a FilePond file-init object, marking it as a locally stored file. Useful for preloading existing files into a FilePond instance.

### Method
`URLtoFile(path)`

### Parameters
- **path** (string) - Required - URL or public-relative path of the stored file (e.g. `/uploads/photo.jpg` or `https://cdn.example.com/a.jpg`).

### Returns
A `Promise` resolving to a FilePond file-init object:
```
{
  source: File,          // File built from the fetched blob; name is the raw path, metadata attached
  options: {
    type: 'local',       // marks the item as a locally (already-)stored file, not a pending upload
    metadata: {
      name: string,      // last path segment
      path: string,      // the original path argument
      size: number,      // blob byte size
      type: string       // blob MIME type
    }
  }
}
```

### Errors
Rejects when `fetch(url)` or `response.blob()` fails (network error, non-2xx response without a body, CORS, invalid URL).

### Example
```js
const item = await URLtoFile('/uploads/photo.jpg');
const pond = LivewireFilePond.create(document.querySelector('input[type=file]'));
pond.addFiles([item]);
console.log(item.options.metadata.path); // '/uploads/photo.jpg'
```

Error handling when the file cannot be fetched:
```js
try {
    const item = await URLtoFile('/uploads/deleted.jpg');
    pond.addFiles([item]);
} catch (e) {
    console.error('Could not load file for FilePond', e);
    // FilePond instance remains functional; user can upload a replacement
}
```
```

--------------------------------

### Publish livewire-filepond translations

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Publish the language file to customize translations.

```bash
php artisan vendor:publish --tag="livewire-filepond-translations"
```

--------------------------------

### Alpine.js x-init Initialization Flow

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/upload-component.md

The initialization sequence for the FilePond instance. It loads existing files, configures options, and registers event listeners for file operations.

```js
(async () => {
  await loadModel();

  const pond = LivewireFilePond.create($refs.input);

  pond.setOptions({ allowMultiple: isMultiple, server: { ... }, required: @js($required), disabled: @js($disabled) });
  pond.setOptions(@js($pondLocalizations));       // __('livewire-filepond::filepond') — label translations
  pond.setOptions(@js($pondProperties));          // camelCased forwarded attributes
  // if a custom $placeholder was passed:
  pond.setOptions({ labelIdle: @js($placeholder) });
  pond.addFiles(files)
  pond.on('addfile', (error, file) => { if (error) console.log(error); });
  pond.on('warning', (error) => { if (error?.body === 'Max files' && {maxFiles ? 'true' : 'false'}) { ... } });
  pond.on('processfiles', () => { $wire.dispatchSelf('filepond-upload-completed', {attribute: property}); });
  $wire.on('filepond-reset-{property}', () => { pond.removeFiles(); });
})();
```

--------------------------------

### Define window.URLtoFile helper function

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Defines the URLtoFile async function that fetches a file from a URL, converts it to a File object, and returns a FilePond file-init object. Assigns it to window.URLtoFile for global use.

```javascript
const URLtoFile = async function (path) {
    let url = `${path}`;
    let name = url.split('/').pop();
    const response = await fetch(url);
    const data = await response.blob();
    const metadata = {
        name: name,
        path: path,
        size: data.size,
        type: data.type
    };
    let file = new File([data], path, metadata);

    return {
        source: file,
        options: {
            type: 'local',
            metadata,
        }
    }
}

window.URLtoFile = URLtoFile;
```

--------------------------------

### Run tests with Composer

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Runs the package's test suite.

```bash
composer test
```

--------------------------------

### LivewireFilepondServiceProvider class

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/livewire-filepond-service-provider.md

The service provider class that configures the package by declaring its name and enabling assets, views, and translations. The packageBooted method is a placeholder for routes, Blade component, and Blade directive registration.

```php
class LivewireFilepondServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('livewire-filepond')
            ->hasAssets()
            ->hasViews()
            ->hasTranslations();
    }

    public function packageBooted(): void
    {
        // ...routes, Blade component, Blade directive (see below)
    }
}
```

--------------------------------

### Default filePondRemovalRoots implementation

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Default implementation that returns the public directory plus all keys from the filesystems.links config map (defaulting to public_path('storage') => storage_path('app/public')). Non-resolvable entries are filtered out.

```php
/**
 * @return array<int, string>
 */
protected function filePondRemovalRoots(): array
{
    $links = config('filesystems.links') ?? [public_path('storage') => storage_path('app/public')];

    return collect([public_path(), ...array_keys($links)])
        ->map(fn (string $root) => realpath($root))
        ->filter()
        ->values()
        ->all();
}
```

--------------------------------

### Preload a file into FilePond using URLtoFile

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Fetches a file from a public path and adds it to a FilePond instance. Logs the metadata path to confirm the preloaded item.

```javascript
const item = await URLtoFile('/uploads/photo.jpg');
const pond = LivewireFilePond.create(document.querySelector('input[type=file]'));
pond.addFiles([item]);
console.log(item.options.metadata.path); // '/uploads/photo.jpg'
```

--------------------------------

### Assign FilePond module to window.LivewireFilePond

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Exposes the full FilePond module namespace as window.LivewireFilePond. Use this global to access the create factory and other FilePond v4 API methods.

```javascript
window.LivewireFilePond = FilePond;
```

--------------------------------

### Vite configuration for building filepond assets

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Configures Vite to build the filepond.js entry point into resources/dist with flat output, sourcemaps enabled, and no manifest. The Laravel plugin is set to watch the resources directory and refresh on changes.

```javascript
export default defineConfig({
    build: {
        sourcemap: true,
        manifest: false,
        rollupOptions: {
            output: {
                entryFileNames: `[name].js`,
                chunkFileNames: `[name].js`,
                assetFileNames: `[name].[ext]`
            },
        },
    },
    plugins: [
        laravel({
            input: ['resources/js/filepond.js'],
            refresh: true,
            publicDirectory: 'resources',
            buildDirectory: 'dist',
        }),
    ],
})
```

--------------------------------

### Publish Livewire Filepond assets

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Publishes the package's assets so they can be served directly instead of through the automatic endpoint. Use the --force flag to overwrite existing files. Add this command to Composer's post-update-cmd scripts to keep assets up to date.

```shell
php artisan vendor:publish --tag=livewire-filepond-assets --force
```

--------------------------------

### FilePond Server Adapter Configuration

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/upload-component.md

The server configuration object for FilePond, defining process, revert, and remove callbacks that interact with Livewire methods.

```js
server: {
    process: async (fieldName, file, metadata, load, error, progress) => {
        $wire.dispatchSelf('filepond-upload-started', '{{ $wireModelAttribute }}');
        await @this.upload('{{ $wireModelAttribute }}', file, async (response) => {
          let validationResult  = await @this.call('validateUploadedFile', response);
          if (validationResult === true) {
              load(response);
              $wire.dispatchSelf('filepond-upload-finished', { '{{ $wireModelAttribute }}': response });
          } else {
              error('Filepond Api Ignores This Message');
              $wire.dispatchSelf('filepond-upload-reset', '{{ $wireModelAttribute }}');
          }
        }, error, (event) => {
              progress(event.detail.progress, event.detail.progress, 100);
        });
    },
    revert: async (filename, load) => {
        await @this.revert('{{ $wireModelAttribute }}', filename, load);
        $wire.dispatchSelf('filepond-upload-reverted', {'attribute' : '{{ $wireModelAttribute }}'});
    },
    remove: async (file, load) => {
        await @this.remove('{{ $wireModelAttribute }}', file.name);
        load();
        $wire.dispatchSelf('filepond-upload-file-removed', {'attribute' : '{{ $wireModelAttribute }}'});
    },
}
```

--------------------------------

### Customize Filepond component with max-files

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Customize the component by passing Filepond properties in kebab case, e.g., max-files.

```bladehtml
<x-filepond::upload wire:model="file" max-files="5" />
```

--------------------------------

### Set locale via .env

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Change the locale by setting APP_LOCALE in the .env file.

```env
APP_LOCALE=id # change to Indonesian for example
```

--------------------------------

### Rendered HTML Markup

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/upload-component.md

The base HTML structure for the FilePond component. It uses wire:ignore to prevent Livewire re-renders and x-cloak to manage visibility during Alpine initialization.

```html
<div class="{class}" wire:ignore x-cloak x-data="..." x-init="async () => { ... }">
    <input type="file" x-ref="input">
</div>
```

--------------------------------

### isSafeFilePondPath() - Check path safety

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Rejects paths that could escape the public directory. Returns false when the path contains a null byte ("\0") or any segment equal to '..'; otherwise returns true.

```php
protected function isSafeFilePondPath(string $path): bool
{
    if (str_contains($path, "\0")) {
        return false;
    }

    return ! in_array('..', preg_split('#[/\\\\]#', $path) ?: [], strict: true);
}
```

--------------------------------

### filePondPropertyHolds() guard method

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Guard method used by remove() to verify the wired property value references the file being removed. Returns true when a strict in_array or comparison finds either the normalized path or the raw filename.

```php
protected function filePondPropertyHolds(mixed $uploads, string $path, string $filename): bool
{
    if (is_array($uploads)) {
        return in_array($path, $uploads, strict: true)
            || in_array($filename, $uploads, strict: true);
    }

    return $uploads === $path || $uploads === $filename;
}
```

--------------------------------

### Validate uploaded file with WithFilePond

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Use this component to validate uploaded files immediately on upload. The rules() method defines validation rules for the 'file' property, and validateUploadedFile() triggers validation and returns true if valid. This allows processing uploads without requiring a button click.

```php
use Livewire\Component;
use Spatie\LivewireFilepond\WithFilePond;

class MyLivewireComponent extends Component
{
    use WithFilePond;
    
    public $file;

    public function rules(): array
    {
        return [
            'file' => 'required|mimetypes:image/jpg,image/jpeg,image/png|max:3000',
        ];
    }
    public function validateUploadedFile()
    {
        $this->validate();

        return true;
    }
}
```

--------------------------------

### Trait declaration for WithFilePond

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Shows the trait declaration, which uses WithFileUploads. The trait must be used in a class extending Livewire\Component.

```php
trait WithFilePond
{
    use WithFileUploads;
    ...
}
```

--------------------------------

### Return value structure of URLtoFile

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Shows the shape of the Promise resolution from URLtoFile. The source is a File object, and options.type is 'local' to mark it as an already-stored file.

```text
{
  source: File,          // File built from the fetched blob; name is the raw path, metadata attached
  options: {
    type: 'local',       // marks the item as a locally (already-)stored file, not a pending upload
    metadata: {
      name: string,      // last path segment
      path: string,      // the original path argument
      size: number,      // blob byte size
      type: string       // blob MIME type
    }
  }
}
```

--------------------------------

### Handle URLtoFile fetch errors

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/javascript-module.md

Wraps URLtoFile in a try/catch to handle fetch failures. Logs an error and keeps the FilePond instance functional so the user can upload a replacement.

```javascript
try {
    const item = await URLtoFile('/uploads/deleted.jpg');
    pond.addFiles([item]);
} catch (e) {
    console.error('Could not load file for FilePond', e);
    // FilePond instance remains functional; user can upload a replacement
}
```

--------------------------------

### Use WithFilePond trait in Livewire component

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Add the WithFilePond trait to your Livewire component to enable file uploads.

```php
use Livewire\Component;
use Spatie\LivewireFilepond\WithFilePond;

class MyLivewireComponent extends Component
{
    use WithFilePond;
    
    public $file;
}
```

--------------------------------

### remove() method implementation

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

The remove() method removes a file from the wired property and deletes it from disk if safe. It checks property existence, path safety, and file ownership before updating the property and deleting the file.

```php
public function remove(string $property, string $filename): void
{
    if (! $this->hasProperty($property)) {
        return;
    }

    $path = $this->normalizeFilePondPath(Str::after($filename, (string) config('app.url')));

    if (! $this->isSafeFilePondPath($path)) {
        return;
    }

    $uploads = $this->getPropertyValue($property);

    if (! $this->filePondPropertyHolds($uploads, $path, $filename)) {
        return;
    }

    app(LivewireManager::class)->updateProperty(
        $this,
        $property,
        is_array($uploads)
            ? array_values(array_filter($uploads, fn ($item) => $item !== $path && $item !== $filename))
            : null,
    );

    $target = $this->filePondRemovalTarget($path);

    if ($target === null) {
        return;
    }

    if (! $this->canRemoveFile($path)) {
        return;
    }

    File::delete($target);
}
```

--------------------------------

### Add Filepond scripts to layout

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Add the Filepond scripts to your layout or view where you want to use Filepond.

```bladehtml
@filepondScripts
```

--------------------------------

### normalizeFilePondPath() - Normalize a path

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Normalizes a browser-supplied path into a canonical, slash-prefixed form. It removes empty segments and '.' segments, but does not collapse '..' segments; that check is left to isSafeFilePondPath().

```php
protected function normalizeFilePondPath(string $path): string
{
    $segments = array_filter(
        preg_split('#[/\\\\]#', $path) ?: [],
        fn (string $segment) => $segment !== '' && $segment !== '.',
    );

    return '/'.implode('/', $segments);
}
```

--------------------------------

### Handle Max files warning in JavaScript

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/upload-component.md

This JavaScript snippet listens for the FilePond 'warning' event. When the error body is 'Max files', it calls the Livewire component method 'setMaxFilesError' with a formatted message.

```javascript
pond.on('warning', (error) => {
    if (error?.body === 'Max files' && {{ $maxFiles ? 'true' : 'false' }}) {
        const message = @js($maxfilesmsg).replace(':max', {{ $maxFiles ?? 0 }});
        $wire.call('setMaxFilesError', message);
    }
});
```

--------------------------------

### filePondRemovalRoots(): array (protected)

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Absolute directory roots from which `remove()` is allowed to delete files. Override this if your app links directories into the public dir without registering them in `filesystems.links`.

```APIDOC
## filePondRemovalRoots(): array (protected)

### Description
Absolute directory roots from which `remove()` is allowed to delete files. Override this if your app links directories into the public dir without registering them in `filesystems.links`.

### Method
filePondRemovalRoots

### Parameters
No arguments.

### Return Type
- `array<int, string>` — a re-indexed list of real (absolute, symlink-resolved) paths: the public directory plus every key of the `filesystems.links` config map (defaulting to `public_path('storage') => storage_path('app/public')`). Non-resolvable entries are filtered out.

### Override Example
protected function filePondRemovalRoots(): array
{
    return [public_path(), '/absolute/path/to/extra-root'];
}
```

--------------------------------

### resetFilePond(string $property): void implementation

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Resets the wired property and dispatches the filepond-reset-{property} event. The blade component listens for this event (scoped via $wire.on) and calls pond.removeFiles() to remove all rendered files.

```php
public function resetFilePond(string $property): void
{
    $this->reset($property);
    $this->dispatch("filepond-reset-$property");
}
```

--------------------------------

### filePondRemovalTarget() - Resolve removal target

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Resolves a public-relative path to an absolute path that may be deleted, or returns null. Returns the realpath()-resolved absolute path when it exists and is inside one of the removal roots; null when the file does not exist on disk or lives outside every removal root (including files behind symlinks not registered in filesystems.links).

```php
protected function filePondRemovalTarget(string $path): ?string
{
    $target = realpath(public_path($path));

    if ($target === false) {
        return null;
    }

    foreach ($this->filePondRemovalRoots() as $root) {
        if (str_starts_with($target, $root.DIRECTORY_SEPARATOR)) {
            return $target;
        }
    }

    return null;
}
```

--------------------------------

### Set locale dynamically with App facade

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Change the locale on the fly using Laravel's App facade, useful when a user changes the language.

```php
use Illuminate\Support\Facades\App;

App::setLocale('id'); // change to Indonesian for example
```

--------------------------------

### resetFilePond(string $property): void

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Resets the wired property and tells the FilePond instance to remove all rendered files. The blade component listens for the `filepond-reset-{property}` event and calls `pond.removeFiles()`.

```APIDOC
## resetFilePond(string $property): void

### Description
Resets the wired property and tells the FilePond instance to remove all rendered files.

### Method
resetFilePond

### Signature
public function resetFilePond(string $property): void

### Parameters
- **$property** (string) - Required - Name of the wired property to reset

### Return Type
void

### Example
```php
public function resetFilePond(string $property): void
{
    $this->reset($property);
    $this->dispatch("filepond-reset-$property");
}
```

### Usage Example
```php
public function clearPhoto(): void
{
    $this->resetFilePond('file');
}
```
```

--------------------------------

### Render Filepond upload component in Blade

Source: https://github.com/spatie/livewire-filepond/blob/main/README.md

Use this Blade component in a Livewire view to render a Filepond upload field bound to a Livewire property. The wire:model attribute connects the uploaded file to the specified property.

```bladehtml
<x-filepond::upload wire:model="file" />
```

--------------------------------

### revert($property, $filename): void

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Aborts an in-flight upload: deletes the Livewire temporary upload file and detaches it from the property. Handles both single-file and array properties.

```APIDOC
## revert($property, $filename): void

### Description
Aborts an in-flight upload: deletes the Livewire temporary upload file and detaches it from the property.

### Method
revert

### Signature
```php
public function revert($property, $filename): void
```

### Parameters
- `$property` (string) - Required - Name of the wired public property
- `$filename` (string) - Required - The temporary upload's filename, as sent by FilePond's `server.revert` callback

### Return Type
`void`

### Behavior
- Non-array property: if the property holds a `Livewire\Features\SupportFileUploads\TemporaryUploadedFile` whose `getFilename()` matches, the temporary file is deleted and the property is set to `null`.
- Array property: every entry that is a `TemporaryUploadedFile` with a matching filename is deleted and filtered out; other entries are kept. The filtered array is written back through `LivewireManager::updateProperty()`.
- Non-matching values are left untouched. If the property does not exist, the method returns immediately.

### Throws
None.

### Examples
```php
// Called by the FilePond revert flow in the blade component; manual usage:
public function cancelUpload(string $filename): void
{
    $this->revert('file', $filename);
}
```
```

--------------------------------

### Register Blade component alias filepond::upload

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/livewire-filepond-service-provider.md

Aliases the anonymous Blade component at resources/views/upload.blade.php so it can be used as <x-filepond::upload> in views.

```php
Blade::component('livewire-filepond::upload', 'filepond::upload');
```

--------------------------------

### Define @filepondScripts Blade directive

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/livewire-filepond-service-provider.md

Defines the @filepondScripts Blade directive. It resolves asset paths in three priority orders: Vite dev server (resources/hot), published static assets, then dynamic package routes. In non-hot mode it outputs a stylesheet link and a module script tag with a cache-busting version query string from Composer's InstalledVersions.

```php
Blade::directive('filepondScripts', function () {
    $version = InstalledVersions::getPrettyVersion('spatie/livewire-filepond');

    $scripts = [];

    // Default to dynamic js (served by a Laravel route).
    $fullScriptPath = route('livewire-filepond.scripts');
    $fullStylePath = route('livewire-filepond.styles');

    // Use static assets if they have been published
    if (file_exists(public_path('vendor/livewire-filepond/filepond.js'))) {
        $fullScriptPath = asset('/vendor/livewire-filepond/filepond.js');
    }

    if (file_exists(public_path('vendor/livewire-filepond/filepond.css'))) {
        $fullStylePath = asset('/vendor/livewire-filepond/filepond.css');
    }

    if (is_file(__DIR__.'/../resources/hot')) {
        $url = rtrim(file_get_contents(__DIR__.'/../resources/hot'));

        $scripts[] = sprintf('<script type="module" src="%s" defer data-navigate-track></script>', "{$url}/resources/js/filepond.js");
        $scripts[] = sprintf('<script type="module" src="%s" defer data-navigate-track></script>', "{$url}/@vite/client");
    } else {
        $scripts[] = <<<HTML
            <link rel="stylesheet" type="text/css" href="{$fullStylePath}?v={$version}">
            <script type="module" src="{$fullScriptPath}?v={$version}" data-navigate-once defer data-navigate-track></script>
        HTML;
    }

    return implode("\n", $scripts);
});
```

--------------------------------

### Throw exception when wire:model is missing

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/errors.md

Thrown at render time when the <x-filepond::upload> tag lacks a wire:model attribute. Surfaces as a Laravel 500 error and is not catchable from Livewire component code; fix by adding wire:model="someProperty".

```bladehtml
@php
if (! $wireModelAttribute = $attributes->whereStartsWith('wire:model')->first()) {
    throw new Exception("You must wire:model to the filepond input.");
}
@endphp
```

--------------------------------

### validateUploadedFile(): bool default implementation

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Default implementation of the validateUploadedFile hook. Override in your component to add server-side validation on upload. Returning true accepts the file (FilePond load(response) is called); anything else rejects it (FilePond error() is called and the filepond-upload-reset event is fired).

```php
/**
 * Default returns true, override in your component
 */
public function validateUploadedFile(): bool
{
    return true;
}
```

--------------------------------

### remove(string $property, string $filename): void

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Removes a file from the wired property and deletes it from disk if it is within an allowed removal root. This method is called by the FilePond component when a file is removed, and can also be called manually from component code.

```APIDOC
## remove(string $property, string $filename): void

### Description
Removes a file from the wired property and, if the file lives inside an allowed removal root, deletes it from disk. This method is triggered by FilePond's server.remove request or can be called manually.

### Method
remove

### Signature
`public function remove(string $property, string $filename): void`

### Parameters
- **$property** (string) - Required - Name of the public property (wired with `wire:model`) that holds the stored file path(s).
- **$filename** (string) - Required - The file reference the client sends; may be a bare path (`/uploads/photo.jpg`), a full URL (`http://localhost/uploads/photo.jpg`), or a path with trailing-slash `app.url`.

### Return Type
`void`

### Behavior / Conditions
1. If the component has no such property (`hasProperty()` false), the method returns without doing anything.
2. The app-URL prefix is stripped with `Str::after($filename, (string) config('app.url'))`, then the path is normalized (see `normalizeFilePondPath()`).
3. Unsafe paths (null bytes or `..` segments, see `isSafeFilePondPath()`) abort silently.
4. The property value is only modified if it currently holds the path or filename (see `filePondPropertyHolds()`). Array properties are filtered of both the normalized path and the raw filename, re-indexed with `array_values()`, and written back through `LivewireManager::updateProperty()`. Scalar (string/null) properties are set to `null`.
5. The on-disk file is then deleted only if the resolved path exists, lies inside an allowed removal root (`filePondRemovalTarget()`), and `canRemoveFile()` returns `true`.

### Throws
None.

### Examples
Basic call — triggered by FilePond's `server.remove` request with the wired property `photos`:

```bladehtml
<x-filepond::upload wire:model="photos" multiple />
```

```php
use Livewire\Component;
use Spatie\LivewireFilepond\WithFilePond;

class Gallery extends Component
{
    use WithFilePond;

    public array $photos = [];
}
```

The blade component calls `@this.remove('photos', file.name)` when the user removes an item; no application code is required. Calling it manually works the same way:

```php
public function deletePhoto(string $filename): void
{
    // $this->remove() is public; also callable from JS via @this.remove('photos', 'photo.jpg')
    $this->remove('photos', $filename);
}
```

Guarding against deletion outside a sub-directory — override the protected `canRemoveFile()` hook (see below):

```php
protected function canRemoveFile(string $path): bool
{
    return str_starts_with($path, '/uploads/');
}
```
```

--------------------------------

### revert method implementation

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Aborts an in-flight upload by deleting the temporary upload file and detaching it from the property. Handles both non-array and array properties, filtering out matching TemporaryUploadedFile entries.

```php
public function revert($property, $filename): void
{
    if (! $this->hasProperty($property)) {
        return;
    }

    $uploads = $this->getPropertyValue($property);

    if (! is_array($uploads)) {
        if ($uploads instanceof TemporaryUploadedFile && $uploads->getFilename() === $filename) {
            $uploads->delete();
            app(LivewireManager::class)->updateProperty($this, $property, null);
        }

        return;
    }

    $newFiles = collect($uploads)
        ->filter(function ($upload) use ($filename) {
            if (! $upload instanceof TemporaryUploadedFile) {
                return false;
            }

            if ($upload->getFilename() === $filename) {
                $upload->delete();

                return false;
            }

            return true;
        })->values()->toArray();

    app(LivewireManager::class)->updateProperty($this, $property, $newFiles);
}
```

--------------------------------

### Script tag for filepond scripts route

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/endpoints.md

HTML script tag emitted by the @filepondScripts directive to load the filepond.js bundle from the scripts route. Includes a version query parameter as a cache buster and Livewire navigation attributes.

```bladehtml
<script type="module" src="https://example.com/_filepond/scripts?v=1.8.0" data-navigate-once defer data-navigate-track></script>
```

--------------------------------

### Add setMaxFilesError method to Livewire component

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/errors.md

Add this method to the Livewire component when using the `max-files` attribute. It is invoked by the upload blade component when FilePond emits a warning with `error.body === 'Max files'`. Without it, the Livewire call fails and no meaningful action happens client-side.

```php
public function setMaxFilesError(string $message): void
{
    $this->addError('file', $message);
}
```

--------------------------------

### Override canRemoveFile() to guard deletion

Source: https://github.com/spatie/livewire-filepond/blob/main/_autodocs/api-reference/with-file-pond.md

Shows overriding the protected canRemoveFile() hook to restrict deletion to paths under /uploads/.

```php
protected function canRemoveFile(string $path): bool
{
    return str_starts_with($path, '/uploads/');
}
```
Tokens:
Raw