Image Processing

Contao features a powerful image processing system for handling image resizes and creating responsive images. In this section you’ll learn how to use this functionality in your own code and templates.

Image Processing Stack

Under the hood, Contao uses its own standalone library contao/image to generate responsive images. This library is based on imagine/imagine and contao/imagine-svg which do the actual modification of image files. The CoreBundle comes with an ImageFactory and PictureFactory that wrap around those libraries, adapt them to the Contao ecosystem and provide additional features like the ability to use predefined resize configuration. Finally, there are the Studio classes that allow a convenient way to use the factories to generate and output images and metadata for your templates.

Example use case	Component	Abstraction level
Output images in a template	→ Image Studio	high
Resize images with full control over each parameter	→ ImageFactory → PictureFactory	medium
Use the image processing features outside a Contao application	→ contao/image	low to medium
Modify or resize images directly	→ imagine/imagine → contao/imagine‑svg	low

Relationships between the image libraries

Imagine is the PHP Composer package that Contao uses. It abstracts image handling for multiple libraries
ImageMagick, Gmagick or GD are the PHP extensions that enable image processing
Either natively GD or by creating a bridge to the actual tools ImageMagick and GraphicsMagick

sequenceDiagram
    participant Contao as Contao
    participant Imagine as Imagine Composer Package
    participant GD as PHP GD extension

    Contao ->> Imagine: request image operation
    Imagine ->> GD: perform image operation
    GD -->> Imagine: image result
    Imagine -->> Contao: image result

sequenceDiagram
    participant Contao as Contao
    participant Imagine as Imagine Composer Package
    participant Imagick as PHP Imagick extension
    participant IM as ImageMagick software

    Contao ->> Imagine: request image operation
    Imagine ->> Imagick: perform image operation
    Imagick ->> IM: call ImageMagick libraries
    IM -->> Imagick: processed image
    Imagick -->> Imagine: image result
    Imagine -->> Contao: image result

sequenceDiagram
    participant Contao as Contao
    participant Imagine as Imagine Composer Package
    participant Gmagick as PHP Gmagick extension
    participant GM as GraphicsMagick software

    Contao ->> Imagine: request image operation
    Imagine ->> Gmagick: perform image operation
    Gmagick ->> GM: call GraphicsMagick libraries
    GM -->> Gmagick: processed image
    Gmagick -->> Imagine: image result
    Imagine -->> Contao: image result

Templating

Outputting responsive images can be quite a challenging task due its large amount of attributes and parameters. Contao therefore provides an image.html5 (and picture_default.html5) template out of the box. If you are using the Image Studio component you can also profit from its matching figure.html.twig Twig template and macros.

See the templating section for more information.