Image Manipulation with eZ Components

Scaling images for use on the Web is one of the most common programming tasks when handling images in an application for the WWW. You typically have a high resolution image you need to make available as smaller thumbnails. These thumbnails need to fit within a defined size, for example 150x100 pixels, but still keep the aspect ratio.

The PHP 5.1 script below shows how you can use the eZ components for scaling your images. The converter API called ezcImageConverter is the main class responsible for image conversion, scaling and effects. It is based on a plugin architecture. This architecture is designed for optimal loading of only the code actually needed, thus lowering the memory usage and making it cleanly extendable with custom functionality.

Autoload Routine

Let's take a close look at the sample code step by step; afterwards showing you the complete code. The first few lines show the autoloader routine which allows to automatically include an eZ components class. You can read more about it in the introduction article.

<?php
// Load autoloader functionality
require_once 'Base/base.php';
function __autoload( $className )
{  
    ezcBase::autoload( $className );
}
?>

Choosing the Image Backend

In this example we use the ImageMagick handler for image conversion. Both ImageMagick and GD provide very similar functionality. However, ImageMagick supports more image formats for conversion compared to GD. On the other side, GD is built as a PHP extension, while ImageMagick is a command line executable ? this makes GD faster in most situations.

<?php
// Define which handler to use for the image manipulation.
$settings = new ezcImageConverterSettings(
    array(
        new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
        new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' )
        )
    );
?>

Scaling Filters

Next, the scaling transformation we are going to perform needs to be defined. We do this in the $scaleFilters array, which describes the different filters we want to apply to the image. In this case, we only apply one filter called scale. We additionally specify image width and height as filter parameters. The images should only be scaled down if larger than the specified size.

<?php
// Define the filters to apply
$scaleFilters = array(
    new ezcImageFilter(
        'scale',
        array( 'width'    => 500,
               'height'   => 350,
               'direction' => ezcImageGeometryFilters::SCALE_DOWN
               )
        )
    );
?>

By assigning the constant ezcImageGeometryFilters::SCALE_DOWN to the direction parameter, the script will take care of this requirement.When using ezcImageGeometryFilters::SCALE_DOWN, please note that it makes the filter only scale images in one direction: from a large to a smaller size. To allow for both directions of scaling (small to large and large to small), use ezcImageGeometryFilter::SCALE_BOTH instead. The constants are summarized in this tabel:

Execution

The definition of the transformation is done within the method $converter->createTransformation(). The $mimeTypes parameter limits the conversion to only output JPEG images. The transformation is given the name thumbnail and will be referenced later by this name (as a modified version of the singleton pattern). The actual transformation is being executed by the method $converter->transform(). There, we specify the transformation's name, as well as the source, and destination filename. Finally, we display the image in HTML by using PHP's print() function.

Sample Script and Result

Here comes the complete code, where you will also find further information about the script's functioning as inline comments to the source code. The sample code is available for download.

<?php
 
// Load autoloader functionality
require_once 'Base/base.php';
function __autoload( $className )
{  
    ezcBase::autoload( $className );
}
 
// Define which handler to use for the image manipulation.
$settings = new ezcImageConverterSettings(
    array(
       new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
        new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' )
        )
    );
 
// Create the converter object.
$converter = new ezcImageConverter( $settings );
 
// Define the filters to apply
$scaleFilters = array(
    new ezcImageFilter(
        'scale',
        array( 'width'    => 500,
               'height'   => 350,
               'direction' => ezcImageGeometryFilters::SCALE_DOWN
               )
        )
    );
 
// Which MIME types the conversion may output
$mimeTypes = array( 'image/jpeg' );
 
// Create the transformation inside the manager, this can be re-used
$converter->createTransformation( 'thumbnail', $scaleFilters, $mimeTypes );
 
// Transform an image.
$converter->transform( 'thumbnail', "boathouse.jpg", "boathouse_tumbnail.jpg" );
 
// Display the image after scaling
print( "<p><img src='boathouse_tumbnail.jpg' /></p>" );
?>

The script outputs a scaled-down version of the image as shown below.