Description

Image aliases are generated with LiipImagineBundle, using the underlying Imagine library from avalanche123. This bundle supports GD, Imagick or Gmagick PHP extensions, and allows to define flexible filters in PHP. Imagefiles are stored using the the IOService, and are completely independent from ezimage FieldType. They are generated only once and cleared on demand (e.g. content removal).

Configuration

Image variation (aka "Image alias") definition follows the same format as before, in ezpublish.yml or any imported semantic configuration file. It's dynamic, so can be configured per site access and all the other scopes.

# Example
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] }

• reference: Name of a reference variation to base the variation on. If null (or ~, which means null un YAML), the variation will take the original image for reference. It can be any available variation configured in ezpublish namespace, or a filter_set defined in liip_imagine namespace.

• filters: array of filter definitions (hashes containing name and params keys). See possible values below.

Available filters

In addition to filters exposed by LiipImagineBundle, the following are available:

Tip: LiipImagineBundle supports additional settings, it is possible to combine filters from the list above to the ones provided in LiipImagineBundle or custom ones.

 

Examples with filters:

With liip filter

It is now possible to define the jpeg_quality setting. This configuration adds a limit to the image quality using a liip filter.

ezpublish:
    system:
        my_siteaccess:
            image_variations:
                reduced_jpeg:
                    reference: null
                    filters:
liip_imagine:
    driver: imagick
    filter_sets:
        mediumimage:
            jpeg_quality: 50

With ezpublish filter

Using the geometry/scalewidth filter

ezpublish:
    system:
        my_siteaccess:
            image_variations:
                mediumimage:
                    reference: null
                    filters:
                       - geometry/scalewidth:
					       params: [770]

Discarded filters

The following filters have been discarded due to incompatibility:

• flatten. Obsolete, images are automatically flattened.
• bordercolor
• border/width
• colorspace/transparent
• colorspace

Custom filters

Please refer to LiipImagineBundle documentation on custom filters. Imagine library documentation may also be useful.

Post-Processors

LiipImagineBundle supports post-processors on image aliases. It is possible to specify them in image alias configuration:

ezpublish:
    system:
        my_siteaccess:
            image_variations:
                articleimage:
                    reference: null
                    filters:
                        - { name: geometry/scalewidth, params: [770] }
                    post_processors:
                        jpegoptim: {}

Please refer to post-processors documentation in LiipImagineBundle for details.

Drivers

LiipImagineBundle supports GD (default), Imagick and GMagick PHP extensions and only work on image blobs (no command line tool is needed). See the bundle's documentation to learn more on that topic.

Upgrade

• Instantiate LiipImagineBundle in your kernel class

If you were using ImageMagick, please install Imagick or Gmagick PHP extensions and activate the driver in liip_imagine (see LiipImagineBundle configuration documentation for more information):

# ezpublish.yml or config.yml
liip_imagine:
    # Driver can either "imagick", "gmagick" or "gd", depending on the PHP extension you're using.
    driver: imagick

Purging aliases

Starting from the 5.4.3 and 2015.05, eZ Platform handles aliases on its own. It is possible to use the Liip Imagine console tool to clear generated aliases.

$ php ezpublish/console liip:imagine:cache:remove --filters=large
$ php ezpublish/console liip:imagine:cache:remove -v

The first example will clear the image files for the large alias. The second will clear all the generated aliases (be careful), and list the removed files (-v).

Note that the naming scheme change introduced by this feature isn't enabled by default on 5.4.x. An alternative purge process has been implemented, that takes much more time, but is compatible with the existing format. More technical information can be found on the pull-request.