Image variations (image aliases) enable you to define and use different versions of the same image. You generate variations based on filters which modify aspects such as size and proportions, quality or effects.
Image variations are generated with LiipImagineBundle, using the underlying Imagine library from avalanche123. This bundle supports GD (default), Imagick or Gmagick PHP extensions, and enables you to define flexible filters in PHP. Image files are stored using the
IOService, and are completely independent from the Image Field Type. They are generated only once and cleared on demand (e.g. on content removal).
LiipImagineBundle only works on image blobs (no command line tool is needed). See the bundle's documentation to learn more on that topic.
Configuring image variations¶
Custom image variations are defined in
ezplatform.yml or any imported semantic configuration file. The definition is dynamic, so it can be configured per SiteAccess and all the other scopes.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
Each variation name must be unique. It may contain underscores (
_), hyphens (
-) or numbers, but no spaces.
The following parameters are set for each variation:
reference: Name of a reference variation to base the variation on. If set to
~, which means
nullin YAML), the variation will take the original image for reference. It can be any available variation configured in the
ezpublishnamespace, or a
filter_setdefined in the
filters: Array of filter definitions (hashes containing
paramskeys). See possible values below.
If you change image variation properties manually, you need to clear persistence cache:
php bin/console cache:pool:clear <pool_name>
cache.app by default, and
cache.redis when using Redis.
Built-in image variations¶
A few basic image variations are included by default in eZ Platform in the
default_settings.yml config file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Configure image variations¶
LiipImagineBundle supports post-processors on image aliases. You can specify them in image variation configuration:
1 2 3 4 5 6 7 8 9 10
Please refer to post-processor documentation in LiipImagineBundle for details.
Scaling with an eZ Platform filter¶
This configuration defines a
medium image variation that is scaled to a width of 700 px.
1 2 3 4 5 6 7 8 9
Image quality with a liip filter¶
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 variation, in this case
1 2 3 4 5 6 7 8 9 10 11
Notice that the
liip_imagine key is not placed under
image_variations, but at the same level as
Rendering image variations¶
Render within a Twig template¶
Image variations can be called within a Twig template by passing
alias with the parameters:
LiipImagineBundle in your kernel class¶
If you were using ImageMagick, install Imagick or Gmagick PHP extensions and activate the driver in
liip_imagine(see LiipImagineBundle configuration documentation for more information):
1 2 3 4
GD will be used by default if no driver is specified.
You can use the Liip Imagine console tool to clear generated variations.
The first example will clear the image files for the
large variation. The second will clear all the generated variations (be careful), and list the removed files (
The naming scheme change introduced by this feature wasn't enabled by default 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 information can be found on the pull request.
Code injection in image EXIF
Resolving image URLs¶
You can use LiipImagine's
liip:image:cache:resolve script to resolve the path to image variations generated from the original image, with one or more paths as arguments. See LiipImagineBundle documentation for more information.
Note that paths to repository images must be relative to the
var/<site>/storage/images directory, for example:
In addition to filters exposed by LiipImagineBundle, the following are available:
|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 height.|
|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 values. 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=#000]||Adds a border around the image. Thickness is defined in px. Color is "#000" by default.|
|filter/noise||[radius=0]||Smooths the contours of an image (
|filter/swirl||[degrees=60]||Swirls the pixels of the center of the image (
|resize||Simple resize filter (provided by LiipImagineBundle).|
|colorspace/gray||N/A||Converts the image to grayscale.|
LiipImagineBundle supports additional settings, it is possible to combine filters from the list above with the ones provided in LiipImagineBundle or custom ones.
The following filters exist in the Imagine library but are not used in eZ Platform due to incompatibility:
flatten. Obsolete, images are automatically flattened.
Please refer to LiipImagineBundle documentation on custom filters. Imagine library documentation may also be useful.
Setting placeholder generator¶
Placeholder generator enables you to download or use generated image placeholder for any missing image. It might be used when you are working on an existing database and you are not able to download uploaded images to your local development environment because of their large size
PlaceholderAliasGenerator::getVariation method generates placeholder (by delegating it to the implementation of
PlaceholderProvider interface) if original image cannot be resolved and saves it under the original path.
In eZ Platform there are two implementations of
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
\eZ\Bundle\EzPublishCoreBundle\Imagine\PlaceholderProvider\GenericProvider generates placeholder with basic information about original image - example 1.
Generic image example:
Full page example:
|fontpath||n/a||Path to the font file (.ttf). **This option is required.*|
|text||"IMAGE PLACEHOLDER %width%x%height%\n(%id%)"||Text which will be displayed in the image placeholder. %width%, %height%, %id% in it will be replaced with width, height and ID of the original image.|
|fontsize||20||Size of the font in the image placeholder.|
|foreground||#000000||Foreground color of the placeholder.|
|secondary||#CCCCCC||Secondary color of the placeholder.|
|background||#EEEEEE||Background color of the placeholder.|
\eZ\Bundle\EzPublishCoreBundle\Imagine\PlaceholderProvider\RemoteProvider allows you to download placeholders from:
- remote source e.g. http://placekitten.com - example 2
- live version of a site - example 3
Full page example:
|url_pattern||''||URL pattern. %width%, %height%, %id% in it will be replaced with width, height and ID of the original image.|
|timeout||5||Period of time before timeout, measured in seconds.|
Placeholder generation can be configured for each
binary_handler under the
1 2 3 4 5 6
If there is no configuration assigned to
binary_handler name, the placeholder generation will be disabled.
Example 1 - placeholders with basic information about original image
1 2 3 4 5 6 7 8 9 10
Example 2 - placeholders from remote source
1 2 3 4 5 6 7
Example 3 - placeholders from live version of a site
1 2 3 4 5 6 7
You can resize all original images of a chosen Content Type using the
You need to provide the command with:
- identifier of the image Content Type
- identifier of the Field you want to affect
- name of the image variation to apply to the images
ezplatform:images:resize-original <Content Type identifier> <Field identifier> -f <variation name>
ezplatform:images:resize-original photo image -f small_image
Additionally you can provide two parameters:
iteration-countis the number of images to be recreated in a single iteration, to reduce memory use. Default is
useris the identifier of a user with proper permission who will perform the operation (
publish). Default is
This command publishes a new version of each Content item it modifies.
If you use image files with unprintable UTF-8 characters in file names, you may come across a problem with images not displaying.
In that case, run the
ezplatform:images:normalize-path command to normalize them:
Next, clear the cache:
and run the following:
You can store images in the media library as independent Content items of a generic Image Content Type to reuse them across the system. It is achieved by uploading images to an ImageAsset Field Type.
For ImageAsset field to be reused you have to publish it. Only then is notification triggered stating image has been published under the Location and can now be reused. After establishing media library you can create object relations between the main Content item and the image content item being used by it.
To learn more about ImageAsset Field Type and its customization see Field Type Reference.
Handling SVG images¶
Currently, eZ Platform does not allow you to store SVG images by using the Image or ImageAsset Field Type. Until the full support for this MIME type is in place, you can work things around by relying on the File Field Type and implementing a custom extension that lets you display and download files in your templates.
First, you need to add a proper rule in
1 2 3
It will point to the custom controller which will handle the action of downloading SVG file. Below you can find its definition (placed in
app/config/services.yml) and implementation:
1 2 3 4 5 6 7
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
To be able to use a proper link in your templates, you also need a dedicated Twig extension:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
Now you can load SVG files in your templates using generated links and newly created Twig helper: