Filters

Edit this page

Filters perform image transformation operations. While some filter set definitions may only require a single filter, more complex definitions often require many filters. Any number of filters can be chained to achieve the desired result.

Tip

You may need to define your own filter to meet your application's specific requirements. Reference the custom filters section for implementation details.

Built-in filters

A number of built-in filters are provided to fulfill the majority of common use-cases.

Custom filters

You can write your own filters to perform any image transformation operations. Custom filters need to implement the filter LoaderInterface (not to be confused with the data loader interface in the Liip\ImagineBundle\Binary\Loader namespace):

1
2
3
4
5
6
namespace Liip\ImagineBundle\Imagine\Filter\Loader;

interface LoaderInterface
{
    public function load(ImageInterface $image, array $options = []);
}

The LoaderInterface has the method load, which is provided an instance of ImageInterface and an array of options. It must return an ImageInterface.

Register it: automatically

By default, your filter will be automatically registered as it implements the LoaderInterface.

You will be able to reference and use your custom filter when defining filter sets in your configuration by using its Fully Qualified Class Name.

Register it: manually

If you want to give it a different name you need to configure a service and tag it liip_imagine.filter.loader.

To register a filter App\Service\MyCustomFilter as my_custom_filter, use the following configuration:

1
2
3
4
5
6
7
# app/config/services.yml

services:
    app.filter.my_custom_filter:
        class: App\Service\MyCustomFilter
        tags:
            - { name: "liip_imagine.filter.loader", loader: my_custom_filter }

You can now reference and use your custom filter when defining filter sets in your configuration:

1
2
3
4
5
6
7
# app/config/config.yml

liip_imagine:
    filter_sets:
        my_special_style:
            filters:
                my_custom_filter: { }

Dynamic filters

It is possible to dynamically modify the configuration that will be applied to the image, by passing configuration as third parameter to applyFilter:

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
namespace App\Service;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Liip\ImagineBundle\Imagine\Cache\CacheManager;
use Liip\ImagineBundle\Imagine\Data\DataManager;
use Liip\ImagineBundle\Imagine\Filter\FilterManager;

class ImageService
{
    private $cacheManager;
    private $dataManager;
    private $filterManager;

    public function __construct(CacheManager $cacheManager, DataManager $dataManager, FilterManager $filterManager) {
        $this->cacheManager  = $cacheManager;
        $this->dataManager   = $dataManager;
        $this->filterManager = $filterManager;
    }

    public function filter(int $width, int $height) {
        $filter = '...'; // Name of the `filter_set` in `config/packages/liip_imagine.yaml`
        $path = '...'; // Path of the image, relative to `/public/`

        if (!$this->cacheManager->isStored($path, $filter)) {
            $binary = $this->dataManager->find($filter, $path);

            $filteredBinary = $this->filterManager->applyFilter($binary, $filter, [
                'filters' => [
                    'thumbnail' => [
                        'size' => [$width, $height]
                    ]
                ]
            ]);

            $this->cacheManager->store($filteredBinary, $path, $filter);
        }
        return new RedirectResponse($this->cacheManager->resolve($path, $filter), Response::HTTP_MOVED_PERMANENTLY);
    }
}
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version