Symfony Bundle to assist in image manipulation using the imagine library
Symfony Bundle to assist in image manipulation using the imagine library
This bundle provides an image manipulation abstraction toolkit for Symfony-based projects.
Filter Sets: Using any Symfony-supported configuration language (such as YML and XML), you can create filter set definitions that specify transformation routines. These definitions include a set of filters and post-processors, as well as other optional parameters.
Filters: Image transformations are applied using filters. A set of build-in filters are provided by the bundle, implementing the most common transformations; examples include thumbnail, scale, crop, flip, strip, and watermark. For more advances transformations, you can easily create your own custom filters.
Post-Processors: Modification of the resulting binary image file (created from your filters) are handled by post-processors. Examples include JPEG Optim, Moz JPEG, Opti PNG, and PNG Quant. Just like filters you can easily create your own custom post-processors.
Suppose you defined a my_thumb filter set, which can be configured to
perform any number of different transformations. The simplest invocation would
be to pipe the path of your image to the provided imagine_filter Twig
filter.
This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Thanks to the many contributors who have dedicated their time and code to this project.
The standalone PHP Imagine Library is used by this bundle for image transformations.
This package was forked from AvalancheImagineBundle with the goal of making the code more extensible. Reference AvalancheImagineBundle#25 for additional information on the reasoning for this fork.
Using this package is similar to all Symfony bundles. The following steps must be performed
Detailed setup instructions can be found in the installation chapter of the documentation.
Detailed information on all available configuration options can be found in the configuration chapter of the documentation.
Generally, this bundle works by applying filter sets to images from inside
a template. Your filter sets are defined within the application's configuration
file (often app/config/config.yml) and are comprised of a collection of
filters, post-processors, and other optional parameters.
We'll learn more about post-processors and other available parameters later, but for now lets focus on how to define a simple filter set comprised of a few filters.
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 boilerplate in your configuration file.
# 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:
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.
…
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 (in this example, 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.
Note: A filter set can have any number of filters defined for it. Simple transformations may only require a single filter while complex transformations can have an unlimited number of filters defined for them.
There are a number of additional filters,
but for now you can use your newly defined my_thumb filter set immediately
within a template.
For Twig-based template, use:
Or, for PHP-based template, use:
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.
Note:
*Using the dev environment you might find that images are not properly
rendered via the template helper. This is often caused by having
intercept_redirect enabled in your application configuration. To ensure
images are rendered, it is strongly suggested to disable this option:
# app/config/config_dev.yml
web_profiler :
intercept_redirects : false
Sometime, 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.
For Twig-based template, use:
{% set runtimeConfig = {"thumbnail": {"size": [50, 50] }} %}
Or, for PHP-based template, use:
<?php
$runtimeConfig = array(
"thumbnail" => array(
"size" => array(50, 50)
)
);
?>
filter('/relative/path/to/image.jpg', 'my_thumb', $runtimeConfig) ?>" />
Sometime you need to resolve the image path returned by this bundle for a filtered image. This can easily be achieved using Symfony's console binary or programmatically from within a controller or other piece of code.
You can resolve an image URL using the console command
liip:imagine:cache:resolve. The only required argument is one or more
relative image paths (which must be separated by a space).
$ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg relative/path/to/image2.jpg
Additionally, you can use the --filter option to specify which filter
you want to resolve for (if the --filter option is omitted, all
available filters will be resolved).
$ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg --filter=my_thumb
You can resolve the image URL in your code using the getBrowserPath
method of the liip_imagine.cache.manager service. Assuming you already
have the service assigned to a variable called $imagineCacheManager,
you would run:
$imagineCacheManager->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb');
Often, you need to perform this operation in a controller. Assuming your
controller inherits from the base Symfony controller, you can take advantage
of the inherited get method to request the liip_imagine.cache.manager
service, from which you can call getBrowserPath on a relative image
path to get its resolved location.
/** @var CacheManager */
$imagineCacheManager = $this->get('liip_imagine.cache.manager');
/** @var string */
$resolvedPath = $imagineCacheManager->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb');
This bundle provides a set of built-in filters and you may easily define your own filters as well. Reference the filters chapter from our documentation.
If you need to use your defined "filter sets" from within your controller, you can fetch this bundle's FilterService from the service container to do the heavy lifting for you.
…
By default, Symfony's web/ directory is registered as a data root to load
assets from. For many installations this will be sufficient, but sometime you
may need to load images from other locations. To do this, you must set the
data_root parameter in your configuration (often located at app/config/config.yml).
liip_imagine:
loaders:
default:
filesystem:
data_root: /path/to/source/images/dir
As of vers
No open issues yet, or sync has not completed.