Image rules

The basis of the image system is to setup the rules that control how to convert from one format to another. This consists of initializing the handlers, mimetypes, conversion rules and output types.

Initializing

The manager is initialized by registering the various image handlers, each handler is given an identifier which is used by image rules. This means that it's possible to register the same image class multiple times with different names, this is useful if you want different options.

// First get the image manager instance.
$img =& eZImageManager::instance();

// Register a shell converter using "convert", we name it "convert"
$img->registerType( "convert", new eZImageShell( '', "convert", array(), array(), array() ) );
// Register a converter which uses the PHP extension ImageGD
$img->registerType( "gd", new eZImageGD() );

Creating mimetypes

For the image manager to know the image type of a file you need to setup some mimetypes. The mimetype is a unique identifier for one given filetype and consists of a group and name part delimited by a slash (/). A standardised set of mimetypes is defined, but you can create your own if you wish.

The mimetypes are based on filenames (for now). The mimetype rule consists of the identifier (image/jpeg), the regular expression matching the filename ("\.jpe?g$") and the filename suffix. The suffix is for creating proper filenames for converted images.

// Create the JPEG, PNG and GIF type
$jpeg_type = $img->createMIMEType( "image/jpeg", "\.jpe?g$", "jpg" );
$png_type  = $img->createMIMEType( "image/png", "\.png$", "png" );
$gif_type  = $img->createMIMEType( "image/gif", "\.gif$", "gif" );

// and register them
$img->setMIMETypes( array( $jpeg_type, $png_type, $gif_type ) );

Creating rules

Next we create conversion rules by using the eZImageManager::createRule function. The function returns a structure based upon the parameters. For instance to convert from GIF to PNG we would do this:

// Create rule
$gif2png_rule = $img->createRule( "image/gif", "image/png", "convert", false, false );

// Register the rule and setup the default rule
$img->setRules( array( $gif2png_rule ),
                $img->createRule( "*", "image/png", "convert", false, false ) );

The rule consists of the from and to mimetypes, the image handler identifier and two parameters that say whether the rule can scale images and if it can run image operations. The default rule is also registered, this rule will be activated if no other rules match the file.

Finishing the setup

The last thing to do before the manager can be used is to setup the allowed output types. The output types supported by most browsers are GIF, PNG and JPEG but this might increase in the future, we might also want to limit our output types due to licensing issues.

// We only want JPEG images
$img->setOutputTypes( array( "mime/jpeg" ) );