53 users Sign-in to change your status

Christian Schaefer <caefer@ical.ly> WebServices Applications Media

• Homepage
• Repository
• Report a bug
• Download package
• Browse source

Utilising the fantastic sfImageTransformPlugin this plugin provides all means to configure any set of thumbnail formats with all possible transformations in a YAML file. All these configured settings can be applied to any kind of source image using a nice URL schema.

Developers

Name	Status	Email
Christian Schaefer	lead	yl.laci <<ta>> refeac

License

Copyright (c) 2010 Christian Schaefer

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

Releases for sf 1.4

Version	License	API	Released
1.0.12stable	MIT license	1.0.0stable	24/11/2010
1.0.11stable	MIT license	1.0.0stable	22/11/2010
1.0.10stable	MIT license	1.0.0stable	16/08/2010
1.0.9stable	MIT license	1.0.0stable	22/07/2010
1.0.8stable	MIT license	1.0.0stable	22/07/2010
1.0.7stable	MIT license	1.0.0stable	21/07/2010
1.0.6stable	MIT license	1.0.0stable	21/07/2010
1.0.5stable	MIT license	1.0.0stable	24/06/2010
1.0.4stable	MIT license	1.0.0stable	31/05/2010
1.0.3stable	MIT license	1.0.0stable	18/05/2010
1.0.2stable	MIT license	1.0.0stable	12/05/2010
1.0.1stable	MIT license	1.0.0stable	28/04/2010
1.0.0stable	MIT license	1.0.0stable	26/04/2010
0.9.9beta	MIT license	0.9.0beta	13/04/2010
0.9.8beta	MIT license	0.9.0beta	06/04/2010
0.9.7beta	MIT license	0.9.0beta	31/03/2010
0.9.6beta	MIT license	0.9.0beta	25/03/2010
0.9.5beta	MIT license	0.9.0beta	24/03/2010
0.9.4beta	MIT license	0.9.0beta	23/03/2010
0.9.3beta	MIT license	0.9.0beta	21/03/2010
0.9.2beta	MIT license	0.9.0beta	21/03/2010
0.9.1beta	MIT license	0.9.0beta	14/03/2010
0.9.0beta	MIT license	0.9.0beta	14/03/2010

Name	Channel	Version
sfImageTransformPlugin	plugins.symfony-project.org	1.3.0-1.3.2

Join this plugin team

Other releases

Release 1.0.12 - 24/11/2010

Release 1.0.11 - 22/11/2010

Release 1.0.10 - 16/08/2010

Release 1.0.9 - 22/07/2010

Release 1.0.8 - 22/07/2010

Release 1.0.7 - 21/07/2010

Release 1.0.6 - 21/07/2010

Release 1.0.5 - 24/06/2010

Release 1.0.4 - 31/05/2010

Release 1.0.3 - 18/05/2010

Release 1.0.2 - 12/05/2010

Release 1.0.1 - 28/04/2010

Release 1.0.0 - 26/04/2010

Release 0.9.9 - 13/04/2010

Release 0.9.8 - 06/04/2010

Release 0.9.7 - 31/03/2010

Release 0.9.6 - 25/03/2010

Release 0.9.5 - 24/03/2010

Release 0.9.4 - 23/03/2010

Release 0.9.3 - 21/03/2010

Release 0.9.2 - 21/03/2010

Release 0.9.1 - 14/03/2010

Release 0.9.0 - 14/03/2010

> THIS IS HIGHLY PRELIMINARY!

Image manipulation made even easier - sfImageTransformExtraPlugin

Introduction

On a website you ususally find lots of images and a set of formats.

For example let's say a user avatar is always 80x80 PNG while a homepage top image is always 320x140 JPG with round corners.

As it is far too costly to prepare all these different formats by hand there are automated ways to generate them from source images uploaded by a user. One of the best tools for this in the symfony world is the sfImageTransformPlugin which enables you to perform many sophisticated transformations on your images such as resizing, color manipulation, overlays and more.

Using such an automatism means you have to write code and perform all necessary transformation on upload, no matter if the generated files are ever requested. It also means that design changes that also change the formats lead to change of business logic rather than just templates.

This is where sfImageTransformExtraPlugin springs to action as it provides a way to configure formats with multiple transformations. In your templates you only refer to the format by name which results in an SEO friendly image URL. The image itself will be generated on first request and (in production environments) written to the filesystem.

Here are some of the key features:

• Configure image transformation for your thumbnail formats
• Format changes without the need to change code
• Unobstrusive implementation (No need to write code)
• Generating images on request
• Can be run as a web service for a content delivery network (CDN)
• Supporting image file sources stored in databases via Doctrine or Propel, remote files and more
• Full control over the thumbnail URLs
• Generated API documentation
• Unit tested
• Easy to extend

A quick demonstration

Consider the following source image.

Here are just a few examples that were all transformed from the above image.

And of course:

A walk through the configuration of a more complex format

Of course you can chain transformations!

In fact most of the above thumbnails have two transformations applied one for resizing and another for the effect.

Let's see how it works and start with the original again. The format looks like this.

      star0:
        quality:                25  
        mime_type:              image/png
        transformations:        ~

With the following result.

Now let's add a crop transformation to get to the correct dimensions.

      star1:
        quality:                25  
        mime_type:              image/png
        transformations:
          - { adapter: GD, transformation: crop, param: { left: 90, top: 72, width: 120, height: 120 }}

And just to be a bit different we want to rotate.

      star2:
        quality:                25  
        mime_type:              image/png
        transformations:
          - { adapter: GD, transformation: crop, param: { left: 90, top: 72, width: 120, height: 120 }}
          - { adapter: GD, transformation: rotate, param: { angle: 20, background: '#FFFFFF' }}

The blank spots are not what we want so let's crop it again.

      star3:
        quality:                25  
        mime_type:              image/png
        transformations:
          - { adapter: GD, transformation: crop, param: { left: 90, top: 72, width: 120, height: 120 }}
          - { adapter: GD, transformation: rotate, param: { angle: 20, background: '#FFFFFF' }}
          - { adapter: GD, transformation: crop, param: { left: 17, top: 17, width: 120, height: 120 }}

So we are back to the dimensions we wanted. Now we want a watermark on top of it.

      star4:
        quality:                25  
        mime_type:              image/png
        transformations:
          - { adapter: GD, transformation: crop, param: { left: 90, top: 72, width: 120, height: 120 }}
          - { adapter: GD, transformation: rotate, param: { angle: 20, background: '#FFFFFF' }}
          - { adapter: GD, transformation: crop, param: { left: 17, top: 17, width: 120, height: 120 }}
          - { adapter: GD, transformation: overlay, param: { overlay: overlays/logo.png, position: center }}

Of course this is not "Web 2.0" enough yet..

      star5:
        quality:                25  
        mime_type:              image/png
        transformations:
          - { adapter: GD, transformation: crop, param: { left: 90, top: 72, width: 120, height: 120 }}
          - { adapter: GD, transformation: rotate, param: { angle: 20, background: '#FFFFFF' }}
          - { adapter: GD, transformation: crop, param: { left: 17, top: 17, width: 120, height: 120 }}
          - { adapter: GD, transformation: overlay, param: { overlay: overlays/logo.png, position: center }}
          - { adapter: GD, transformation: overlay, param: { overlay: overlays/star_frame.png, position: center }}

Now we want to get rid of the bits that stick out by applying an alpha mask.

      star6:
        quality:                25  
        mime_type:              image/png
        transformations:
          - { adapter: GD, transformation: crop, param: { left: 90, top: 72, width: 120, height: 120 }}
          - { adapter: GD, transformation: rotate, param: { angle: 20, background: '#FFFFFF' }}
          - { adapter: GD, transformation: crop, param: { left: 17, top: 17, width: 120, height: 120 }}
          - { adapter: GD, transformation: overlay, param: { overlay: overlays/logo.png, position: center }}
          - { adapter: GD, transformation: overlay, param: { overlay: overlays/star_frame.png, position: center }}
          - { adapter: GD, transformation: alphaMask, param: { mask: masks/star_mask.gif }}

Done! ;)

How does it work?

The generation process that we designed so far works like this:

1. An HTTP Request is made to a thumbnail
2. All necessary parameters are parsed from the URL
3. The requested source image is found
4. The thumbnail gets generated according to the format specification
5. The thumbnail gets cached (saved to disk)
6. The thumbnail is send out to the user

The thumbnail image is generated on the first request. All succeeding requests are coming from cache (per default the filesystem) and are served by Apache without spawning a PHP process.

The caching mechanism

Image generation is quite expansive in terms of CPU and memory. This is why sfsfImageTransformExtraPlugin by default stores generated images for the production environment on the filesystem. For this the custom cache class sfRawFileCache is used which is basically a copy of sfFileCache but does not prepend the cached file with expire time information but instead saves only the generated image.

You can see the typical lifecycle of a generated image in the following Firebug screenshots.

The image is generated, saved to the filesystem and sent to the requesting browser.

The image is read directly from the filesystem without invoking a PHP process.

Apache automatically informs the browser that the image has not been modified by sending a 304 status.

As you can see the time needed to deliver a generated image after the second request is drastically reduced. (The times will vary on different installations.)

The deletion of generated images use the sfCache interface and can be triggered by a task of a symfony event.

Installation

To install the plugin for a symfony project, the usual process is to use the symfony command line:

$ php symfony plugin:install sfImageTransformExtraPlugin

Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's plugins/ directory.

Activate the plugin in your ProjectConfiguration.class.php.

// /config/ProjectConfiguration.class.php

... $this->enablePlugins(..., 'sfImageTransformPlugin', 'sfImageTransformExtraPlugin'); ...

Enable the generating module in your settings.yml.

// /apps/yourapplication/config/settings.yml
all:
  .settings:
    enabled_modules:        [ ..., sfImageTransformator ]

...

You also need to configure automatic mime detection for sfImageTransformPlugin in your applications app.yml.

// /apps/yourapplication/config/app.yml
all:
  sfImageTransformPlugin:
    mime_type:
      auto_detect:  true
      library:    gd_mime_type #  gd_mime_type (GD), Fileinfo (PECL), MIME_Type (PEAR)
    font_dir:     %SF_PLUGINS_DIR%/sfImageTransformExtraPlugin/data/example-resources/fonts

...

Automatic mime detection is absolutely necessary! Of course you can point the font_fir to your own location containing True Type Fonts.

Clear the cache to enable the autoloading to find the new classes:

$ php symfony cc

Note: The plugin requires sfImageTransformPlugin to be installed as well. The dependencies described there apply as well so please follow the README.

Next you have to configure your routes.

Configuration for local image sources identified by filename

Your image sources lie in a directory accessible to your web server and you want to keep the filenames.

Create a route like the following in your applications routing.yml.

// /apps/yourapplication/config/routing.yml

sf_image: class: sfImageTransformRoute url: /thumbnails/:format/:filepath.:sf_format param: { module: sfImageTransformator, action: index } requirements: format: '[\w_-]+' filepath: '[\w/]+' sf_format: 'gif|png|jpg' sf_method: [ get ] options: image_source: File ...

You can now generate <img /> tags to these images like this.

<?php
echo image_tag(url_for('sf_image_file', array('format' => 'pixelate', 'filepath' => 'logo.png')));

// resulting in: http://localhost/thumbnails/pixelate/logo.png.jpg ?>

Please note that the filepath is expected relative to sf_upload_dir!

Configuration for local image sources linked by a Doctrine or Propel record

Your image sources lie in a directory accessible to your web server and you want to keep the filenames.

Create a route like the following in your applications routing.yml.

// /apps/yourapplication/config/routing.yml
sf_image:
  class: sfImageTransformRoute
  url:   /thumbnails/:type/:format/:path/:slug-:id.:sf_format
  param: { module: sfImageTransformator, action: index, attribute: file }
  requirements:
    format:    '[\w_-]+'
    path:      '[\w/]+'
    slug:      '[\w_-]+'
    id:        '\d+(?:,\d+)?'
    sf_format: 'gif|png|jpg'
    sf_method: [ get ]
  options:
    image_source: Doctrine
    segment_separators: [ '/', '.', '-' ]

...

You can now generate <img /> tags to these images like this.

<?php
echo image_tag(url_for('sf_image_doctrine', array('format' => 'pixelate', 'sf_subject' => $record)));

// resulting in: http://localhost/thumbnails/News/pixelate/01/00/00/mytest-1.jpg ?>

$record in this example is either a Doctrine or Propel record.

Configuration for remote image sources to be read over HTTP

Your image sources lie in a directory accessible to your web server and you want to keep the filenames.

Create a route like the following in your applications routing.yml.

// /apps/yourapplication/config/routing.yml
sf_image:
  class: sfImageTransformRoute
  url:   /thumbnails/sfweb/:format/:filepath.:sf_format
  param: { module: sfImageTransformator, action: index, protocol: http, domain: www.symfony-project.org }
  requirements:
    format:    '[\w_-]+'
    sf_format: http|https
    domain:    '[\w-_.]+'
    filepath:  '[\w/-_.]+'
    sf_format: 'gif|png|jpg'
    sf_method: [ get ]
  options:
    image_source: HTTP

...

You can now generate <img /> tags to these images like this.

<?php
echo image_tag(url_for('sf_image_http', array('format' => 'pixelate', 'filepath' => 'images/symfony-reloaded.png')));

// resulting in: http://localhost/thumbnails/sfweb/pixelate/images/symfony-reloaded.png.jpg ?>

Invalidating generated images

trigger event run task

see also twiggering invalidation when using sfImageTransformExtraPlugin as a web service further down in this document.

Advanced usage:

How can I use static resources like fonts, alpha masks and overlay images?

How can I run sfImageTransformExtraPlugin as a web service?

To run sfImageTransformExtraPlugin as a web service you create a new symfony installation and install the plugin as described in the previous chapter.

You then have to create a configuration file called thumbnailing.yml in your applications config directory with the following contents:

all:
  source_image:
    class: sfImageSourceHTTP
    param:
      url_schema: http://yourhost/%type/%id/%attribute

As the invalidation of the generated images can not be triggered with an event you will have to create a new route that can be called as a trigger.

EXAMPLE

If you serve your generated images from a web service installation you have to prefix the URL with the domain of your service.

<?php echo image_tag('http://your.webservice.url'.url_for(...), array());

How can I use a custom image source?

write a new stream wrapper

How can I configure a transformation that needs an object for a parameter?

prepareParameters()

How can I run the tests?

$ cd /path/to/sfImageTransformExtraPlugin

$ phpunit --tap test/sfImageTransformExtraPluginsTests.php

How can I generate the API documentation?

$ cd /path/to/sfImageTransformExtraPlugin
$ phpdoc ...

How can I use an HTTP cache like Squid, Varnish or Akamai instead of the filesystem?