<?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
 * under the License.
 *
 * @package ImageConversion
 * @version //autogentag//
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
 * @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.
 *
 * 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:
 *
 * <ul>
 * <li>ezcImageGdHandler
 *  <ul>
 *  <li>Uses PHP's GD extension for image manipulation.</li>
 *  <li>Implements the following filter interfaces
 *   <ul>
 *   <li>{@link ezcImageGeometryFilters}</li>
 *   <li>{@link ezcImageColorspaceFilters}</li>
 *   </ul>
 *  </li>
 *  </ul>
 * </li>
 * <li>ezcImageImagemagickHandler
 *  <ul>
 *  <li>Uses the external "convert" program, contained in ImageMagick</li>
 *  <li>Implements the following interfaces:
 *   <ul>
 *   <li>{@link ezcImageGeometryFilters}</li>
 *   <li>{@link ezcImageColorspaceFilters}</li>
 *   <li>{@link ezcImageEffectFilters}</li>
 *   </ul>
 *  </li>
 *  </ul>
 * </li>
 * </ul>
 *
 * A general example, how to use ezcImageConversion to convert images:
 * <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', dirname(__FILE__).'/jpeg.jpg', dirname(__FILE__).'/jpeg_thumb.jpg' );
 * </code>
 *
 * 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:
 * <code>
 * function getImageConverterInstance()
 * {
 *     if ( !isset( $GLOBALS['_ezcImageConverterInstance'] ) )
 *     {
 *         // 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(
 *                 'scale',
 *                 array(
 *                     'width'     => 100,
 *                     'height'    => 300,
 *                     'direction' => ezcImageGeometryFilters::SCALE_BOTH,
 *                 )
 *             ),
 *             new ezcImageFilter(
 *                 'colorspace',
 *                 array(
 *                     'space' => ezcImageColorspaceFilters::COLORSPACE_SEPIA,
 *                 )
 *             ),
 *             new ezcImageFilter(
 *                 'border',
 *                 array(
 *                     'width' => 5,
 *                     '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...
 * // Transform an image.
 * getImageConverterInstance()->transform( 'funny', dirname(__FILE__).'/jpeg.jpg', dirname(__FILE__).'/jpeg_singleton.jpg' );
 * 
 * </code>
 *
 * @see ezcImageHandler
 * @see ezcImageTransformation
 *
 * @package ImageConversion
 * @version //autogentag//
 * @mainclass
 */
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 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.
     *
     * @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 )
    {
        // Initialize handlers
        foreach ( $settings->handlers as $i => $handlerSettings )
        {
            if ( !$handlerSettings instanceof ezcImageHandlerSettings )
            {
                throw new ezcImageHandlerSettingsInvalidException();
            }
            $handlerClass = $handlerSettings->className;
            if ( !ezcBaseFeatures::classExists( $handlerClass ) )
            {
                throw new ezcImageHandlerNotAvailableException( $handlerClass );
            }
            $handler = new $handlerClass( $handlerSettings );
            $this->handlers[$handlerSettings->referenceName] = $handler;
        }
        // Check implicit conversions
        foreach ( $settings->conversions as $mimeIn => $mimeOut )
        {
            if ( !$this->allowsInput( $mimeIn ) )
            {
                throw new ezcImageMimeTypeUnsupportedException( $mimeIn, 'input' );
            }
            if ( !$this->allowsOutput( $mimeOut ) )
            {
                throw new ezcImageMimeTypeUnsupportedException( $mimeOut, 'output' );
            }
        }
        $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. 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
     * quality options.
     *
     * @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] ) )
        {
            throw new ezcImageTransformationAlreadyExistsException( $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.
     */
    public function removeTransformation( $name )
    {
        if ( !isset( $this->transformations[$name] ) )
        {
            throw new ezcImageTransformationNotAvailableException( $name );
        }
        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 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 )
    {
        if ( !isset( $this->transformations[$name] ) )
        {
            throw new ezcImageTransformationNotAvailableException( $name );
        }
        $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 ezcImageMimeTypeUnsupportedException
     *         If the input MIME type is not supported.
     */
    public function getMimeOut( $mimeIn )
    {
        if ( $this->allowsInput( $mimeIn ) === false )
        {
            throw new ezcImageMimeTypeUnsupportedException( $mimeIn, 'input' );
        }
        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 enabled 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 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 )
    {
        $handlerObj = false;
        // Do we have an explicit handler given?
        if ( $handlerName !== null )
        {
            if ( !isset( $this->handlers[$handlerName] ) )
            {
                throw new ezcImageHandlerNotAvailableException( $handlerName );
            }
            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 ezcImageFilterNotAvailableException( $filter->name );
        }
        $imgRef = $handlerObj->load( $inFile );
        $handlerObj->applyFilter( $imgRef, $filter );
        $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
     * returned.
     *
     * 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 )
    {
        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 ezcImageHandlerNotAvailableException( 'unknown' );
    }
}
?>