## Apache Zeta Components Manual :: Docs For Class ezcImageConverter

### ImageConversion::ezcImageConverter

### Class ezcImageConverter

Class to manage conversion and filtering of image files.

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. );
14. // Create the converter itself.
15. $converter=new ezcImageConverter ($settings);
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. );
34. // Which MIME types the conversion may output
35. $mimeTypes=array('image/jpeg','image/png');
37. // Create the transformation inside the manager
38. $converter-> createTransformation ('thumbnail',$filters,$mimeTypes);
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. functiongetImageConverterInstance()
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. );
19. // Create the converter itself.
20. $converter=new ezcImageConverter ($settings);
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. );
47. // Which MIME types the conversion may output
48. $mimeTypes=array('image/jpeg','image/png');
50. // Create the transformation inside the manager
51. $converter-> createTransformation ('funny',$filters,$mimeTypes);
53. // Assign singleton instance
54. $GLOBALS['_ezcImageConverterInstance']=$converter;
55. }
57. // Return singleton instance
58. return$GLOBALS['_ezcImageConverterInstance'];
59. }
61. // ...
62. // Somewhere else in the code...
63. // Transform an image.
64. getImageConverterInstance()-> transform ('funny', dirname (__FILE__).'/jpeg.jpg', dirname (__FILE__).'/jpeg_singleton.jpg');

Source for this file: /ImageConversion/src/converter.php

Version: | //autogentag//

### Member Variables

protected array(ezcImageHandler) | `$handlers = array()` Keeps the handlers used by the converter.
protected ezcImageConverterSettings | `$settings` Manager settings Settings basis for all image manipulations.
protected array | `$transformations = array()` Stores transformation registered with this converter.

### Method Summary

public ezcImageConverter | `__construct( $settings )` Initialize converter with settings object.
public bool | `allowsInput( $mime )` Returns if a handler is found, supporting the given MIME type for output.
public bool | `allowsOutput( $mime )` Returns if a handler is found, supporting the given MIME type for output.
public void | `applyFilter( $filter , $inFile , $outFile , [ $handlerName = null] )` Apply a single filter to an image.
public ezcImageTransformation | `createTransformation( $name , $filters , $mimeOut , [ $saveOptions = null] )` Create a transformation in the manager.
public array(string) | `getFilterNames( )` Returns a list of enabled filters.
public ezcImageHandler | `getHandler( [ $filterName = null] , [ $mimeIn = null] , [ $mimeOut = null] )` Returns a handler object for direct use.
public string | `getMimeOut( $mimeIn )` Returns the MIME type that will be outputted for a given input type.
public mixed | `hasFilter( $name )` Returns if a given filter is available.
public ezcImageTransformation | `removeTransformation( $name )` Removes a transformation from the manager.
public void | `transform( $name , $inFile , $outFile )` Apply transformation on a file.

### Methods

#### __construct

ezcImageConverter __construct( ezcImageConverterSettings $settings )

Initialize converter with settings object.

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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$settings` | ezcImageConverterSettings | Settings for the converter.

##### Exceptions:

Type | Description
--- | ---
`ezcImageMimeTypeUnsupportedException` | If a given MIME type is not supported.
`ezcImageHandlerSettingsInvalidException` | If handler settings are invalid.

#### allowsInput

bool allowsInput( string $mime )

Returns if a handler is found, supporting the given MIME type for output.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$mime` | string | The MIME type to check for.

#### allowsOutput

bool allowsOutput( string $mime )

Returns if a handler is found, supporting the given MIME type for output.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$mime` | string | The MIME type to check for.

#### applyFilter

void applyFilter( ezcImageFilter $filter , string $inFile , string $outFile , [string $handlerName = null] )

Apply a single filter to an image.

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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$filter` | ezcImageFilter | Filter object to apply.
`$inFile` | string | Name of the input file.
`$outFile` | string | Name of the output file.
`$handlerName` | string | To choose a specific handler, this is the reference named passed to ezcImageHandlerSettings.

##### Exceptions:

Type | Description
--- | ---
`ezcImageHandlerNotAvailableException` | If fitting handler is not available.
`ezcImageFilterNotAvailableException` | If filter is not available.
`ezcImageFileNameInvalidException` | If an invalid character (", ', $) is found in the file name.

#### createTransformation

ezcImageTransformation createTransformation( string $name , $filters , $mimeOut , [ezcImageSaveOptions $saveOptions = null] )

Create a transformation in the manager.

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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | Name for the transformation.
`$filters` | array(ezcImageFilter) | Filters.
`$mimeOut` | array(string) | Output MIME types.
`$saveOptions` | ezcImageSaveOptions | Save options.

##### Exceptions:

Type | Description
--- | ---
`ezcImageTransformationAlreadyExists` | If a transformation with the given name does already exist.
`ezcImageFiltersException` | If a given filter does not exist.

#### getFilterNames

array(string) getFilterNames( )

Returns a list of enabled filters.

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

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

#### getHandler

ezcImageHandler getHandler( [string $filterName = null] , [string $mimeIn = null] , [string $mimeOut = null] )

Returns a handler object for direct use.

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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$filterName` | string | Name of the filter to search for.
`$mimeIn` | string | Input MIME type.
`$mimeOut` | string | Output MIME type.

##### Exceptions:

Type | Description
--- | ---
`ezcImageHandlerNotAvailableException` | If a handler for the given specification could not be found.

#### getMimeOut

string getMimeOut( string $mimeIn )

Returns the MIME type that will be outputted for a given input type.

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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$mimeIn` | string | Input MIME type.

##### Exceptions:

Type | Description
--- | ---
`ezcImageMimeTypeUnsupportedException` | If the input MIME type is not supported.

#### hasFilter

mixed hasFilter( string $name )

Returns if a given filter is available.

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | Name of the filter to query existance for

#### removeTransformation

ezcImageTransformation removeTransformation( string $name )

Removes a transformation from the manager.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | Name of the transformation to remove

##### Exceptions:

Type | Description
--- | ---
`ezcImageTransformationNotAvailableExeption` | If the requested transformation is unknown.

#### transform

void transform( string $name , string $inFile , string $outFile )

Apply transformation on a file.

This applies the given transformation to the given file.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$name` | string | Name of the transformation to perform
`$inFile` | string | The file to transform
`$outFile` | string | The file to save transformed version to

##### Exceptions:

Type | Description
--- | ---
`ezcImageTransformationNotAvailableExeption` | If the requested transformation is unknown.
`ezcBaseFilePermissionException` | If the file you are trying to transform is not readable.
`ezcImageTransformationException` | If an error occurs during the transformation. The returned exception contains the exception the problem resulted from in it's public $parent attribute.
`ezcBaseFileNotFoundException` | If the file you are trying to transform does not exists.

Documentation generated by phpDocumentor 1.4.3