sfThumbnailPlugin - 1.5.1

symfony thumbnail generation support.

You are currently browsing
the website for symfony 1

Visit the Symfony2 website

« Back to the Plugins Home


Forgot your password?
Create an account



advanced search
Information Readme Releases Changelog Contribute
Show source | Show as Markdown

sfThumbnailPlugin plugin

The sfThumbnailPlugin creates thumbnails from images. It relies on your choice of the [GD] or http://www.imagemagick.org ImageMagick libraries.


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

$ symfony plugin-install http://plugins.symfony-project.com/sfThumbnailPlugin

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.

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

$ php symfony cc

You're done.

Note: If the GD library is not activated, you might have to uncomment the related line in your php.ini and restart your web server to enable PHP image handling functions.

Note: To use !ImageMagick, you'll need to download and install the binaries from http://www.imagemagick.org.


The plugin contains three classes, sfThumbnail, sfGDAdapter and sfImageMagickAdapter. Available methods are:

// Initialize the thumbnail attributes
__construct($maxWidth = null, $maxHeight = null, $scale = true, $inflate = true, $quality = 75, $adapterClass = null, $adapterOptions = array())

// Load image file from a file system

// Load image file from a string (GD adapter only, currently)
loadData($imageString, $mimeType)

// Save the thumbnail to a file
save($thumbFile, $targetMime = null)

Supported GD image types are 'image/jpeg', 'image/png' and 'image/gif'.

!ImageMagick supports over 100 types.

Note that the $quality setting only applies to JPEG images.


Creating a thumbnail from an existing image file

The process of creating a thumbnail from an existing image file is pretty straightforward.

First, you must initialize a new sfThumbnail object with two parameters: the maximum width and height of the desired thumbnail.

// Initialize the object for 150x150 thumbnails
$thumbnail = new sfThumbnail(150, 150);

Then, specify a file path to the image to reduce to the loadFile() method.

// Load the image to reduce

Finally, ask the thumbnail object to save the thumbnail. You must provide a file path. Optionally, if you don't want the thumbnail to use the same mime type as the source image, you can specify a mime type as the second parameter.

// Save the thumbnail
$thumbnail->save('/path/to/thumbnail/file.jpg', 'image/jpg');

Both the source and destination file paths must be absolute paths in your filesystem. To store files under a symfony project directory, make sure you use the directory constants, accessed by sfConfig::get().

Creating a thumbnail for an uploaded file

If you upload images, you might need to create thumbnails of each uploaded file. For instance, to save a thumbnail of maximum size 150x150px at the same time as the uploaded image, the form handling action can look like:

public function executeUpload()
  // Retrieve the name of the uploaded file
  $fileName = $this->getRequest()->getFileName('file');

  // Create the thumbnail
  $thumbnail = new sfThumbnail(150, 150);
  $thumbnail->save(sfConfig::get('sf_upload_dir').'/thumbnail/'.$fileName, 'image/png');

  // Move the uploaded file to the 'uploads' directory
  $this->getRequest()->moveFile('file', sfConfig::get('sf_upload_dir').'/'.$fileName);

  // Do whatever is next

Don't forget to create the uploads/thumbnail/ directory before calling the action.

!ImageMagick-Specific Usage

Usage is the same as above except you need to explicitly call the sfImageMagickAdapter class.

$thumbnail = new sfThumbnail(150, 150, true, true, 75, 'sfImageMagickAdapter');

Custom Options

The last option in the constructor is an array that you can use to pass custom options to !ImageMagick. Below are some examples of this functionality.

Extract the first page from a PDF document:

$thumbnail = new sfThumbnail(150, 150, true, true, 75, 'sfImageMagickAdapter', array('extract' => 1));

"1" stands for the first page, "2" for the second page, etc.

If for some reason you use a non-standard name for your !ImageMagick binary, you can specify it like so:

$thumbnail = new sfThumbnail(150, 150, true, true, 75, 'sfImageMagickAdapter', array('convert' => 'my_imagemagick_binary'));

By default sfThumbnail resizes the image in order to get to the desired width and height of the thumbnail. But what if you want to force the thumbnail to be a certain width and height but without distorting the image of the source size scale is different than the thumbnail size scale Now you can use a custom option "method" to achieve just that but "shaving" the source image in order to get it to be the same scale as the thumbnail and them resize it to the required dimentions. When "shave_bottom" is used and the image’s width is greater than the height then sfThumbnail shaves from both left side and right side until the desired scale. There is one requirement for the "method" option to work as expected and it is to turn off scaling (set the third parameter of sfThumbnail to FALSE)

$thumbnail = new sfThumbnail(150, 150, false, true, 75, 'sfImageMagickAdapter', array('method' => 'shave_all'));

$thumbnail->save('/tmp/shave.png', 'image/png'); 



2007-09-15 | 1.5.0 Stable

  • kupokomapa: toString($mime) method now works for both adapters
  • kupokomapa: loadFile() method can now accept a URI if sfWebBrowserPluging is available
  • kupokomapa: Implemented "method" option for sfImageMagickAdapter where "method" for now can be "shave_all" or "shave_bottom"

2007-09-12 | 1.4.0 Stable

  • davedash: Added toString($mime) function to save file to a string

2007-05-18 | 1.3.0 Stable

  • bmeynell: Updated README
  • bmeynell: Fixed ticket (#1710)
  • bmeynell: Added adapter support
  • francois: Updated README

2006-11-29 | 1.2.0 Stable