Apache Zeta Components Manual :: File Source for converter.php
Source for file converter.php
Documentation is available at converter.php
* File containing the ezcImageConverter class.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* @package ImageConversion
* @version //autogentag//
* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
* 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
* 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
* <li>Uses PHP's GD extension for image manipulation.</li>
* <li>Implements the following filter interfaces
* <li>{@link ezcImageGeometryFilters}</li>
* <li>{@link ezcImageColorspaceFilters}</li>
* <li>ezcImageImagemagickHandler
* <li>Uses the external "convert" program, contained in ImageMagick</li>
* <li>Implements the following interfaces:
* <li>{@link ezcImageGeometryFilters}</li>
* <li>{@link ezcImageColorspaceFilters}</li>
* <li>{@link ezcImageEffectFilters}</li>
* A general example, how to use ezcImageConversion to convert images:
* // Prepare settings for ezcImageConverter
* // Defines the handlers to utilize and auto conversions.
* $settings = new ezcImageConverterSettings(
* new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
* new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
* 'image/gif' => 'image/png',
* 'image/bmp' => 'image/jpeg',
* // Create the converter itself.
* $converter = new ezcImageConverter( $settings );
* // Define a transformation
* 'direction' => ezcImageGeometryFilters::SCALE_BOTH,
* 'space' => ezcImageColorspaceFilters::COLORSPACE_GREY,
* // Which MIME types the conversion may output
* $mimeTypes = array( 'image/jpeg', 'image/png' );
* // Create the transformation inside the manager
* $converter->createTransformation( 'thumbnail', $filters, $mimeTypes );
* $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
* function getImageConverterInstance()
* if ( !isset( $GLOBALS['_ezcImageConverterInstance'] ) )
* // Prepare settings for ezcImageConverter
* // Defines the handlers to utilize and auto conversions.
* $settings = new ezcImageConverterSettings(
* new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
* new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
* 'image/gif' => 'image/png',
* 'image/bmp' => 'image/jpeg',
* // Create the converter itself.
* $converter = new ezcImageConverter( $settings );
* // Define a transformation
* 'direction' => ezcImageGeometryFilters::SCALE_BOTH,
* 'space' => ezcImageColorspaceFilters::COLORSPACE_SEPIA,
* 'color' => array(255, 0, 0),
* // Which MIME types the conversion may output
* $mimeTypes = array( 'image/jpeg', 'image/png' );
* // Create the transformation inside the manager
* $converter->createTransformation( 'funny', $filters, $mimeTypes );
* // Assign singleton instance
* $GLOBALS['_ezcImageConverterInstance'] = $converter;
* // Return singleton instance
* return $GLOBALS['_ezcImageConverterInstance'];
* // Somewhere else in the code...
* getImageConverterInstance()->transform( 'funny', dirname(__FILE__).'/jpeg.jpg', dirname(__FILE__).'/jpeg_singleton.jpg' );
* @see ezcImageTransformation
* @package ImageConversion
* @version //autogentag//
* Settings basis for all image manipulations.
* @var ezcImageConverterSettings
* Keeps the handlers used by the converter.
* @var array(ezcImageHandler)
* Stores transformation registered with this converter.
* 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
* @param ezcImageConverterSettings $settings Settings for the converter.
* @throws ezcImageHandlerSettingsInvalidException
* If handler settings are invalid.
* @throws ezcImageMimeTypeUnsupportedException
* If a given MIME type is not supported.
public function __construct( ezcImageConverterSettings $settings )
foreach ( $settings->handlers as $i =>
$handlerSettings )
$handlerClass =
$handlerSettings->className;
$handler =
new $handlerClass( $handlerSettings );
$this->handlers[$handlerSettings->referenceName] =
$handler;
// Check implicit conversions
foreach ( $settings->conversions as $mimeIn =>
$mimeOut )
* 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 {@link removeTransformation()} or to execute it
* using {@link transform()}. The $filters and $mimeOut parameters specify
* the transformation actions as described with {@link }
* ezcImageTransformation::__construct()}. The $saveOptions are used when
* the finally created image is saved and can configure compression and
* @param string $name Name for the transformation.
* @param array(ezcImageFilter) $filters Filters.
* @param array(string) $mimeOut Output MIME types.
* @param ezcImageSaveOptions $saveOptions Save options.
* @return ezcImageTransformation
* @throws ezcImageFiltersException
* If a given filter does not exist.
* @throws ezcImageTransformationAlreadyExists
* If a transformation with the given name does already exist.
public function createTransformation( $name, array $filters, array $mimeOut, ezcImageSaveOptions $saveOptions =
null )
if ( isset
( $this->transformations[$name] ) )
$this->transformations[$name] =
new ezcImageTransformation( $this, $name, $filters, $mimeOut, $saveOptions );
return $this->transformations[$name];
* Removes a transformation from the manager.
* @param string $name Name of the transformation to remove
* @return ezcImageTransformation The removed transformation
* @throws ezcImageTransformationNotAvailableExeption
* If the requested transformation is unknown.
* Apply transformation on a file.
* This applies the given transformation to the given file.
* @param string $name Name of the transformation to perform
* @param string $inFile The file to transform
* @param string $outFile The file to save transformed version to
* @throws ezcImageTransformationNotAvailableExeption
* If the requested transformation is unknown.
* @throws ezcImageTransformationException If an error occurs during the
* transformation. The returned exception contains the exception
* the problem resulted from in it's public $parent attribute.
* @throws ezcBaseFileNotFoundException If the file you are trying to
* transform does not exists.
* @throws ezcBaseFilePermissionException If the file you are trying to
* transform is not readable.
public function transform( $name, $inFile, $outFile )
* Returns if a handler is found, supporting the given MIME type for output.
* @param string $mime The MIME type to check for.
* @return bool Whether the MIME type is supported.
* Returns if a handler is found, supporting the given MIME type for output.
* @param string $mime The MIME type to check for.
* @return bool Whether the MIME type is supported.
* 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.
* @param string $mimeIn Input MIME type.
* @return string Output MIME type.
* @throws ezcImageMimeTypeUnsupportedException
* If the input MIME type is not supported.
if ( isset
( $this->settings->conversions[$mimeIn] ) )
return $this->settings->conversions[$mimeIn];
* 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.
* @param string $name Name of the filter to query existance for
* @return mixed Array of handlers on success, otherwise false.
* Returns a list of enabled filters.
* Gives you an overview on filters enabled in the manager.
* 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.
* @param ezcImageFilter $filter Filter object to apply.
* @param string $inFile Name of the input file.
* @param string $outFile Name of the output file.
* @param string $handlerName
* To choose a specific handler, this is the reference named passed
* to {@link ezcImageHandlerSettings}.
* @throws ezcImageHandlerNotAvailableException
* If fitting handler is not available.
* @throws ezcImageFilterNotAvailableException
* If filter is not available.
* @throws ezcImageFileNameInvalidException
* If an invalid character (", ', $) is found in the file name.
public function applyFilter( ezcImageFilter $filter, $inFile, $outFile, $handlerName =
null )
// Do we have an explicit handler given?
if ( $handlerName !==
null )
if ( !isset
( $this->handlers[$handlerName] ) )
$handlerObj =
$this->handlers[$handlerName];
// Either no handler explicitly given or try to fall back.
if ( $handlerObj ===
false )
foreach ( $this->handlers as $regHandler )
if ( $regHandler->hasFilter( $filter->name ) )
$handlerObj =
$regHandler;
// No handler found to apply filter with.
if ( $handlerObj ===
false )
$imgRef =
$handlerObj->load( $inFile );
$handlerObj->save( $imgRef, $outFile );
* 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
* If no handler is found, that supports the criteria named, an exception
* of type {@link ezcImageHandlerNotAvailableException} will be thrown.
* @param string $filterName Name of the filter to search for.
* @param string $mimeIn Input MIME type.
* @param string $mimeOut Output MIME type.
* @return ezcImageHandler
* @throws ezcImageHandlerNotAvailableException
* If a handler for the given specification could not be found.
public function getHandler( $filterName =
null, $mimeIn =
null, $mimeOut =
null )
if ( ( !isset
( $filterName ) ||
$handler->hasFilter( $filterName ) )
&&
( !isset
( $mimeIn ) ||
$handler->allowsInput( $mimeIn ) )
&&
( !isset
( $mimeOut ) ||
$handler->allowsOutput( $mimeOut ) )