Apache Zeta Components - high quality PHP components

This class is highly recommended to be used with an external singleton pattern to have just 1 converter in place over the whole application.

As back-ends 2 handler classes are available, of which at least 1 has to be configured during the instantiation of the ezcImageConverter. Both handlers utilize different image manipulation tools and are capable of different sets of filters:

• ezcImageGdHandler
  • Uses PHP's GD extension for image manipulation.
  • Implements the following filter interfaces
    • ezcImageGeometryFilters
    • ezcImageColorspaceFilters
• ezcImageImagemagickHandler
  • Uses the external "convert" program, contained in ImageMagick
  • Implements the following interfaces:
    • ezcImageGeometryFilters
    • ezcImageColorspaceFilters
    • ezcImageEffectFilters

A general example, how to use ezcImageConversion to convert images:

1.  // Prepare settings for ezcImageConverter
2.  // Defines the handlers to utilize and auto conversions.
3.  $settings = new ezcImageConverterSettings(
4.      array(
5.          new ezcImageHandlerSettings( 'GD',          'ezcImageGdHandler' ),
6.          new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
7.      ),
8.      array(
9.          'image/gif' => 'image/png',
10.          'image/bmp' => 'image/jpeg',
11.      )
12.  );
13.  
14.  // Create the converter itself.
15.  $converter = new ezcImageConverter( $settings );
16.  
17.  // Define a transformation
18.  $filters = array(
19.      new ezcImageFilter(
20.          'scaleWidth',
21.          array(
22.              'width'     => 100,
23.              'direction' => ezcImageGeometryFilters::SCALE_BOTH,
24.          )
25.      ),
26.      new ezcImageFilter(
27.          'colorspace',
28.          array(
29.              'space' => ezcImageColorspaceFilters::COLORSPACE_GREY,
30.          )
31.      ),
32.  );
33.  
34.  // Which MIME types the conversion may output
35.  $mimeTypes = array( 'image/jpeg', 'image/png' );
36.  
37.  // Create the transformation inside the manager
38.  $converter->createTransformation( 'thumbnail', $filters, $mimeTypes );
39.  
40.  // Transform an image.
41.  $converter->transform( 'thumbnail', dirname(__FILE__).'/jpeg.jpg', dirname(__FILE__).'/jpeg_thumb.jpg' );

It's recommended to create only a single ezcImageConverter instance in your application to avoid creating multiple instances of it's internal objects. You can implement a singleton pattern for this, which might look similar to the following example:

1.  function getImageConverterInstance()
2.  {
3.      if ( !isset( $GLOBALS['_ezcImageConverterInstance'] ) )
4.      {
5.          // Prepare settings for ezcImageConverter
6.          // Defines the handlers to utilize and auto conversions.
7.          $settings = new ezcImageConverterSettings(
8.              array(
9.                  new ezcImageHandlerSettings( 'GD',          'ezcImageGdHandler' ),
10.                  new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
11.              ),
12.              array(
13.                  'image/gif' => 'image/png',
14.                  'image/bmp' => 'image/jpeg',
15.              )
16.          );
17.  
18.  
19.          // Create the converter itself.
20.          $converter = new ezcImageConverter( $settings );
21.  
22.          // Define a transformation
23.          $filters = array(
24.              new ezcImageFilter(
25.                  'scale',
26.                  array(
27.                      'width'     => 100,
28.                      'height'    => 300,
29.                      'direction' => ezcImageGeometryFilters::SCALE_BOTH,
30.                  )
31.              ),
32.              new ezcImageFilter(
33.                  'colorspace',
34.                  array(
35.                      'space' => ezcImageColorspaceFilters::COLORSPACE_SEPIA,
36.                  )
37.              ),
38.              new ezcImageFilter(
39.                  'border',
40.                  array(
41.                      'width' => 5,
42.                      'color' => array(255, 0, 0),
43.                  )
44.              ),
45.          );
46.  
47.          // Which MIME types the conversion may output
48.          $mimeTypes = array( 'image/jpeg', 'image/png' );
49.  
50.          // Create the transformation inside the manager
51.          $converter->createTransformation( 'funny', $filters, $mimeTypes );
52.  
53.          // Assign singleton instance
54.          $GLOBALS['_ezcImageConverterInstance'] = $converter;
55.      }
56.  
57.      // Return singleton instance
58.      return $GLOBALS['_ezcImageConverterInstance'];
59.  }
60.  
61.  // ...
62.  // Somewhere else in the code...
63.  // Transform an image.
64.  getImageConverterInstance()->transform( 'funny', dirname(__FILE__).'/jpeg.jpg', dirname(__FILE__).'/jpeg_singleton.jpg' );

The ezcImageConverter can be directly instantiated, but it's highly recommended to use a manual singleton implementation to have just 1 instance of a ezcImageConverter per Request.

ATTENTION: The ezcImageConverter does not support animated GIFs. Animated GIFs will simply be ignored by all filters and conversions.

Applies just a single filter to an image. Optionally you can select a handler yourself, which is not recommended, but possible. If the specific handler does not have that filter, ImageConverter will try to fall back on another handler.

Creates a transformation and stores it in the manager. A reference to the transformation is returned by this method for further manipulation and to set options on it. The $name can later be used to remove a transfromation using removeTransformation() or to execute it using transform(). The $filters and $mimeOut parameters specify the transformation actions as described with ezcImageTransformation::__construct(). The $saveOptions are used when the finally created image is saved and can configure compression and quality options.

Gives you an overview on filters enabled in the manager. Format is:

1.  array(
2.   '<filterName>',
3.  );

Returns the handler with the highest priority, that supports the given filter, MIME input type and MIME output type. All parameters are optional, if none is specified, the highest prioritized handler is returned.

If no handler is found, that supports the criteria named, an exception of type ezcImageHandlerNotAvailableException will be thrown.

Checks whether the given input type can be processed. If not, an exception is thrown. Checks then, if an implicit conversion for that MIME type is defined. If so, outputs the given output MIME type. In every other case, just outputs the MIME type given, because no conversion is implicitly required.

Returns either an array of handler names this filter is available in or false if the filter is not enabled.

This applies the given transformation to the given file.