fyii / imagefilter
Automatic image filtering for Yii2
Installs: 277
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Type:yii2-extension
Requires
- php: >=5.4.0
- yiisoft/yii2: ^2.0.0
Suggests
- fyii/imagefilters: Image filters for FYii Imagefilter
This package is not auto-updated.
Last update: 2018-11-14 02:55:59 UTC
README
The Fyii Imagefilter extension provides a mechanism to automatically transform and generate ("filter") image files. For example, you can define a filter pipeline called "thumbnail-100", and add a filter to it that transforms an image into a 100px thumbnail. When the filtered image URL is accessed for the first time, FYii Imagefilter will apply all the filters in the selected 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: filtered 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
https://www.yiiframework.com/doc/guide/2.0/en/runtime-routing#using-pretty-urls
for more info.
Usage
-
Configure the
imagefilter
component in your Yii2 application. This usually means editing@app\config\web.php
and including the following lines:'components' => [ // (...) 'imagefilter' => [ 'class' => \fyii\imagefilter::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.
-
Configure the image filter controller. I.e., add the following to you your Yii2 controller map configuration:
'controllerMap' => [ 'imagefilter' => \fyii\imagefilter\Controller::class, ],
-
Configure an URL rule pointing to the imagefilter controller. Add this to your
urlManager
configuration:'urlManager' => [ // (...) 'rules' => [ // (...) 'assets/img/<pipeline>/<version>/<src:.+>' => 'imagefilter/view', // (...) ], ],
-
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<img>
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().
Creating filters
Filters are defined by PHP classes that implements the
fyii\imagefilter\Filter
interface:
class MyFilter extends \yii\base\BaseObject implements \fyii\imagefilter\Filter { public $width; public $height; public function filterImage($src, $dest) { \yii\imagine\Image::thumbnail($src, $this->width, $this->height) ->save($dest); } }
The separate FYii Imagefilters extension (note: plural) contains ready-made filters to be used with FYii Imagefilter.
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, add a version configuration to the filters:
'standard-watermark' => [ 'version' => '1', // Force a new version 'filters' => [ // (...) [ // (...) 'fontSize' => 12, // (...) ], ], ]
Notes:
-
The extension will not delete older versions from your
@webroot
. You should do it manually. -
Another approach to force browsers get new filtered images is to simply remove the directory corresponding to the current version. This will force FYii imagefilter to regenerate new images.