<?php
/**
 * File containing the ezcImageConverter class.
 *
 * @package ImageConversion
 * @version 1.0beta2
 * @copyright Copyright (C) 2005 eZ systems as. All rights reserved.
 * @license http://ez.no/licenses/new_bsd New BSD License
 * @filesource
 */

/**
 * 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.
 *
 * <code>
 *
 * // Prepare settings for ezcImageConverter
 * // Defines the handlers to utilize and auto conversions.
 * $settings = new ezcImageConverterSettings(
 *     array(
 *         new ezcImageHandlerSettings( 'GD',          'ezcImageGdHandler' ),
 *         new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
 *     ),
 *     array(
 *         'image/gif' => 'image/png',
 *         'image/bmp' => 'image/jpeg',
 *     )
 * );
 *
 *
 * // Create the converter itself.
 * $converter = new ezcImageConverter( $settings );
 *
 * // Define a transformation
 * $filters = array(
 *     new ezcImageFilter(
 *         'scaleWidth',
 *         array(
 *             'width'     => 100,
 *             'direction' => ezcImageGeometryFilters::SCALE_BOTH,
 *         ),
 *     ),
 *     new ezcImageFilter(
 *         'colorspace',
 *         array(
 *             '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 );
 *
 * // Transform an image.
 * $converter->transform( 'thumbnail', 'var/storage/football.bmp', 'var/storage/footballThumb.jpg' );
 * </code>
 *
 * @see ezcImageHandler
 * @see ezcImageTransformation
 *
 * @package ImageConversion
 */
class ezcImageConverter
{
    /**
     * Manager settings
     * Settings basis for all image manipulations.
     *
     * @var ezcImageConverterSettings
     */
    protected $settings;

    /**
     * Keeps the handlers used by the converter.
     *
     * @var array(ezcImageHandler)
     */
    protected $handlers = array();

    /**
     * Stores transformation registered with this converter.
     *
     * @var array
     */
    protected $transformations = array();

    /**
     * Initialize converter with settings object.
     * The ezcImageConverter can be directly instanciated, 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.
     *
     * @param ezcImageConverterSettings $settings Settings for the converter.
     *
     * @throws ezcImageConverterException
     *         for missmatching settings
     *         {@link ezcImageConverterException::HANDLER_NOT_AVAILABLE}.
     */
    public function __construct( ezcImageConverterSettings $settings )
    {
        // Initialize handlers
        foreach ( $settings->handlers as $i => $handlerSettings )
        {
            if ( !$handlerSettings instanceof ezcImageHandlerSettings )
            {
                if ( is_object( $handlerSettings ) )
                {
                    throw new ezcImageConverterException(
                        "Invalid handler settings object for index <{$i}>, expected class <ezcImageHandlerSettings> got class <" . get_class( $handlerSettings ) . ">.",
                        ezcImageConverterException::HANDLER_SETTINGS_INVALID
                        );
                }
                else
                {
                    throw new ezcImageConverterException(
                        "Invalid handler settings object for index <{$i}>, expected class <ezcImageHandlerSettings> got type " . gettype( $handlerSettings ) . ">.",
                        ezcImageConverterException::HANDLER_SETTINGS_INVALID
                        );
                }
            }
            $handlerClass = $handlerSettings->className;
            // Silence stupid warning from class_exists()
            if ( !@class_exists( $handlerClass ) )
            {
                throw new ezcImageConverterException(
                    "Handler class <{$handlerClass}> not found.",
                    ezcImageConverterException::HANDLER_NOT_AVAILABLE
                );
            }
            $handler = new $handlerClass( $handlerSettings );
            $this->handlers[$handlerSettings->referenceName] = $handler;
        }
        // Check implicit conversions
        foreach ( $settings->conversions as $mimeIn => $mimeOut )
        {
            if ( !$this->allowsInput( $mimeIn ) )
            {
                throw new ezcImageConverterException(
                    "Converter does not have a handler to support <{$mimeIn}> as input.",
                    ezcImageConverterException::MIMETYPE_NOT_AVAILABLE
                );
            }
            if ( !$this->allowsOutput( $mimeOut ) )
            {
                throw new ezcImageConverterException(
                    "Converter does not have a handler to support <{$mimeOut}> as output.",
                    ezcImageConverterException::MIMETYPE_NOT_AVAILABLE
                );
            }
        }
        $this->settings = $settings;
    }

    /**
     * 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.
     *
     * @param string                $name    Name of the transformation.
     * @param array(ezcImageFilter) $filters Definition of filters.
     * @param array(string)         $mimeOut Array definition of output MIME types.
     *
     * @return ezcImageTransformation
     *
     * @throws ezcImageFiltersException 
     *         if filters does not exist.
     * @throws eczImageConverterException 
     *         if the output type is unsupported
     *         {@link ezcImageConverterException::TRANSFORMATION_ALREADY_EXISTS}.
     */
    public function createTransformation( $name, array $filters, array $mimeOut )
    {
        if ( isset( $this->transformations[$name] ) )
        {
            throw new ezcImageConverterException(
                "Transformation <{$name}> already exists.",
                ezcImageConverterException::TRANSFORMATION_ALREADY_EXISTS
            );
        }
        $this->transformations[$name] = new ezcImageTransformation( $this, $name, $filters, $mimeOut );
        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 eczImageConverterException 
     *         if the transformation is unknown
     *         {@link ezcImageConverterException::TRANSFORMATION_NOT_AVAILABLE}.
     */
    public function removeTransformation( $name )
    {
        if ( !isset( $this->transformations[$name] ) )
        {
            throw new ezcImageConverterException(
                "Transformation <{$name}> does not exists.",
                ezcImageConverterException::TRANSFORMATION_NOT_AVAILABLE
            );
        }
        unset( $this->transformations[$name] );
    }

    /**
     * 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 eczImageConverterException 
     *         if the transformation is unknown
     *         {@link ezcImageConverterException::TRANSFORMATION_NOT_AVAILABLE}.
     * @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.
     */
    public function transform( $name, $inFile, $outFile )
    {
        if ( !isset( $this->transformations[$name] ) )
        {
            throw new ezcImageConverterException(
                "Transformation <{$name}> does not exists.",
                ezcImageConverterException::TRANSFORMATION_NOT_AVAILABLE
            );
        }
        $this->transformations[$name]->transform( $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.
     */
    public function allowsInput( $mime )
    {
        foreach ( $this->handlers as $handler )
        {
            if ( $handler->allowsInput( $mime ) )
            {
                return true;
            }
        }
        return false;
    }

    /**
     * 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.
     */
    public function allowsOutput( $mime )
    {
        foreach ( $this->handlers as $handler )
        {
            if ( $handler->allowsOutput( $mime ) )
            {
                return true;
            }
        }
        return false;
    }

    /**
     * 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 eczImageConverterException 
     *         if the input MIME type is not supported
     *         {@link ezcImageConverterException::MIMETYPE_NOT_AVAILABLE}.
     */
    public function getMimeOut( $mimeIn )
    {
        if ( $this->allowsInput( $mimeIn ) === false )
        {
            throw new ezcImageConverterException(
                "Input MIME type <{$mimeIn}> not supported by converter.",
                ezcImageConverterException::MIMETYPE_NOT_AVAILABLE
            );
        }
        if ( isset( $this->settings->conversions[$mimeIn] ) )
        {
            return $this->settings->conversions[$mimeIn];
        }
        return $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.
     */
    public function hasFilter( $name )
    {
        foreach ( $this->handlers as $handler )
        {
            if ( $handler->hasFilter( $name ) )
            {
                return true;
            }
        }
        return false;
    }

    /**
     * Returns a list of enabled filters.
     * Gives you an overview on filters enbled in the manager.
     * Format is:
     * <code>
     * array(
     *  '<filterName>',
     * );
     * </code>
     *
     * @return array(string)
     */
    public function getFilterNames()
    {
        $filters = array();
        foreach ( $this->handlers as $handler )
        {
            $filters = array_merge( $filters, $handler->getFilterNames() );
        }
        return array_unique( $filters );
    }

    /**
     * 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}.
     * @return void
     *
     *
     * @throws ezcImageConverterException 
     *         If fitting handler is not available
     *         {@link ezcImageConverterException::HANDLER_NOT_AVAILABLE}.
     * @throws ezcImageConverterException 
     *         If filter is not available
     *         {@link ezcImageConverterException::FILTER_NOT_AVAILABLE}.
     */
    public function applyFilter( ezcImageFilter $filter, $inFile, $outFile, $handlerName = null )
    {
        $handlerObj = false;
        // Do we have an explicit handler given?
        if ( $handlerName !== null )
        {
            if ( !isset( $this->handlers[$handlerName] ) )
            {
                throw new ezcImageConverterException(
                    "Handler <{$handlerName}> does not exist or is not instanciated.",
                    ezcImageConverterException::HANDLER_NOT_AVAILABLE
                );
            }
            if ( $this->handlers[$handlerName]->hasFilter( $filter->name ) === true )
            {
                $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;
                    break;
                }
            }
        }
        // No handler found to apply filter with.
        if ( $handlerObj === false )
        {
            throw new ezcImageConverterException(
                "Filter <{$filter->name}> does not exist.",
                ezcImageConverterException::FILTER_NOT_AVAILABLE
            );
        }
        $imgRef = $handlerObj->load( $inFile );
        $handlerObj->applyFilter( $imgRef, $filter );
        $handlerObj->save( $imgRef, $outFile );
    }

    /**
     * Returns a handler object for direct use.
     * Returns the handler with the highes 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
     * with code @link ezcImageFiltersException::NOT_AVAILABLE is thrown.
     *
     * @param string $filterName  Name of the filter to search for.
     * @param string $mimeIn      Input MIME type.
     * @param string $mimeOut     Output MIME type.
     *
     * @return object(ezcImageHandler)
     *
     * @throws ezcImageConverterException
     *         If a handler for the given specification could not be found
     *         {@link ezcImageConverterException::HANDLER_NOT_AVAILABLE}.
     */
    public function getHandler( $filterName = null, $mimeIn = null, $mimeOut = null )
    {
        foreach ( $this->handlers as $handler )
        {
            if ( ( !isset( $filterName ) || $handler->hasFilter( $filterName ) )
              && ( !isset( $mimeIn )     || $handler->allowsInput( $mimeIn ) )
              && ( !isset( $mimeOut )    || $handler->allowsOutput( $mimeOut ) )
               )
            {
                return $handler;
            }
        }
        throw new ezcImageConverterException(
            "No handler found that has filter <{$filterName}> and supports <{$mimeIn}> for input and <{$mimeOut}> for output.",
            ezcImageConverterException::HANDLER_NOT_AVAILABLE
        );
    }
}
?>