Image manipulation made even easier! Why worry about the creation of your thumbnails when you can easily configure the image formats your design desires? With sfImageTransformExtraPlugin the days of coding transforms are gone. Instead you define formats as a series of transformations provided by the awesome sfImageTransformPlugin.
Instead of changing your business logic when the design requires new formats you only need to change the configuration while the application remains untouched.

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

License

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

caefer: removed all example routes and left only default @sf_image all others are commented

caefer: added class check for sfImageSource classes as set on routes

caefer: adapted tests

Release 1.0.3 - 18/05/2010

This is a bugfix release. Remote image sources depending on their binary structure might not have been able to detect the mime type of. This was caused by getimagesize() seeking when mime information could not be read from the first chunk of data.

caefer: moved default http route upwards to avoid a conflict with the default file route

Release 1.0.1 - 28/04/2010

PLEASE NOTE!
In this release there is a bugfix of the autoboxing feature which requires you to change your thumbnailing.yml if you use transformations like overlay or alphamask.
In this case you have to prefix the overlay and mask parameters with "sfImage|". See http://trac.symfony-project.org/changeset/29292 for an example.

caefer: bugfix: autoboxing of parameters now limited to parameters prefixed with 'className|'

caefer: updated docblock comments for autoboxing related methods

Release 1.0.0 - 26/04/2010

caefer: bugfix: removed forgotten var_dump()s..

caefer: optimised the extension matching and file info code

caefer: reviewed, corrected and completed README

caefer: reviewed and updated some of the default resources used within this plugin

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
sfImageTransformPlugin which enables you to perform
many sophisticated transformations on your images such as resizing, color manipulation, overlays and much much more. It
is not only easy to use but easy to extend as well. Writing your own transformation is a bliss.

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

This is where sfImageTransformExtraPlugin springs into 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 (a URL that you have
full control over). The image itself will be generated on first request and (in production environments) written to the
filesystem.

Automatic mime detection is absolutely necessary!
Of course you can point the font_dir 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](http://www.symfony-project.org/plugins/sfImageTransformPlugin?tab=plugin_readme
"sfImageTransformPlugin README").

The default routes of the plugin expect all thumbails to be called from the relative URL /thumbnails/... So you have
to make sure, that this folder (SF_ROOT_DIR/web/thumbnails) exists and is writable to the web server.

sfImageTransformExtraPlugins uses custom PHP stream wrappers to map your images URLs to the real location of the source images. There are a few sources already available but of course you can easily add your own.

When you develop on symfony chances are that uploaded image files are located in the sf_upload_dir and their
filenames are stored in the database. sfImageTransformExtraPlugin comes with two images source classes that you can use
to work with these files.

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

It doesn't matter where your source images are stored and how you need to receive the filepath/URL you can easily
implement a solution by following two easy steps:

Write a new route

When defining the URL of the new route the only thing you need to care about is the list of parameters. You have to
provide all parameters that are necessary to retrieve the images location.

In the case of a Doctrine model storing the filename of a local file you need to know the model type (i.e.
NewsBulletin), the ID of the object (i.e. 123) and the model attribute or field which stores the filename (i.e. file).
Depending on your requirements you might need different parameters to identify the source.

Once you defined the parameters you can implement the sfImageSource class by implementing sfImageSourceInterface and
barfoo.

If the image source files are stored on the local filesystem accessible to the webserver your need to implement
sfImageSourceLocalAbstract. For all other locations please use sfImageSourceRemote as PHP functions like stat() only
work with local files and therefor need to be faked .

sfImageTransformExtraPlugin provides functionality to cache your generated images so that instead of processing the images from scratch per request they get stored on the local filesystem from where your webserver can serve them statically without even spawning a PHP process.

sfImageTransformExtraPlugin provides a symfony task to check your settings to ensure that caching is working properly.

$ ./symfony help transforms:check-caching
Usage:
symfony transforms:check-caching [--env="..."] [--route-name="..."] application
Arguments:
application The application name
Options:
--env The environment (default: prod)
--route-name The sfImageTransform routename (default: sf_image)
Description:
The transforms:check-caching task performs a series of tests on your project to verify the thumbnail caching to work.
Call it with:
php symfony transforms:check-caching application
Please read the output carefully especially if one or more checks fail.
You can also run the tests for a specific environment by providing the env option. It defaults to prod which in most cases is the only environment you want your cache to be enabled.
php symfony transforms:check-caching application --env=prod
The tasks assumes the default route name sf_image for your thumbnails. If you use a different one you can specify it with the route-name option.
php symfony transforms:check-caching application --route-name=your_thumbnail_route
Please note that the permission checks can not be reliable as they are performed with the system permissions of your current user account while your web server should run with a different user account which might have different priviledges.

Of course you can combine all available attributes. In this case to remove all jpg images that were generated using
the default format (for example if you changed the mimetype of that particular format).

The important thing is the parameters you pass. You are always required to provide a route name (sf_route) and as many of its route parameters as possible.

For the route parameters the same logic applies as in the previous chapter about the symfony task.

The deletion process will iterate over all files recursively and try to match them against the route. You can speed up this process by passing as much known route parameters as possible. The following best practice applies.

DON'T PASS WHOLE OBJECTS! As these can contain fields like slugs that might have changed themselves and could prevent matching of previously generated files. Do pass all route parameters separately.

The above route definition does not define a definite depth for the thumbnail file as the :filepath parameter can include many folders. By setting max_folder_depth to 10 or another number the invalisation process can now use this information to search for generated thumbnail files rather than doing a recursive directory scan.

As you know your application best this is a value that you can set yourself per route.

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.

Image generation is quite expansive in terms of CPU and memory usage. 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. It also maintains the real
filename and does not add a .cache suffix.

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 (depending on
your Apache configuration, however the described behaviour is the default).

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.

sfImageTransformExtraPlugin is fully unit tested with PHPUnit. You can run the test suite like this.