PHPackages                             flaviovs/yii2-imagefilter - 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. [Image & Media](/categories/media)
4. /
5. flaviovs/yii2-imagefilter

ActiveYii2-extension[Image & Media](/categories/media)

flaviovs/yii2-imagefilter
=========================

Automatic image filtering for Yii2

1.4.1(1mo ago)01.3k1MITPHPPHP >=5.4.0

Since Nov 13Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/flaviovs/yii2-imagefilter)[ Packagist](https://packagist.org/packages/flaviovs/yii2-imagefilter)[ RSS](/packages/flaviovs-yii2-imagefilter/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (2)Versions (8)Used By (1)

Yii2 Imagefilter extension
==========================

[](#yii2-imagefilter-extension)

The Yii2 Imagefilter extension provides a mechanism to automatically transform and generate ("filter") image files. For example, you can define a pipeline called "thumbnail-100", and add a filter to it that transforms an image into a 100px thumbnail. When the pipeline image URL is accessed for the first time, Yii2 Imagefilter will apply all filters configured pipeline, and then save and output the image. On a properly configured web server software (i.e. nginx, Apache, etc.), the next time the image URL is accessed the file is served directly, withou any PHP/Yii2 overhead.

**Important**: processed images are saved to your `@webroot`, so your web server should be configured to serve existing files directly. Also, this extension requires `enablePrettyUrl` to be enabled in your Yii2 URL manager configuration. See for more info.

Usage
-----

[](#usage)

1. Configure the `imagefilter` component in your Yii2 application. This usually means editing `@app\config\web.php` and including the following lines:

    ```
    'components' => [
        // (...)
        'imagefilter' => [
            'class' => \fv\yii\imagefilter\Component::class,
            'pipelines' => [
                'thumbnail-100' => [
                    'filters' => [
                        [
                            'class' => 'app\filters\Scale',
                            'width' => 100,
                            'height' => 100,
                        ],
                    ],
                ],
            ],
        ],
        // (...)
    ]
    ```

    Notice that you can have several filters in a single pipeline. Multiple filters are applied in the sequence they are configured.

    See *Creating filters* below to know about creating image filters.
2. Add the image filter Action to one of your controllers. For example, you could create a controller that looks like this:

    ```
    namespace app\controllers;

    class ImageController extends \yii\web\Controller
    {
        public function actions()
        {
     	   return [
     		   'filter' => \fv\yii\imagefilter\Action::class,
     	   ];
        }
    }
    ```
3. Configure an URL rule pointing to the Imagefilter action you just created in the previous step:

    ```
    'urlManager' => [
        // (...)
        'rules' => [
            // (...)
            'assets/img///' => 'image/filter',
            // (...)
         ],
    ],
    ```
4. Generate URLs to images using the `imagefilter` component.

    To generate na URL, call `$app->imagefilter->url()`:

    ```
    $app->imagefilter->url('thumbnail-100', '/img/foobar.png')
    ```

    Call `$app->imagefilter->img()` to generate a complete `` tag:

    ```
    $app->imagefilter->img('thunbnail-100', '/img/foobar.png', ['alt' => 'Foo bar']);
    ```

    Note: URL path and options array are used the same way as in [\\yii\\helpers\\Html::img()](https://www.yiiframework.com/doc/api/2.0/yii-helpers-basehtml#img()-detail).

Creating filters
----------------

[](#creating-filters)

Filters are defined by PHP classes that implements the `fv\yii\imagefilter\Filter` interface:

```
class MyFilter extends \yii\base\BaseObject implements \fv\yii\imagefilter\Filter
{
    public $width;
    public $height;

    public function filterImage($src, $dest)
	{
         \yii\imagine\Image::thumbnail($src, $this->width, $this->height)
            ->save($dest);
    }
}
```

The separate [Yii2 Imagefilters](https://github.com/flaviovs/yii2-imagefilters) extension (note: plural) contains some ready-to-use filters for Yii2 Imagefilter.

Pipeline versioning
-------------------

[](#pipeline-versioning)

Each pipeline can have a version (default "0"). The version is used to generate the final, filtered image URL. This allow you to force browsers to load new images on the next requests by just changing a pipeline version. This also allows you to implement very aggressive caching for image files (i.e. you can instructing your web server to generate HTTP caching headers that expire image files far in the future).

Example:

```
'standard-watermark' => [
    'filters' => [
        [
            'class' => 'app\filters\Scale',
            'width' => 400,
            'height' => 400,
        ],
        [
            'class' => 'app\filters\AddWatermark',
            'text' => 'My Image',
            'fontSize' => 10,
            'x' => -1,
            'y' => -1,
        ],
    ],
]
```

Since no version was specified, this pipeline is assigned version "0" (you can check this by looking at URLs of filtered images, which should be like `/assets/img/standard-watermark/0/img/my-image.png` -- note the "0" as the fourth element in the path).

Now suppose that you changed your watermark font size from 10 to 12 pixels. To force browsers to load new images, just change the pipeline version:

```
'standard-watermark' => [
    'version' => '1', // Force a new version
    'filters' => [
        // (...)
        [
            // (...)
            'fontSize' => 12,
            // (...)
        ],
    ],
]
```

Notes:

1. The extension will never delete older versions from your `@webroot`. You should do it manually.
2. Another approach to force browsers get new filtered images is to simply remove the directory corresponding to the current version. This will force Yii2 Imagefilter to regenerate new images.

Token authentication
--------------------

[](#token-authentication)

By default, URLs are validated using a CRC32 hash of the file path and modification time. This requires filesystem access to compute the token.

For applications without filesystem access (e.g., frontend apps, API services), configure a `tokenSecret` to enable HMAC-based token validation:

```
'imagefilter' => [
    'class' => \fv\yii\imagefilter\Component::class,
    'tokenSecret' => 'your-secret-key',
    // ...
],
```

When `tokenSecret` is configured, the extension accepts an HMAC-SHA1 token in the URL query string. The token must use the format `t:{8chars}` where the 8 characters are the first 8 hex digits of the HMAC-SHA1 hash.

The HMAC is calculated using SHA1 as the algorithm and `tokenSecret` as the key. The data is the path components separated by null bytes:

```
HMAC-SHA1(key=tokenSecret, data="{path}\0{pipeline}\0{version}\0{src}")

```

Where:

- `tokenSecret` - the configured secret key
- `path` - the configured cache path (default: "assets/img")
- `pipeline` - the pipeline name
- `version` - the pipeline version
- `src` - the source image path relative to webroot

Note: Null byte separators (`\0`) are used to prevent injection attacks where a maliciously crafted path component could affect the token calculation.

Examples (using secret `your-secret-key`):

PathTokenassets/img/thumbnail-100/0/img/foobar.png`t:465f8d96`assets/img/thumbnail-100/0/img/subdir/image.jpg`t:7d8f0c12`assets/img/standard-watermark/1/photos/landscape.jpg`t:e92dd6aa`Note: URLs generated by the `url()` method always use the default CRC32. If you need HMAC tokens in your URLs, you must manually construct them using the same algorithm.

Support
-------

[](#support)

Visit

###  Health Score

46

↑

FairBetter than 93% of packages

Maintenance90

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity61

Established project with proven stability

 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 ~448 days

Recently: every ~642 days

Total

7

Last Release

46d ago

### Community

Maintainers

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

---

Top Contributors

[![flaviovs](https://avatars.githubusercontent.com/u/1832699?v=4)](https://github.com/flaviovs "flaviovs (18 commits)")

### Embed Badge

![Health badge](/badges/flaviovs-yii2-imagefilter/health.svg)

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

###  Alternatives

[trntv/yii2-glide

Yii2 Glide Extension

41269.5k9](/packages/trntv-yii2-glide)[maxmirazh33/yii2-uploadable-cropable-image

Yii2 extension for upload and crop images

1020.8k](/packages/maxmirazh33-yii2-uploadable-cropable-image)[developit/yii2-jcrop

 yii2 image cropping extension

101.5k](/packages/developit-yii2-jcrop)

PHPackages © 2026

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