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

AvalancheImagineBundle

by avalanche123

Image manipulation using Imagine and Twig Filters

Deprecated

This project is no longer actively maintained, please find one of the populate forks. Thanks!

AvalancheImagineBundle

This bundle provides easy image manipulation support for Symfony2. For example,
with this bundle, the following is possible:

<img src="{{ '/relative/path/to/image.jpg' | apply_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".

Installation

Installation is a quick 3 step process:

  1. Download AvalancheImagineBundle using composer
  2. Enable the Bundle
  3. Configure your application's config.yml

Step 1: Download AvalancheImagineBundle using composer

Add AvalancheImagineBundle in your composer.json:

composer require avalanche123/imagine-bundle

Composer will install the bundle to your project's vendor/avalanche123/imagine-bundle directory.

Step 2: Enable the bundle

Enable the bundle in the kernel:

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Avalanche\Bundle\ImagineBundle\AvalancheImagineBundle(),
    );
}

Step3: Register the bundle's routes

Finally, add the following to your routing file:

# app/config/routing.yml

_imagine:
    resource: .
    type:     imagine

Congratulations! You're ready to rock your images!

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

avalanche_imagine:
    filters:
        my_thumb:
            type:    thumbnail
            options: { size: [120, 90], mode: outbound }

You can also change the quality and the format you want to use to save our image :

# app/config/config.yml

avalanche_imagine:
    filters:
        my_thumb:
            type:    thumbnail
            options: { size: [120, 90], mode: outbound, quality: 100, format: png }

You've now defined a filter 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' | apply_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 bundle 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.

HTTP Cache Headers

  • cache_type - one of the three values: false, public or private.
    Setting false disables caching i.e. sets Cache-Control: no-cache.

    default: false

  • cache_expires - Sets time when cache expires. Uses format that the DateTime
    parser understands. Expression will be prefixed with + so expression
    should be like 2 weeks. Used only when cache_type equal public or private.

    default: 1 day

Configuration example:

# app/config/config.yml

avalanche_imagine:
    filters:
        my_thumb:
            type:    thumbnail
            options: { size: [120, 90], mode: outbound, cache_type: public, cache_expires: 2 weeks }

Cache headers are set only for first request when image is generated.
To solve this issue you should add additional configuration for your web server.
Example for apache web server:
apache
<IfModule mod_expires.c>
<Directory "/path/to/web/media/cache">
ExpiresActive On
ExpiresDefault "access plus 2 weeks"
</Directory>
</IfModule>

Configuration

The default configuration for the bundle looks like this:

avalanche_imagine:
    source_root:  %kernel.root_dir%/../web
    web_root:     %kernel.root_dir%/../web
    cache_prefix: media/cache
    driver:       gd
    filters:      []

There are several configuration options available:

  • source_root - can be set to the absolute path to your original image's
    directory. This option allows you to store the original image in a
    different location from the web root. Under this root the images will
    be looked for in the same relative path specified in the apply_filter
    template filter.

    default: %kernel.root_dir%/../web

  • web_root - must be the absolute path to you application's web root. This
    is used to determine where to put generated image files, so that apache
    will pick them up before handing the request to Symfony2 next time they
    are requested.

    default: %kernel.root_dir%/../web

  • cache_prefix - this is also used in the path for image generation, so
    as to not clutter your web root with cached images. For example by default,
    the images would be written to the web/media/cache/ directory.

    default: media/cache

  • driver - one of the three drivers: gd, imagick, gmagick

    default: gd

  • filters - specify the filters that you want to define and use

Each filter that you specify have the following options:

  • type - determine the type of filter to be used, refer to Filters section for more information
  • options - options that should be passed to the specific filter type
  • path - override the global cache_prefix and replace it with this path
  • source_root - override the global source_root and replace it with this path

Built-in Filters

Currently, this bundles comes with just one built-in filter: thumbnail.

Thumbnail

The thumbnail filter, as the name implies, performs a thumbnail transformation
on your image. The configuration looks like this:

filters:
    my_thumb:
        type:    thumbnail
        options: { size: [120, 90], mode: outbound }

The mode can be either outbound or inset.

Resize

The resize filter may be used to simply change the width and height of an
image irrespective of its proportions.

Consider the following configuration example, which defines two filters to alter
an image to an exact screen resolution:

avalanche_imagine:
    filters:
        cga:
            type:    resize
            options: { size: [320, 200] }
        wuxga:
            type:    resize
            options: { size: [1920, 1200] }

RelativeResize

The relative_resize filter may be used to heighten, widen, increase or
scale an image with respect to its existing dimensions. These options directly
correspond to methods on Imagine's BoxInterface.

Given an input image sized 50x40 (width, height), consider the following
annotated configuration examples:

avalanche_imagine:
    filters:
        heighten:
            type:    relative_resize
            options: { heighten: 60 } # Transforms 50x40 to 75x60
        widen:
            type:    relative_resize
            options: { widen: 32 }    # Transforms 50x40 to 40x32
        increase:
            type:    relative_resize
            options: { increase: 10 } # Transforms 50x40 to 60x50
        scale:
            type:    relative_resize
            options: { scale: 2.5 }   # Transforms 50x40 to 125x100

If you prefer using Imagine without a filter configuration, the RelativeResize
class may be used directly.

Paste

The paste filter pastes an image into your image.

avalanche_imagine:
    filters:
        paste:
            type:        paste
            options:
                image:   %kernel.root_dir%/Resources/image.png  # path to image
                x:       right                                  # [left|right|center] or integer
                y:       bottom                                 # [top|bottom|middle] or integer

Chain

With chain filter you can apply some filters on your image.
You can quite simply create a watermark filter:

avalanche_imagine:
    filters:
        watermark:
            type:                chain
            options:
                filters:
                    thumbnail:                                          # filter type
                        size:    [100, 100]                             # filter options
                        mode:    outbound
                    paste:
                        image:   %kernel.root_dir%/Resources/image.png
                        x:       right
                        y:       bottom

Crop

The crop filter crop an image with start coordinate, and size dimension.

avalanche_imagine:
    filters:
        crop:
            type   : crop
            options: { start: [0, 0], size: [100, 100] } #crop image with 100x100 square box

Load your Custom Filters

The ImagineBundle allows you to load your own custom filter classes. The only
requirement is that each filter loader implement the following interface:

Avalanche\Bundle\ImagineBundle\Imagine\Filter\Loader\LoaderInterface

To tell the bundle about your new filter loader, register it in the service
container and apply the following tag to it (example here in XML):

<tag name="imagine.filter.loader" filter="my_custom_filter" />

For more information on the service container, see the Symfony2
Service Container documentation.

You can now reference and use your custom filter when defining filters you'd
like to apply in your configuration:

filters:
    my_special_filter:
        type:    my_custom_filter
        options: { }

For an example of a filter loader implementation, refer to
Avalanche\Bundle\ImagineBundle\Imagine\Filter\Loader\ThumbnailFilterLoader.

Caveats

If you are generating your image names from multiple parts in a Twig template,
please be aware that Twig applies filters before concatenation, so

<img src="{{ '/relative/path/to/' ~ some_variable ~ '.jpg' | apply_filter('my_thumb') }}" />

will apply your filter to '.jpg', and then concatenate the result to
'/relative/path/to/' and some_variable. So the correct invocation would be

<img src="{{ ('/relative/path/to/' ~ some_variable ~ '.jpg') | apply_filter('my_thumb') }}" />

Using as a service

You can use ImagineBundle as a service and resolve the cached image path.
php
$avalancheService = $this->get('imagine.cache.path.resolver');

Then, call the getBrowserPath and pass the original image webpath and the filter you want to use
php
$cachedImage = $avalancheService->getBrowserPath($object->getWebPath(), 'my_thumb');

And also use ImagineBundle as a service and create the cache image from controller.
php
$cacheManager = $this->get('imagine.cache.manager');
$cachedPath = $cacheManager->cacheImage($this->getRequest()->getBaseUrl(), '/images/picture1.jpg', 'my_filter');

Copyright (c) 2004-2013 Bulat Shakirzyanov

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.
  • Merge pull request #198 from FlashBlack/develop
    By avalanche123, 2 years ago
  • Merge pull request #193 from rdohms/patch-1
    By avalanche123, 2 years ago
  • Update CachePathResolver.php
    By , 2 years ago
  • Update imagine.xml
    By FlashBlack, 2 years ago
  • Update README.md
    By avalanche123, 3 years ago
  • Update README.md
    By rdohms, 3 years ago
  • Merge pull request #191 from JavierJimenez/develop
    By avalanche123, 3 years ago
  • Update README.md
    By , 3 years ago
  • Merge pull request #145 from Bup3/develop
    By avalanche123, 3 years ago
  • Merge pull request #146 from caravane/develop
    By avalanche123, 3 years ago
  • Merge pull request #190 from ChMat/develop
    By avalanche123, 3 years ago
  • Add permissions configuration setting to set specific chmod value on generated images.
    By ChMat, 3 years ago
  • Merge pull request #181 from athlan/develop
    By avalanche123, 3 years ago
  • Update composer.json
    By , 3 years ago
  • Merge branch 'feature-webroot-per-filter' into develop
    By athlan, 3 years ago
  • can be overrided in filter options.
    By athlan, 3 years ago
  • Merge pull request #169 from josaliba/patch-1
    By avalanche123, 3 years ago
  • fixed link to imagine library
    By , 3 years ago
  • Merge pull request #160 from straube/develop
    By avalanche123, 4 years ago
  • Merge pull request #153 from yanickouellet/merge-recursive
    By avalanche123, 4 years ago
  • Fixing bug related to concurrency in dir creation. See PHP bug #35326.
    By Gustavo Straube, 4 years ago
  • Fixing bug in cached content verifying (switching from 'file_exists' to 'is_file').
    By Gustavo Straube, 4 years ago
  • Merge recursively the config
    By yanickouellet, 4 years ago
  • Merge branch 'develop'
    By , 4 years ago
  • Check if $cached is not a directory to avoid error on unlink
    By EricGrivilers, 4 years ago
  • Fixed bug with symfony 2.3
    By Bup3, 4 years ago
  • Merge pull request #137 from ejsidisi/develop
    By avalanche123, 4 years ago
  • Merge pull request #138 from kbond/patch-1
    By avalanche123, 4 years ago
  • added missing use statement
    By kbond, 4 years ago
  • Update composer.json
    By , 4 years ago