Basic Usage

Create Thumbnails

Before we get started, there is a small amount of configuration needed to ensure our data loaders and cache-resolvers operate correctly. Use the following configuration boilerplate.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# app/config/config.yml

liip_imagine:

    # configure resolvers
    resolvers:

        # setup the default resolver
        default:

            # use the default web path
            web_path: ~

    # your filter sets are defined here
    filter_sets:

        # use the default cache configuration
        cache: ~

With the basic configuration in place, we'll start with an example that fulfills a common use-case: creating thumbnails. Lets assume we want the resulting thumbnails to have the following transformations applied to them:

• Scale and crop the image to 120x90px.
• Add a 2px black border to the scaled image.
• Adjust the image quality to 75.

Adding onto our boilerplate from above, we need to define a filter set (which we'll name my_thumb) with two filters configured: the thumbnail and background filters.

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

# app/config/config.yml

liip_imagine:
    resolvers:
        default:
            web_path: ~

    filter_sets:
        cache: ~

        # the name of the "filter set"
        my_thumb:

            # adjust the image quality to 75%
            quality: 75

            # list of transformations to apply (the "filters")
            filters:

                # create a thumbnail: set size to 120x90 and use the "outbound" mode
                # to crop the image when the size ratio of the input differs
                thumbnail: { size: [120, 90], mode: outbound }

                # create a 2px black border: center the thumbnail on a black background
                # 4px larger to create a 2px border around the final image
                background: { size: [124, 94], position: center, color: '#000000' }

You've now created a filter set called my_thumb that performs a thumbnail transformation. The thumbnail filter sizes the image to the desired width and height (120x90px), and its mode: outbound option causes the resulting image to be cropped if the input ratio differs. The background filter results in a 2px black border by creating a black canvas 124x94px in size, and positioning the thumbnail at its center.

There are a number of additional filters, but for now you can use your newly defined my_thumb filter set immediately within a template.

1

<img src="{{ asset('/relative/path/to/image.jpg') | imagine_filter('my_thumb') }}" />

1

<img src="<?php echo $this['imagine']->filter('/relative/path/to/image.jpg', 'my_thumb') ?>" />

Behind the scenes, the bundle applies the filter(s) to the image on-the-fly when the first page request is served. The transformed image is then cached for subsequent requests. The final cached image path would be similar to /media/cache/my_thumb/relative/path/to/image.jpg.

1
2
3
4

# app/config/config_dev.yml

web_profiler:
    intercept_redirects: false

Runtime Options

Sometimes, you may have a filter defined that fulfills 99% of your usage scenarios. Instead of defining a new filter for the erroneous 1% of cases, you may instead choose to alter the behavior of a filter at runtime by passing the template helper an options array.

1
2
3

{% set runtimeConfig = {"thumbnail": {"size": [50, 50] }} %}

<img src="{{ asset('/relative/path/to/image.jpg') | imagine_filter('my_thumb', runtimeConfig) }}" />

1
2
3
4
5
6
7
8
9

<?php
$runtimeConfig = [
    "thumbnail" => [
        "size" => [50, 50]
    ]
];
?>

<img src="<?php $this['imagine']->filter('/relative/path/to/image.jpg', 'my_thumb', $runtimeConfig) ?>" />

Path Resolution

Sometimes you need to resolve the image path returned by this bundle for a filtered image. This can be achieved using Symfony's console binary or programmatically from within a controller or other piece of code.

1

$ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg relative/path/to/image2.jpg

1

$ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg --filters=my_thumb

1

$imagineCacheManager->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?php

namespace App\Controller;

use Liip\ImagineBundle\Imagine\Cache\CacheManager;

class YourController
{
    public function yourControllerMethod(CacheManager $imagineCacheManager)
    {
        /** @var string */
        $resolvedPath = $imagineCacheManager->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb');

        // ...
    }
}

WebP image format

The WebP format better optimizes the quality and size of the compressed image compared to JPEG and PNG. Google strongly recommends using this format.

1
2
3
4
5

# app/config/config.yml

liip_imagine:
    default_filter_set_settings:
        format: webp

1
2
3
4
5
6
7
8
9
10
11
12

# app/config/config.yml

liip_imagine:
    # configure webp
    webp:
        generate: true

    # example filter
    filter_sets:
        thumbnail_web_path:
            filters:
                thumbnail: { size: [223, 223], mode: inset }

1
2
3
4
5
6
7

# app/config/security.yml

security:
    firewalls:
        image_resolver:
            pattern: ^/media/cache/resolve
            security: false

1
2
3
4
5

# app/config/config.yml

liip_imagine:
    controller:
        redirect_response_code: 302

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# app/config/config.yml

liip_imagine:
    filter_sets:
        my_thumb_jpeg:
            format: jpeg
            quality: 80
            filters:
                thumbnail: { size: [223, 223], mode: inset }
        my_thumb_webp:
            format: webp
            quality: 100
            filters:
                thumbnail: { size: [223, 223], mode: inset }

1
2
3
4
5

<picture>
  <source srcset="{{ '/relative/path/to/image.jpg' | imagine_filter('my_thumb_webp') }}" type="image/webp">
  <source srcset="{{ '/relative/path/to/image.jpg' | imagine_filter('my_thumb_jpeg') }}" type="image/jpeg">
  <img src="{{ '/relative/path/to/image.jpg' | imagine_filter('my_thumb_jpeg') }}" alt="Alt Text!">
</picture>