Image_Transform main use case is to create thumbnails of images.
The first step to do when using Image_Transform is to create an Image_Transform_Driver instance via the static factory() method. Just pass the driver name and you've got your object.
Note: You may omit the driver name. In that case, Image_Transform checks for Imagick2, GD and Imlib and uses whatever driver is found first.
Now you can load() your image by passing the filename to this function. Use one of the scaling methods and then save().
You may not execute several scaling functions in a row without saving in between.
Example 49-2. Scaling an image down
The example above did not do any error checking. Principially, any method may return a PEAR_Error object. Either you check each return value or - in PHP 5 - set the global PEAR error handler to throw exceptions as soon as an error occurs. This may interfere with other errors that are expected and can be hidden, so be careful with this option (especially when using other packages).
Example 49-3. Scaling an image and checking for all possible errors
The Image_Transform package is useless without a driver that encapsulates some graphic libraries' methods. As of April 2008, the package has the following drivers you can install and use:
Image_Transform_Driver_GD - uses methods of the GD 2 extension
Image_Transform_Driver_Imagick2 - for imagick PECL extension version < 2.0
Image_Transform_Driver_Imagick3 - for imagick PECL extension version >= 2.0
Image_Transform_Driver_Imlib - uses PHP imlib extension
Image_Transform_Driver_IM - Imagick binary executables (if you don't have the extension)
Image_Transform_Driver_NetPBM - uses the binary executable pnmscale of the NetPBM software package.
Image_Transform brings you a lot of methods to scale images. Most of them call the basic resizing method with different parameters, but still have their right to exist because they make your life convenient. Here is a short list:
resize - generic resizing method. Pass any size, percentage string (with %) or a scaling factor for both x and y values. Keep it 0 to keep that size. Does not necessarily keep the aspect ratio.
scaleByX - scale the image by resizing the width of the image to the given pixel size. Preserves aspect ratio.
scaleByY - scale the image by resizing the height of the image to the given pixel size. Preserves aspect ratio.
scale - generig scaling function. Pass a pixel value, percentage (with %) or scaling factor (<1). Keeps aspect ratio.
scaleByPercentage - scales by the given percentage.
scaleByFactor - same as scaleByPercentage(), just that the numbers are factor 100 smaller.
scaleByLength - scale so that the longest size has the desired size.
fit - scale the image so that it fits into the given box (width and height). Nothing is done if the image is already smaller or equal than the box size.
fitX - scale the image so that the width is the given size. If the width is already smaller, nothing is done.
fitY - scale the image so that the height is the given size. If the height is already smaller, nothing is done.
The save() method requires at least one parameter, the filename as which the scaled image is to be saved as. With only one parameter, the type of the new image is the same as the original type.
Note: File extensions are not appended if left out.
The second parameter can be the extension of the file type you want to save the image as, for example png or jpg.
In case of an error - for example if the driver does not support to write the file type - a PEAR_Error object is returned.
Instead of saving, you can directly put out the image to the browser using display().
Table 49-3. Driver support for transformation methods