PHPackages                             studio255/yii2-fileupload - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. studio255/yii2-fileupload

ActiveYii2-extension[File & Storage](/categories/file-storage)

studio255/yii2-fileupload
=========================

FilePond-based file upload widget for Yii2 — chunked uploads, ActiveRecord binding and image variants.

v1.1.7(2d ago)03↑2900%MITPHPPHP >=8.2

Since Sep 5Pushed 2d agoCompare

[ Source](https://github.com/studio255/yii2-fileupload)[ Packagist](https://packagist.org/packages/studio255/yii2-fileupload)[ Docs](https://github.com/studio255/yii2-fileupload)[ RSS](/packages/studio255-yii2-fileupload/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (2)Versions (12)Used By (0)

yii2-fileupload
===============

[](#yii2-fileupload)

[![Packagist Version](https://camo.githubusercontent.com/d10c5e3cb0e9f0a9bbc46cebecb57bfcf176c07b7b4577079df1df27290db481/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73747564696f3235352f796969322d66696c6575706c6f61643f7374796c653d666c61742d737175617265)](https://packagist.org/packages/studio255/yii2-fileupload)[![PHP](https://camo.githubusercontent.com/785f7956bb6a8b12fed4f715e3bbbec1c1b4bc21b5bd1ba60ed4b0954911722d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344253230382e322d3737374242343f7374796c653d666c61742d737175617265266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://php.net)[![Yii2](https://camo.githubusercontent.com/d9f45637de1aef821941378796c05ce4e2c518a1c09f2a30ecbf7a7037645390/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f596969322d7e322e302e35312d4544314532343f7374796c653d666c61742d737175617265)](https://www.yiiframework.com)[![License: MIT](https://camo.githubusercontent.com/2064788fb84458d8ff362f54c72f9e243482923edc86c7959056107df445aca7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d3232633535653f7374796c653d666c61742d737175617265)](LICENSE)

[FilePond](https://pqina.nl/filepond/)-based file upload widget for Yii2 — chunked uploads, ActiveRecord binding, and image variants out of the box.

---

Features
--------

[](#features)

- **FilePond widget** — drop-in Yii2 widget with auto-initialization for plain `` fields
- **Chunked uploads** — enabled by default, bypasses PHP `post_max_size` limits
- **Multiple files** — configurable file count and MIME type filters
- **ActiveRecord binding** — auto-assigns filenames to model attributes after upload
- **Image variants** — optional server-side resizing (GD-based, keeps PNG transparency)
- **CSRF support** — sends `X-CSRF-Token` header automatically

---

Installation
------------

[](#installation)

```
composer require studio255/yii2-fileupload
```

---

Quick Start
-----------

[](#quick-start)

### 1. Widget in a view

[](#1-widget-in-a-view)

```
use studio255\fileupload\FileUpload;
use yii\helpers\Url;

echo FileUpload::widget([
    'id'            => 'my-upload',
    'url'           => Url::to(['/upload/handle']),
    'acceptedFiles' => 'image/*',   // e.g. 'image/*,application/pdf'
    'maxFiles'      => 5,
    'multiple'      => true,
]);
```

### 2. Controller action

[](#2-controller-action)

```
use studio255\fileupload\UploadHandler;

public function actionHandle()
{
    return UploadHandler::processUpload([
        'targetPath' => \Yii::getAlias('@webroot/uploads'),
        // optional model binding:
        // 'modelClass' => app\models\MyModel::class,
    ]);
}
```

---

Widget Options
--------------

[](#widget-options)

OptionTypeDefaultDescription`id`string`'filepond'`HTML `id` of the input`url`string—Upload URL`multiple`bool`true`Allow multiple files`maxFiles`int|null`5`Maximum number of files`acceptedFiles`string|null`null`Accepted MIME types / extensions`model`array`[]`Extra URL parameters passed to the server`options`array`[]`Additional FilePond options (see below)**Common `options` keys:**

KeyDefaultDescription`chunkUploads``true`Enable chunked uploads`chunkSize``1048576`Chunk size in bytes (1 MB)`extraData``[]`Additional form fields sent with each upload---

UploadHandler Options
---------------------

[](#uploadhandler-options)

```
UploadHandler::processUpload([
    // Paths
    'targetPath' => \Yii::getAlias('@webroot/uploads'),  // default
    'tmpPath'    => \Yii::getAlias('@runtime/fileupload'), // chunk temp dir

    // Model binding (optional)
    'modelClass' => app\models\MyModel::class,
    // model_id and model_attribute are read from GET params by the widget

    // Image variants (optional)
    // 'createVariants' => true,  // generates a_ and w_ prefix files
    // 'a_' => [null, 200],       // thumbnail: height 200 px, keep aspect ratio
    // 'w_' => [800, null],       // preview: width 800 px, keep aspect ratio
]);
```

### Where files are saved

[](#where-files-are-saved)

- Default: `@webroot/uploads/`
- With `model_id` param: `@webroot/uploads/{model_id}/`
    The subfolder is cleared before saving (pass `emptyIdFolder=0` to disable).

---

Multiple Instances
------------------

[](#multiple-instances)

Use `options['instances']` to mount several FilePond ponds from a single widget call:

```
echo FileUpload::widget([
    'options' => [
        'instances' => [
            [
                'id'            => 'pond-cover',
                'url'           => Url::to(['/upload/handle']),
                'multiple'      => false,
                'acceptedFiles' => 'image/*',
            ],
            [
                'id'       => 'pond-gallery',
                'url'      => Url::to(['/upload/handle']),
                'multiple' => true,
                'maxFiles' => 10,
            ],
        ],
    ],
]);
```

---

Plain `` (no widget)
---------------------------

[](#plain-input-no-widget)

The JS helper auto-initializes every `` on DOM ready via `data-*` attributes:

```

```

AttributeDescription`data-url`Upload endpoint`data-multiple``"true"` / `"false"``data-accepted`Accepted MIME types`data-maxfiles`Max number of files`data-model-id`Sent to server as subfolder ID---

Chunked Upload Protocol
-----------------------

[](#chunked-upload-protocol)

The handler implements the FilePond TUS-like protocol automatically:

RequestPurpose`POST` (no files, `Upload-Length` header)Init — returns a temp file ID`HEAD ?patch=`Resume — returns current `Upload-Offset``PATCH ?patch=`Append chunk — finalizes on last chunkThe CSRF token is sent as `X-CSRF-Token` from ``. No extra configuration needed for standard Yii2 setups.

---

Notes
-----

[](#notes)

- Filenames are sanitized server-side: only `A–Z a–z 0–9 - _` plus a lowercase extension are kept. German umlauts are transliterated (`ä→ae`, etc.).
- Image variants require the GD extension. Input formats: JPG, PNG, GIF. PNG output preserves transparency; all others are saved as JPEG at quality 90.
- Assets (FilePond CSS/JS) are registered automatically by the widget.

---

License
-------

[](#license)

MIT

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance99

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~27 days

Total

11

Last Release

2d ago

PHP version history (2 changes)v1.0.0PHP >=8.1

v1.1.6PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/d6dcb82da544394a0e9a641a8772ee633345f2f5b79d835a0e6f7de2d9f2a19f?d=identicon)[studio255](/maintainers/studio255)

---

Top Contributors

[![studio255](https://avatars.githubusercontent.com/u/3940053?v=4)](https://github.com/studio255 "studio255 (17 commits)")

---

Tags

filepondphpuploadwidgetyii2yii2-extensionuploadyii2widgetyii2-extensionfile-uploadfilepond

### Embed Badge

![Health badge](/badges/studio255-yii2-fileupload/health.svg)

```
[![Health](https://phpackages.com/badges/studio255-yii2-fileupload/health.svg)](https://phpackages.com/packages/studio255-yii2-fileupload)
```

###  Alternatives

[noam148/yii2-image-manager

A Yii2 module/widget for upload and cropping images

12914.9k](/packages/noam148-yii2-image-manager)[vova07/yii2-fileapi-widget

The FileAPI widget for Yii2 framework.

4766.0k9](/packages/vova07-yii2-fileapi-widget)[sjaakp/yii2-illustrated-behavior

ActiveRecord Behavior with associated Widget for Yii2.

423.1k](/packages/sjaakp-yii2-illustrated-behavior)[limion/yii2-jquery-fileupload-widget

Blueimp file upload widget for Yii2

1224.7k](/packages/limion-yii2-jquery-fileupload-widget)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)