Developed with love by KnpLabs Hire us for your project!
553

LiipImagineBundle

by liip

Symfony2 Bundle to assist in imagine manipulation using the imagine library

LiipImagineBundle

This bundle is a fork of AvalancheImagineBundle which provides easy image
manipulation support for Symfony2. The goal of the fork is to make the
code more extensible and as a result applicable for more use cases.

For more details on the reason for the fork see:
https://github.com/avalanche123/AvalancheImagineBundle/pull/25

For example with this bundle the following is possible:

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

This will perform the transformation called thumbnail, which you can define
to do a number of different things, such as resizing, cropping, drawing,
masking, etc.

This bundle integrates the standalone PHP "Imagine library".

Build Status
Total Downloads
Latest Stable Version

Installation

In case you are not sure how to install this bundle, see the installation instructions.

Configuration

After installing the bundle, make sure you add this route to your routing:

# app/config/routing.yml

_liip_imagine:
    resource: "@LiipImagineBundle/Resources/config/routing.xml"

For a complete configuration drill-down see the respective chapter in the documentation.

Basic Usage

This bundle works by configuring a set of filters and then applying those
filters to images inside a template So, start by creating some sort of filter
that you need to apply somewhere in your application. For example, suppose
you want to thumbnail an image to a size of 120x90 pixels:

# app/config/config.yml

liip_imagine:
    resolvers:
       default:
          web_path: ~

    filter_sets:
        cache: ~
        my_thumb:
            quality: 75
            filters:
                thumbnail: { size: [120, 90], mode: outbound }

You've now defined a filter set called my_thumb that performs a thumbnail transformation.
We'll learn more about available transformations later, but for now, this
new filter can be used immediately in a template:

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

Or if you're using PHP templates:

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

Behind the scenes, the bundles applies the filter(s) to the image on the first
request and then caches the image to a similar path. On the next request,
the cached image would be served directly from the file system.

In this example, the final rendered path would be something like
/media/cache/my_thumb/relative/path/to/image.jpg. This is where Imagine
would save the filtered image file.

You can also pass some options at runtime:

{% set runtimeConfig = {"thumbnail": {"size": [50, 50] }} %}
<img src="{{ '/relative/path/to/image.jpg' | imagine_filter('my_thumb', runtimeConfig) }}" />

Or if you're using PHP templates:

<?php
$runtimeConfig = array(
    "thumbnail" => array(
        "size" => array(50, 50)
    )
);
?>

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

Also you can resolve image url from console:
jinja
app/console liip:imagine:cache:resolve relative/path/to/image.jpg relative/path/to/image2.jpg --filters=my_thumb --filters=thumbnail_default

Where only paths required parameter. They are separated by space. If you omit filters option will be applied all available filters.

If you need to access filtered image URL in your controller:

$this->get('liip_imagine.cache.manager')->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb', true),

In this case, the final rendered path would contain some random data in the path
/media/cache/my_thumb/S8rrlhhQ/relative/path/to/image.jpg. This is where Imagine
would save the filtered image file.

Note: Using the dev environment you might find that the images are not properly rendered when
using the template helper. This is likely caused by having intercept_redirect enabled in your
application configuration. To ensure that the images are rendered disable this option:

web_profiler:
    intercept_redirects: false

Filters

The LiipImagineBundle provides a set of built-in filters.
You may easily roll your own filter, see the filters chapter in the documentation.

Using the controller as a service

If you need to use the filters in a controller, you can just load ImagineController.php controller as a service and handle the response:

class MyController extends Controller
{
    public function indexAction()
    {
        // RedirectResponse object
        $imagemanagerResponse = $this->container
            ->get('liip_imagine.controller')
                ->filterAction(
                    $this->request          // http request
                    'uploads/foo.jpg',      // original image you want to apply a filter to
                    'my_thumb'              // filter defined in config.yml
        );

        // string to put directly in the "src" of the tag <img>
        $cacheManager = $this->container->get('liip_imagine.cache.manager');
        $srcPath = $cacheManager->getBrowserPath('uploads/foo.jpg', 'my_thumb');

        // ..
    }
}

In case you need to add more logic the recommended solution is to either extend ImagineController.php controller or take the code from that controller as a basis for your own controller.

If you want to use the service in another service, you have to simulate a new request:

$imagemanagerResponse = $this->container
    ->get('liip_imagine.controller')
        ->filterAction($this->container->get('request'), 'uploads/foo.jpg', 'my_thumb');

Outside the web root

When your setup requires your source images to live outside the web root, or if that's just the way you roll,
you have to set your loader's parameter data_root in the config.yml with the absolute path where your source images are
located:

liip_imagine:
    loaders:
        default:
            filesystem:
                data_root: /path/to/source/images/dir

Afterwards, you need to grant read access on Apache to access the images source directory. For achieving it you have
to add the following directive to your project's vhost file:

<VirtualHost *:80>
    <!-- Rest of directives like DocumentRoot or ServerName -->

    Alias /FavouriteAlias /path/to/source/images/dir
    <Directory "/path/to/source/images/dir">
        AllowOverride None
        Allow from All
    </Directory>
</VirtualHost>

Another way would be placing the directive in a separate file living inside your project. For instance,
you can create a file app/config/apache/photos.xml and add to the project's vhost the following directive:

<VirtualHost *:80>
    <!-- Rest of directives like DocumentRoot or ServerName -->

    Include "/path/to/your/project/app/config/apache/photos.xml"
</VirtualHost>

This way you keep the file along with your code and you are able to change your files directory access easily or create
different environment-dependant configuration files.

Either way, once you have granted access on Apache to read the data_root files, the relative path of an image with this
absolute path /path/to/source/images/dir/logo.png must be /FavouriteAlias/logo.png to be readable.

Documentation

For more detailed information about the features of this bundle, please refer to the documentation.

Copyright (c) 2010-2011 Liip

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
liip_imagine:
driver: gd
web_root: %kernel.root_dir%/../web
data_root: %liip_imagine.web_root%
cache_mkdir_mode: 511
cache_prefix: /media/cache
cache: web_path
cache_base_path:
cache_clearer: true
data_loader: filesystem
controller_action: liip_imagine.controller:filterAction
formats: []
filter_sets:

# Prototype
name:
path: ~
quality: 100
format: ~
cache: ~
data_loader: ~
controller_action: ~
route:

# Prototype
name: []
filters:

# Prototype
name: []
  • Merge pull request #567 from adam187/option-resolver-is-defined
    By makasim, 2 years ago
  • use isDefined method for OptionsResolver instead of isKnown
    By adam187, 2 years ago
  • Merge pull request #565 from digitalkaoz/patch-2
    By makasim, 2 years ago
  • Update CacheResolver.php
    By digitalkaoz, 2 years ago
  • fix invalid in_array
    By digitalkaoz, 2 years ago
  • Merge pull request #473 from patrickli/new-quality-options
    By makasim, 2 years ago
  • Add unit tests
    By patrickli, 2 years ago
  • Add documentation about the new options
    By patrickli, 2 years ago
  • Add support for jpeg_quality, png_compression_level and png_compression_filter options
    By patrickli, 2 years ago
  • typo fix
    By lsmith77, 2 years ago
  • point to symfony.com for the docs
    By lsmith77, 2 years ago
  • Merge pull request #559 from javiereguiluz/patch-1
    By makasim, 2 years ago
  • Add a short introductory paragraph about the bundle
    By javiereguiluz, 2 years ago
  • Merge pull request #556 from Spawnrad/patch-1
    By makasim, 2 years ago
  • Update Filters.rst
    By , 2 years ago
  • Merge pull request #554 from javiereguiluz/fix_internal_links
    By makasim, 2 years ago
  • Fixed the syntax of the internal doc links
    By javiereguiluz, 2 years ago
  • Merge pull request #551 from Khez/master
    By makasim, 2 years ago
  • Updated README.md to point to new .rst doc files
    By Cristian Lupu, 2 years ago
  • Merge pull request #550 from erivello/master
    By makasim, 2 years ago
  • fix typo on readme file
    By erivello, 2 years ago
  • Merge pull request #545 from javiereguiluz/transform_md_doc_to_rest
    By lsmith77, 2 years ago
  • Fixed a minor syntax issue
    By javiereguiluz, 2 years ago
  • Switched the documentation from Markdown to ReStructuredText
    By javiereguiluz, 2 years ago
  • Merge pull request #544 from wodka/patch-1
    By makasim, 2 years ago
  • Fix Filter Documentation
    By wodka, 2 years ago
  • Merge pull request #503 from wodka/master
    By makasim, 2 years ago
  • * implement interlace filter
    By wodka, 2 years ago
  • Merge pull request #543 from mbiagetti/master
    By lsmith77, 2 years ago
  • Update the filter_sets Documentation about removed configurations:
    By mbiagetti, 2 years ago