Image variations (image aliases) allow you to define and use different v= ersions of the same image. You generate variations based on filters which m= odify aspects such as size and proportions, quality or decorations.
Image variations are generated with LiipImagine=
Bundle, using the underlying Imagine library from a=
valanche123. This bundle supports GD, Imagick or Gmagick PHP exten=
sions, and allows you to define flexible filters in PHP. Image files a=
re stored using the IOService, and are completely independent =
from the ezimage Field Type. T=
hey are generated only once and cleared on demand (e.g. on content removal)=
.
Custom image variations are defined in ezplatform.yml or an=
y imported semantic configuration file. The definition is dynamic, so it can be c=
onfigured per siteaccess and all the other scopes.
ezpublish:
system:
my_siteaccess:
image_variations:
small:
reference: null
filters:
- { name: geometry/scaledownonly, params: [100, 160=
] }
medium:
reference: null
filters:
- { name: geometry/scaledownonly, params: [200, 290=
] }
listitem:
reference: null
filters:
- { name: geometry/scaledownonly, params: [130, 190=
] }
articleimage:
reference: null
filters:
- { name: geometry/scalewidth, params: [770] }=20
_ or=20
- or numbers, but no spaces.
The following parameters are set for each variation:
reference: Name of a reference variation to base the va=
riation on. If set to null (or ~, which means ezpublish=
namespace, or a filter_set defined in the liip_i=
magine namespace.
filters: Array of filter definitions (hashes containing=
name and params keys). See possible values below.
A few basic image variations are included by default in eZ Platform in t=
he default_settings.yml confi=
g file:
ezsettings.default.image_variations:
reference:
reference: ~
filters:
geometry/scaledownonly: [600, 600]
small:
reference: reference
filters:
geometry/scaledownonly: [100, 100]
tiny:
reference: reference
filters:
geometry/scaledownonly: [30, 30]
medium:
reference: reference
filters:
geometry/scaledownonly: [200, 200]
large:
reference: reference
filters:
geometry/scaledownonly: [300, 300]=20
This configuration defines a medium image variation th=
at is scaled to a width of 700 px.
ezpublish:
system:
my_siteaccess:
image_variations:
medium:
reference: null
filters:
- geometry/scalewidth:
=09=09=09=09=09 params: [770]=20
This configuration adds a limit to the image quality using a liip filter= .
You can use both an eZ Platform and a liip filter for the same image var=
iation, in this case medium.
ezpublish:
system:
my_siteaccess:
image_variations:
=09=09=09=09# List of variations
liip_imagine:
driver: imagick
filter_sets:
medium:
jpeg_quality: 50=20
Notice that the liip_imagine key is not placed under&n=
bsp;image_variations, but at the same level as ezpu=
blish.
LiipImagineBundle supports post-processors on image aliases. It is possible to spe= cify them in image variation configuration:
ezpublish:
system:
my_siteaccess:
image_variations:
articleimage:
reference: null
filters:
- { name: geometry/scalewidth, params: [770] }
post_processors:
jpegoptim: {}=20
Please refer to post-processors documentation in LiipImagineBundle for deta= ils.
LiipImagineBundle supports GD (default), Imagick and GMagick PHP extensi= ons and only works on image blobs (no command line tool is needed). See the= bundle's documentatio= n to learn more on that topic.
LiipImagineBundle in your kernel classIf you were using ImageMagick, install Imagick or Gmagick PHP =
extensions and activate the driver in liip_imagine (see LiipImagineBundle configurat=
ion documentation for more information):
# ezplatform.yml or config.yml
liip_imagine:
# Driver can be either "imagick", "gmagick" or "gd", depending on the P=
HP extension you're using.
driver: imagick=20
GD will be used by default if no driver is specified.
It is possible to use the Liip Imagine console tool to clear generated a= liases.
$ php app/console liip:imagine:cache:remove --filters=3Dlarge $ php app/console liip:imagine:cache:remove -v=20
The first example will clear the image files for the large alias. The second will clear all the generated aliases (be careful), a=
nd list the removed files (-v).
The naming scheme change introduced by this feature wasn't enabled by de= fault on 5.4.x. As part of migration you'll need to adapt to the new schema= to get the benefit of this more efficient purge method. More technical inf= ormation can be found on the pull request= .
In addition to filt= ers exposed by LiipImagineBundle, the following are available:
| Filter name | Parameters | Description |
|---|---|---|
| geometry/scaledownonly | [width, height] | Generates a thumbnail that will not exceed width= /height. |
| geometry/scalewidthdownonly | [width] | Generates a thumbnail that will not exceed width= . |
| geometry/scaleheightdownonly | [height] | Generates a thumbnail that will not exceed heigh= t. |
| geometry/scalewidth | [width] | Alters image width. Proportion will be kept. |
| geometry/scaleheight | [height] | Alters image height. Proportion will be kept. |
| geometry/scale | [width, height] | Alters image size, not exceeding provided width = and height. Proportion will be kept. |
| geometry/scaleexact | [width, height] | Alters image size to fit exactly provided width = and height. Proportion will not be kept. |
| geometry/scalepercent | [widthPercent, heightPercent] | Scales width and height with provided percent va= lues. Proportion will not be kept. |
| geometry/crop | [width, height, startX, startY] | Crops the image. Result will have provided width= /height, starting at provided startX/startY |
| border | [thickBorderX, thickBorderY, color=3D#000] | Adds a border around the image. Thickness is def= ined in px. Color is "#000" by default. |
| filter/noise | [radius=3D0] | Smooths the contours of an image (imagick<=
/code>/ |
| filter/swirl | [degrees=3D60] | Swirls the pixels of the center of an image (gmagick only). degrees defaults=
to 60=C2=B0. |
| resize | {size: [width, height]} | Simple resize filter (provided by LiipImagineBun= dle). |
| colorspace/gray | N/A | Converts an image to grayscale. |
LiipImagineBundle supports additional settings, it is possible to combin= e filters from the list above to the ones provided in LiipImagineBundle or custom ones.
The following filters exist in the Imagine library but are not used in e= Z Platform due to incompatibility:
flatten. Obsolete, images are automatically flattened.
bordercolorborder/widthcolorspace/transparentcolorspacePlease refer to LiipImagineBundle documentation on custom filters. Imagine library documentation may also be useful.