# FilePond

> FilePond file uploads for Yii2 forms

**FilePond file uploads for Yii2 forms**

_Cropper.js image editing, previews, client and server validation, no jQuery_

File uploads with image previews, a Cropper.js editor, and server-side validation and storage helpers.
The widget initializes FilePond without jQuery and loads only enabled plugin assets.

![FilePond widget with the Cropper.js editor](/docs/_astro/filepond.CB_2L99t.png)

## Features

![Feature Overview](/docs/_astro/features.DtqZ3Vjr.svg)

## Quick start

### Installation

Requires the `fileinfo` extension. Foxy 0.4's native manager installs the frontend assets without Node.js or npm;
it requires PHP `zlib` and Composer 2.10.2+.

Set the manager in the application's root `composer.json` before installing:

```json
{
  "config": {
    "foxy": {
      "manager": "native"
    }
  }
}
```

```bash
composer config allow-plugins.php-forge/foxy true
composer require php-forge/foxy:^0.4 yii2-extensions/filepond:^0.2
```

Foxy installs FilePond, its plugins, and Cropper.js in `node_modules` beside the application's `package.json`.
Commit the generated `foxy.lock` with the application's Composer files. Point Yii's `@npm` alias at that directory;
`@app/node_modules` is correct only when the application `basePath` is the Composer project root. See
[installation](/docs/extensions/filepond/installation/index.md) for alias configuration, existing npm projects, and asset delivery.

### Basic usage

Place this in a Yii view, select a raster image, and edit it with a fixed square selection:

```php
use yii2\extensions\filepond\FilePond;

echo FilePond::widget(
    [
        'name' => 'avatar',
        'acceptedFileTypes' => ['image/jpeg', 'image/png', 'image/webp'],
        'allowImageEdit' => true,
        'allowImageTransform' => true,
        'imageCropAspectRatio' => '1:1',
        'cropper' => ['aspectRatios' => ['1:1']],
        'maxFileSize' => '2MB',
        'config' => ['imageEditInstantEdit' => true],
    ],
);
```

The editor opens when an image is added and offers only the `1:1` ratio preset. Image Transform applies the
confirmed crop before form submission.
Previewing a crop alone does not change the uploaded bytes. To receive, validate, and store the image, follow the
[complete upload workflow](/docs/extensions/filepond/uploads/index.md).

## Documentation

Practical guides and runnable examples for uploads, plugins, and image
editing.

- 📚 [Installation Guide](/docs/extensions/filepond/installation/index.md): native Composer setup, asset paths, translations, and assets.
- ⚙️ [Configuration Guide](/docs/extensions/filepond/configuration/index.md): option precedence, plugins, and editor behavior.
- 💡 [Usage Examples](/docs/extensions/filepond/examples/index.md): runnable widgets and helper demonstrations.
- 🧪 [Testing Guide](/docs/extensions/filepond/testing/index.md): development checks.
- 📤 [Upload Workflow](/docs/extensions/filepond/uploads/index.md): active form, server validation, cropping, and storage.

Server validation inspects decoded bytes rather than trusting the browser's MIME type. List raster MIME types
explicitly when serving uploads from your origin: `image/*` also accepts SVG. Encoded uploads increase request
size; configure the application's request limits as explained in the upload guide.

## AI assistance

AI agents: use the repository guides and source for the installed revision.
For a [documentation deployment](https://yii2-framework.github.io/docs/) with
`llms.txt`, read that index first. When Markdown export is enabled, append
`index.md` to a page URL. For Yii conventions, use the `yii2-framework` skill
from a local framework documentation checkout.

- 🤖 [yii2-filepond-uploads skill](/docs/extensions/filepond/agents/index.md): installation for Claude Code, Codex, and OpenCode.

If the hosted sources are unavailable, use the repository guides and locally available skills.

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)

## License

[License](https://github.com/yii2-extensions/filepond/blob/main/LICENSE)

## Package

- Source code and issues: [yii2-extensions/filepond](https://github.com/yii2-extensions/filepond). Star the repository if the package is useful to you.
- Composer package: [yii2-extensions/filepond](https://packagist.org/packages/yii2-extensions/filepond).
- Changelog: [CHANGELOG.md](https://github.com/yii2-extensions/filepond/blob/main/CHANGELOG.md).