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:
A general example, how to use ezcImageConversion to convert images:
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:
Source for this file: /ImageConversion/src/converter.php
Version: | //autogentag// |
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. |
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. |
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.
Name | Type | Description |
---|---|---|
$settings |
ezcImageConverterSettings | Settings for the converter. |
Type | Description |
---|---|
ezcImageMimeTypeUnsupportedException |
If a given MIME type is not supported. |
ezcImageHandlerSettingsInvalidException |
If handler settings are invalid. |
Returns if a handler is found, supporting the given MIME type for output.
Name | Type | Description |
---|---|---|
$mime |
string | The MIME type to check for. |
Returns if a handler is found, supporting the given MIME type for output.
Name | Type | Description |
---|---|---|
$mime |
string | The MIME type to check for. |
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.
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. |
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. |
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.
Name | Type | Description |
---|---|---|
$name |
string | Name for the transformation. |
$filters |
array(ezcImageFilter) | Filters. |
$mimeOut |
array(string) | Output MIME types. |
$saveOptions |
ezcImageSaveOptions | Save options. |
Type | Description |
---|---|
ezcImageTransformationAlreadyExists |
If a transformation with the given name does already exist. |
ezcImageFiltersException |
If a given filter does not exist. |
Returns a list of enabled filters.
Gives you an overview on filters enabled in the manager. Format is:
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.
Name | Type | Description |
---|---|---|
$filterName |
string | Name of the filter to search for. |
$mimeIn |
string | Input MIME type. |
$mimeOut |
string | Output MIME type. |
Type | Description |
---|---|
ezcImageHandlerNotAvailableException |
If a handler for the given specification could not be found. |
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.
Name | Type | Description |
---|---|---|
$mimeIn |
string | Input MIME type. |
Type | Description |
---|---|
ezcImageMimeTypeUnsupportedException |
If the input MIME type is not supported. |
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.
Name | Type | Description |
---|---|---|
$name |
string | Name of the filter to query existance for |
Removes a transformation from the manager.
Name | Type | Description |
---|---|---|
$name |
string | Name of the transformation to remove |
Type | Description |
---|---|
ezcImageTransformationNotAvailableExeption |
If the requested transformation is unknown. |
Apply transformation on a file.
This applies the given transformation to the given file.
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 |
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. |