yii2-extensions / filepond

0.2.1 2026-10-22 22:07 UTC

Requires

• php: >=8.3
• ext-fileinfo: *
• ui-awesome/html: ^0.6
• ui-awesome/html-helper: ^0.7
• yiisoft/yii2: ~2.0.55 || ^22.0@dev

Requires (Dev)

• infection/infection: ^0.35
• maglnet/composer-require-checker: ^4.1
• php-forge/coding-standard: ^0.3
• php-forge/foxy: ^0.4
• php-forge/support: ^0.3
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0.3
• phpunit/phpunit: ^12.5
• xepozz/internal-mocker: ^1.4
• yii2-extensions/phpstan: ^0.5

Suggests

• ext-gd: Required by `ImageCropper` to apply crop rectangles on the server.

BSD-3-Clause

• Wilmer Arambula

• widget
• yii2
• yii2-extension
• image-upload
• cropper
• file-upload
• image-crop
• cropperjs
• filepond

Published on Packagist.org on 2026-10-22 22:08 UTC

README

FilePond

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.

Features

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:

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

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 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:

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.

Documentation

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

• 📚 Installation Guide: native Composer setup, asset paths, translations, and assets.
• ⚙️ Configuration Guide: option precedence, plugins, and editor behavior.
• 💡 Usage Examples: runnable widgets and helper demonstrations.
• 🧪 Testing Guide: development checks.
• 📤 Upload Workflow: 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.

The guides and the API reference generated from the PHPDoc in src/ are published at https://yii2-framework.github.io/docs/extensions/filepond/.

AI assistance

AI agents: read the documentation index and fetch the Markdown version of a page by appending index.md to its URL. The AI agents guide covers skill installation, client setup and verification.

• 🤖 yii2-filepond-uploads skill: FilePond uploads.
• 🧭 yii2-framework skill: Yii 22.0 application conventions.

The hosted documentation covers Yii 22.0. If it does not match the installed revision or is unavailable, use the repository guides, the skill source, the source PHPDoc and the changelog.

Package information

Project status

Our social networks

License