Apache Zeta Components Manual :: File Source for transformation.php

Source for file transformation.php

Documentation is available at transformation.php

  1. <?php
  2. /**
  3.  * File containing the ezcImageTransformation class.
  4.  *
  5.  * Licensed to the Apache Software Foundation (ASF) under one
  6.  * or more contributor license agreements.  See the NOTICE file
  7.  * distributed with this work for additional information
  8.  * regarding copyright ownership.  The ASF licenses this file
  9.  * to you under the Apache License, Version 2.0 (the
  10.  * "License"); you may not use this file except in compliance
  11.  * with the License.  You may obtain a copy of the License at
  12.  * 
  13.  *   http://www.apache.org/licenses/LICENSE-2.0
  14.  * 
  15.  * Unless required by applicable law or agreed to in writing,
  16.  * software distributed under the License is distributed on an
  17.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18.  * KIND, either express or implied.  See the License for the
  19.  * specific language governing permissions and limitations
  20.  * under the License.
  21.  *
  22.  * @see ezcImageConverter
  23.  *
  24.  * @package ImageConversion
  25.  * @version //autogentag//
  26.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  27.  * @filesource
  28.  */
  29.  
  30. /**
  31.  * Provides transformations on images using filters and MIME conversions.
  32.  * Objects of this class group MIME type conversion and filtering of images
  33.  * into transformations of images. Transformations can be chained by referencing
  34.  * to another transformation so that multiple transformations will be produced
  35.  * after each other.
  36.  *
  37.  * <code>
  38.  * $filters = array(
  39.  *   new ezcImageFilter( 'scaleDownByWidth',
  40.  *                        array(
  41.  *                            'width' => 100
  42.  *                        )
  43.  *       ),
  44.  *   new ezcImageFilter( 'crop',
  45.  *                        array(
  46.  *                            'x' => 0,
  47.  *                            'y' => 0,
  48.  *                            'width'  => 100,
  49.  *                            'height' => 100,
  50.  *                        )
  51.  *       ),
  52.  * );
  53.  * $mimeTypes = array( 'image/jpeg', 'image/png' );
  54.  *
  55.  * // ezcImageTransformation object returned for further manipulation
  56.  * $thumbnail = $converter->createTransformation(
  57.  *      'thumbnail',
  58.  *      $filters,
  59.  *      $mimeTypes
  60.  * );
  61.  *
  62.  * $converter->transform( 'thumbnail', 'var/storage/myOriginal1.jpg',
  63.  *                        'var/storage/myThumbnail1' ); // res: image/jpeg
  64.  * $converter->transform( 'thumbnail', 'var/storage/myOriginal2.png',
  65.  *                        'var/storage/myThumbnail2' ); // res: image/png
  66.  * $converter->transform( 'thumbnail', 'var/storage/myOriginal3.gif',
  67.  *                        'var/storage/myThumbnail3' ); // res: image/.png
  68.  *
  69.  * // Animated GIF, will simply be copied!
  70.  * $converter->transform( 'thumbnail', 'var/storage/myOriginal4.gif',
  71.  *                        'var/storage/myThumbnail4' ); // res: image/gif
  72.  * </code>
  73.  *
  74.  * @see ezcImageConverter
  75.  *
  76.  * @package ImageConversion
  77.  * @version //autogentag//
  78.  */
  79. {
  80.     /**
  81.      * Array of MIME types allowed as output for this transformation.
  82.      * Leave empty, for all MIME types to be allowed.
  83.      *
  84.      * @var array(string) 
  85.      */
  86.     protected $mimeOut;
  87.  
  88.     /**
  89.      * Stores the filters utilized by a transformation.
  90.      *
  91.      * @var array(ezcImageFilter) 
  92.      */
  93.     protected $filters;
  94.  
  95.     /**
  96.      * Stores the name of this transformation.
  97.      *
  98.      * @var string 
  99.      */
  100.     protected $name;
  101.  
  102.     /**
  103.      * The ezcImageConverter
  104.      *
  105.      * @var ezcImageConverter 
  106.      */
  107.     protected $converter;
  108.  
  109.     /**
  110.      * The handler last used for filtering.
  111.      *
  112.      * @var ezcImageHandler 
  113.      */
  114.     protected $lastHandler;
  115.  
  116.     /**
  117.      * Options for the final save step.
  118.      * 
  119.      * @var ezcSaveOptions 
  120.      */
  121.     protected $saveOptions;
  122.  
  123.     /**
  124.      * Initialize transformation.
  125.      *
  126.      * @param ezcImageConverter $converter     The global converter.
  127.      * @param string $name                     Name for the transformation.
  128.      * @param array(ezcImageFilter) $filters   Filters to apply.
  129.      * @param array(string) $mimeOut           Output MIME types.
  130.      * @param ezcImageSaveOptions $saveOptions Options for saving images.
  131.      *
  132.      * @throws ezcImageFiltersException
  133.      *          On invalid filter or filter settings error.
  134.      * @throws ezcImageMimeTypeUnsupportedException
  135.      *          If the output type is unsupported.
  136.      */
  137.     public function __constructezcImageConverter $converter$namearray $filters array()array $mimeOut array()ezcImageSaveOptions $saveOptions null )
  138.     {
  139.         $this->converter = $converter;
  140.         $this->name = $name;
  141.         $this->setFilters$filters );
  142.         $this->setMimeOut$mimeOut );
  143.         $this->setSaveOptions$saveOptions !== null $saveOptions new ezcImageSaveOptions() );
  144.     }
  145.  
  146.     /**
  147.      * Add a filter to the conversion.
  148.      * Adds a filter with the specific settings. Filters can be added either
  149.      * before an existing filter or at the end (leave out $before parameter).
  150.      *
  151.      * @param ezcImageFilter $filter  The filter definition.
  152.      * @param int $before             Where to add the filter
  153.      * @return void 
  154.      *
  155.      * @throws ezcImageFilterNotAvailableException
  156.      *          If the given filter is not available.
  157.      */
  158.     public function addFilterezcImageFilter $filter$before null )
  159.     {
  160.         if $this->converter->hasFilter$filter->name === false )
  161.         {
  162.             throw new ezcImageFilterNotAvailableException$filter->name );
  163.         }
  164.         if isset$before && isset$this->filters[$before) )
  165.         {
  166.             array_splice$this->filters$before0array$filter ) );
  167.             return;
  168.         }
  169.         $this->filters[$filter;
  170.     }
  171.  
  172.     /**
  173.      * Determine output MIME type
  174.      * Returns the MIME type that the transformation will output.
  175.      *
  176.      * @param string $fileIn File that should deal as input for the transformation.
  177.      * @param string $mimeIn Specify the MIME type, so method does not need to.
  178.      *
  179.      * @return string MIME type the transformation will output.
  180.      *
  181.      * @throws ezcImageAnalyzerException If the input type is unsupported.
  182.      */
  183.     public function getOutMime$fileIn$mimeIn null )
  184.     {
  185.         if !isset$mimeIn ) )
  186.         {
  187.             $analyzer new ezcImageAnalyzer$fileIn );
  188.             $mimeIn   $analyzer->mime;
  189.         }
  190.         $mimeOut  $this->converter->getMimeOut$mimeIn );
  191.         // Is output type allowed by this transformation? Else use first allowed one...
  192.         return in_array$mimeOut$this->mimeOut $mimeOut reset$this->mimeOut );
  193.     }
  194.  
  195.     /**
  196.      * Apply the given filters for the transformation.
  197.      * Applies the conversion as defined to the given file and saves it as
  198.      * defined.
  199.      *
  200.      * @param string $fileIn  The file to transform.
  201.      * @param string $fileOut The file to save the transformed image to.
  202.      * @return void 
  203.      *
  204.      * @throws ezcImageTransformationException If an error occurs during the
  205.      *          transformation. The returned exception contains the exception
  206.      *          the problem resulted from in it's public $parent attribute.
  207.      * @throws ezcBaseFileNotFoundException If the file you are trying to
  208.      *          transform does not exists.
  209.      * @throws ezcBaseFilePermissionException If the file you are trying to
  210.      *          transform is not readable.
  211.      */
  212.     public function transform$fileIn$fileOut )
  213.     {
  214.         // Sanity checks
  215.         if !is_file$fileIn ) )
  216.         {
  217.             throw new ezcBaseFileNotFoundException$fileIn );
  218.         }
  219.         if !is_readable$fileIn ) )
  220.         {
  221.             throw new ezcBaseFilePermissionException$fileInezcBaseFileException::READ );
  222.         }
  223.         
  224.         // Start atomic file operation
  225.         $fileTmp tempnamdirname$fileOut DIRECTORY_SEPARATOR'.'basename$fileOut ) );
  226.         copy$fileIn$fileTmp );
  227.  
  228.         try
  229.         {
  230.             // MIME types
  231.             $analyzer new ezcImageAnalyzer$fileTmp );
  232.  
  233.             // Do not process animated GIFs
  234.             if $analyzer->data->isAnimated )
  235.             {
  236.                 copy$fileTmp$fileOut );
  237.                 unlink$fileTmp );
  238.                 return;
  239.             }
  240.  
  241.             $mimeIn $analyzer->mime;
  242.         }
  243.         catch ezcImageAnalyzerException $e )
  244.         {
  245.             // Clean up
  246.             unlink$fileTmp );
  247.             // Rethrow
  248.             throw new ezcImageTransformationException$e );
  249.         }
  250.  
  251.         $outMime $this->getOutMime$fileTmp$mimeIn );
  252.  
  253.         $ref '';
  254.  
  255.         // Catch exceptions for cleanup
  256.         try
  257.         {
  258.             // Apply the filters
  259.             foreach $this->filters as $filter )
  260.             {
  261.                 // Avoid reopening in same handler
  262.                 if isset$this->lastHandler ) )
  263.                 {
  264.                     if $this->lastHandler->hasFilter$filter->name ) )
  265.                     {
  266.                         $this->lastHandler->applyFilter$ref$filter );
  267.                         continue;
  268.                     }
  269.                     else
  270.                     {
  271.                         // Handler does not support filter, save file
  272.                         $this->lastHandler->save$ref );
  273.                         $this->lastHandler->close$ref );
  274.                     }
  275.                 }
  276.                 // Get handler to perform filter correctly
  277.                 $this->lastHandler = $this->converter->getHandler$filter->name$mimeIn );
  278.                 $ref $this->lastHandler->load$fileTmp$mimeIn );
  279.                 $this->lastHandler->applyFilter$ref$filter );
  280.             }
  281.  
  282.             // When no filters are performed by a transformation, we might have no last handler here
  283.             if !isset$this->lastHandler ) )
  284.             {
  285.                 $this->lastHandler = $this->converter->getHandlernull$mimeIn$outMime );
  286.                 $ref $this->lastHandler->load$fileTmp$mimeIn );
  287.             }
  288.  
  289.             // Perform conversion
  290.             if $this->lastHandler->allowsOutput( ( $outMime ) ) )
  291.             {
  292.                 $this->lastHandler->convert$ref$outMime );
  293.             }
  294.             else
  295.             {
  296.                 // Close in last handler
  297.                 $this->lastHandler->save$ref );
  298.                 $this->lastHandler->close$ref );
  299.                 // Destroy invalid reference (has been closed)
  300.                 $ref null;
  301.                 // Retreive correct handler
  302.                 $this->lastHandler = $this->converter->getHandlernull$mimeIn$outMime );
  303.                 // Load in new handler
  304.                 $ref $this->lastHandler->load$fileTmp );
  305.                 // Perform conversion
  306.                 $this->lastHandler->convert$ref$outMime );
  307.             }
  308.             // Everything done, save and close
  309.             $this->lastHandler->save$refnullnull$this->saveOptions );
  310.             $this->lastHandler->close$ref );
  311.         }
  312.         catch ezcImageException $e )
  313.         {
  314.             // Cleanup
  315.             if $ref !== null )
  316.             {
  317.                 $this->lastHandler->close$ref );
  318.             }
  319.             if file_exists$fileTmp ) )
  320.             {
  321.                 unlink$fileTmp );
  322.             }
  323.             $this->lastHandler = null;
  324.             // Rethrow
  325.             throw new ezcImageTransformationException$e );
  326.         }
  327.         
  328.         // Cleanup
  329.         $this->lastHandler = null;
  330.  
  331.         // Finalize atomic file operation
  332.         if ezcBaseFeatures::os(=== 'Windows' && file_exists$fileOut ) )
  333.         {
  334.             // Windows does not allows overwriting files using rename,
  335.             // therefore the file is unlinked here first.
  336.             if unlink$fileOut === false )
  337.             {
  338.                 // Cleanup
  339.                 unlink$fileTmp );
  340.                 throw new ezcImageFileNotProcessableException$fileOut'The file exists and could not be unlinked.' );
  341.             }
  342.         }
  343.         if @rename$fileTmp$fileOut === false )
  344.         {
  345.             unlink$fileTmp );
  346.             throw new ezcImageFileNotProcessableException$fileOut"The temporary file {$fileTmp} could not be renamed to {$fileOut}.);
  347.         }
  348.     }
  349.  
  350.     /**
  351.      * Set the filters for this transformation.
  352.      * Checks if the filters defined are available and saves them to the created
  353.      * transformation if everything is okay.
  354.      *
  355.      * @param array(ezcImageFilter) $filters Array of {@link ezcImageFilter filter objects}.
  356.      * @return void 
  357.      *
  358.      * @throws ezcImageFilterNotAvailableException
  359.      *          If a filter is not available.
  360.      * @throws ezcBaseFileException
  361.      *          If the filter array contains invalid object entries.
  362.      */
  363.     protected function setFiltersarray $filters )
  364.     {
  365.         foreach $filters as $id => $filter )
  366.         {
  367.             if !$filter instanceof ezcImageFilter )
  368.             {
  369.                 throw new ezcBaseSettingValueException'filters''array( int => ' get_class$filter ' )''array( int => ezcImageFilter )' );
  370.             }
  371.             if !$this->converter->hasFilter$filter->name ) )
  372.             {
  373.                 throw new ezcImageFilterNotAvailableException$filter->name );
  374.             }
  375.         }
  376.         $this->filters $filters;
  377.     }
  378.  
  379.     /**
  380.      * Sets the MIME types which are allowed for output.
  381.      *
  382.      * @param array $mime MIME types to allow output for.
  383.      * @return void 
  384.      *
  385.      * @throws ezcImageMimeTypeUnsupportedException
  386.      *          If the MIME types cannot be used as output of any of the
  387.      *          handlers in the converter.
  388.      */
  389.     protected function setMimeOutarray $mime )
  390.     {
  391.         foreach $mime as $mimeType )
  392.         {
  393.             if !$this->converter->allowsOutput$mimeType ) )
  394.             {
  395.                 throw new ezcImageMimeTypeUnsupportedException$mimeType'output' );
  396.             }
  397.         }
  398.         $this->mimeOut $mime;
  399.     }
  400.  
  401.     /**
  402.      * Sets the save options.
  403.      * Sets the save options, that are used for the final save step of the
  404.      * transformation.
  405.      *
  406.      * {@link ezcImageSaveOptions}
  407.      * 
  408.      * @param ezcImageSaveOptions $options Save options.
  409.      * @return void 
  410.      */
  411.     public function setSaveOptionsezcImageSaveOptions $options )
  412.     {
  413.         $this->saveOptions $options;
  414.     }
  415. }
  416. ?>
Documentation generated by phpDocumentor 1.4.3