Filters

1.0 version
Maintained

Filters

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.

Custom filters

You can easily define your own, custom filters to perform any image transformation operations required. Creating a custom filter begins by creating a class that implements the following interface:

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

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

As defined in LoaderInterface, the only required method is one named load, which is provided an instance of ImageInterface and an array of options, and subsequently provides an instance of ImageInterface in return.

The following is a template for creating your own filter. You must provide the implementation for the load method to create a valid filter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
namespace AppBundle\Imagine\Filter\Loader;

use Imagine\Image\ImageInterface;
use Liip\ImagineBundle\Imagine\Filter\Loader\LoaderInterface;

class MyCustomFilter implements LoaderInterface
{
    /**
     * @param ImageInterface $image
     * @param array          $options
     *
     * @return ImageInterface
     */
    public function load(ImageInterface $image, array $options = array())
    {
        /** @todo: implement */
    }
}

After you have finished implementing your custom filter class, it must be defined as a service in the Symfony Service Container and tagged with liip_imagine.filter.loader. To register a our filter, AppBundle\Imagine\Filter\Loader\MyCustomFilter, as my_custom_filter, use the following configuration.

  • YAML
    1
    2
    3
    4
    5
    6
    7
    # app/config/services.yml
    
    services:
        app.filter.my_custom_filter:
            class: AppBundle\Imagine\Filter\Loader\MyCustomFilter
            tags:
                - { name: "liip_imagine.filter.loader", loader: my_custom_filter }
    
  • XML
    1
    2
    3
    4
    5
    <!-- app/config/services.xml -->
    
    <service id="app.filter.my_custom_filter" class="AppBundle\Imagine\Filter\Loader\MyCustomFilter">
        <tag name="liip_imagine.filter.loader" loader="my_custom_filter" />
    </service>
    

Note

For more information on the Service Container, reference the official Symfony Service Container documentation.

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

With a custom controller action it is possible to dynamically modify the configuration that will be applied to the image. Inside the controller you can access FilterManager instance, pass configuration as third parameter of applyFilter method (for example based on information associated with the image or whatever other logic you might want).

A simple example showing how to change the filter configuration dynamically.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
public function filterAction($path, $filter)
{
    if (!$this->cacheManager->isStored($path, $filter)) {
        $binary = $this->dataManager->find($filter, $path);

        $filteredBinary = $this->filterManager->applyFilter($binary, $filter, array(
            'filters' => array(
                'thumbnail' => array(
                    'size' => array(300, 100)
                )
            )
        ));

        $this->cacheManager->store($filteredBinary, $path, $filter);
    }

    return new RedirectResponse($this->cacheManager->resolve($path, $filter), Response::HTTP_MOVED_PERMANENTLY);
}

Tip

The constant Response::HTTP_MOVED_PERMANENTLY was introduced in Symfony 2.4. Developers using older versions of Symfony, please replace the constant by 301.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.