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

Source for file analyzer.php

Documentation is available at analyzer.php

  1. <?php
  2. /**
  3.  * File containing the ezcImageAnalyzer 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.  * @package ImageAnalysis
  23.  * @version //autogentag//
  24.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  25.  * @filesource
  26.  */
  27.  
  28. /**
  29.  * Class to retreive information about a given image file.
  30.  * This class scans the specified image file and leaves the information
  31.  * available through the public property {@link ezcImageAnalyzer::$data}.
  32.  * The information available depends on the handlers used by the
  33.  * ezcImageAnalyzer and the type of image you select. In case the
  34.  * ezcImageAnalyzer does not find a suitable handler to analyze an image,
  35.  * it will throw a {@link ezcImageAnalyzerFileNotProcessableException}.
  36.  *
  37.  * In this package the following handlers are available (in their priority
  38.  * order):
  39.  * - {@link ezcImageAnalyzerImagemagickHandler}, which uses the ImageMagick
  40.  *   binary "identify" to collect information about an image.
  41.  * - {@link ezcImageAnalyzerPhpHandler}, which relies on the GD extension and
  42.  *   is capable of using the exif extension to determine additional data.
  43.  * 
  44.  * For detailed information on the data provided by these handlers,
  45.  * their capabilities on analyzing images and their speciallties, please
  46.  * take a look at their documentation. For general information on handlers,
  47.  * look at {@link ezcImageAnalyzerHandler},
  48.  * {@link ezcImageAnalyzer::getHandlerClasses()} and
  49.  * {@link ezcImageAnalyzer::setHandlerClasses()}.
  50.  * 
  51.  * A simple example.
  52.  * <code>
  53.  * // Analyzation of the MIME type is done during creation.
  54.  * $image = new ezcImageAnalyzer( dirname( __FILE__ ).'/toby.jpg' );
  55.  * 
  56.  * if ( $image->mime == 'image/tiff' || $image->mime == 'image/jpeg' )
  57.  * {
  58.  *      // Analyzation of further image data is done during access of the data
  59.  *      echo 'Photo taken on '.date( 'Y/m/d, H:i', $image->data->date ).".\n";
  60.  * }
  61.  * elseif ( $mime !== false )
  62.  * {
  63.  *      echo "Format was detected as {$mime}.\n";
  64.  * }
  65.  * else
  66.  * {
  67.  *      echo "Unknown photo format.\n";
  68.  * }
  69.  * </code>
  70.  *
  71.  * If you want to manipulate the handlers used by ezcImageAnalyzer, you can do
  72.  * this globally like this:
  73.  * <code>
  74.  * // Retreive the predefined handler classes
  75.  * $originalHandlers = ezcImageAnalyzer::getHandlerClasses();
  76.  * foreach ( $handlerClasses as $id => $handlerClass )
  77.  * {
  78.  *      // Unset the ezcImageAnalyzerPhpHandler (do not use that anymore!)
  79.  *      if ( $handlerClass === 'ezcImageAnalyzerPhpHandler' )
  80.  *      {
  81.  *          unset( $handlerClasses[$id] );
  82.  *      }
  83.  * }
  84.  * // Set the new collection of handler classes.
  85.  * ezcImageAnalyzer::setHandlerClasses( $handlerClasses );
  86.  *
  87.  * // Somewhere else in the code... This now tries to use your handler in the
  88.  * // first place
  89.  * $image = new ezcImageAnalyzer( '/var/cache/images/toby.jpg' );
  90.  * </code>
  91.  *
  92.  * Or you can define your own handler classes to be used (beware, those must
  93.  * either be already loaded or load automatically on access).
  94.  * <code>
  95.  * // Define your onw handler class to be used in the first place and fall back on
  96.  * // ImageMagick, if necessary.
  97.  * $handlerClasses = array( 'MyOwnHandlerClass', 'ezcImageAnalyzerImagemagickHandler' );
  98.  * ezcImageAnalyzer::setHandlerClasses( $handlerClasses );
  99.  *
  100.  * // Somewehre else in the code... This now tries to use your handler in the
  101.  * // first place
  102.  * $image = new ezcImageAnalyzer( '/var/cache/images/toby.jpg' );
  103.  * </code>
  104.  *
  105.  * @property-read string $mime 
  106.  *                 The MIME type of the image.
  107.  * @property-read ezcImageAnalyzerData $data 
  108.  *                 Extended data about the image.
  109.  *
  110.  * @package ImageAnalysis
  111.  * @version //autogentag//
  112.  */
  113. {
  114.     /**
  115.      * The path of the file to analyze.
  116.      *
  117.      * @var string 
  118.      */
  119.     protected $filePath;
  120.  
  121.     /**
  122.      * Determines whether the image file has been analyzed or not.
  123.      * This is used internally.
  124.      *
  125.      * @var bool 
  126.      */
  127.     protected $isAnalyzed;
  128.  
  129.     /**
  130.      * Container to hold the properties
  131.      *
  132.      * @var array(string=>mixed) 
  133.      */
  134.     protected $properties;
  135.  
  136.     /**
  137.      * Collection of known handler classes. Classes are ordered by priority.
  138.      *
  139.      * @var array(string=>mixed) 
  140.      */
  141.     protected static $knownHandlers array(
  142.         'ezcImageAnalyzerPhpHandler' => array(),
  143.         'ezcImageAnalyzerImagemagickHandler' => array(),
  144.     );
  145.  
  146.     /**
  147.      * Available handler classes and their options.
  148.      *
  149.      * @var array 
  150.      */
  151.     protected static $availableHandlers;
  152.  
  153.     /**
  154.      * Create an image analyzer for the specified file.
  155.      *
  156.      * @throws ezcBaseFilePermissionException
  157.      *          If image file is not readable.
  158.      * @throws ezcBaseFileNotFoundException
  159.      *          If image file does not exist.
  160.      * @throws ezcImageAnalyzerFileNotProcessableException
  161.      *          If the file could not be processed.
  162.      * @param string $file The file to analyze.
  163.      */
  164.     public function __construct$file )
  165.     {
  166.         if !file_exists$file || !is_file$file ) )
  167.         {
  168.             throw new ezcBaseFileNotFoundException$file );
  169.         }
  170.         if !is_readable$file ) )
  171.         {
  172.             throw new ezcBaseFilePermissionException$fileezcBaseFileException::READ );
  173.         }
  174.         $this->filePath = $file;
  175.         $this->isAnalyzed = false;
  176.  
  177.         $this->checkHandlers();
  178.         
  179.         $this->analyzeType();
  180.     }
  181.  
  182.     /**
  183.      * Check all known handlers for availability.
  184.      *
  185.      * This method checks all registered handler classes for if the they are
  186.      * available (using {@link ezcImageAnalyzerHandler::isAvailable()}).
  187.      * 
  188.      * @throws ezcImageAnalyzerInvalidHandlerException
  189.      *          If a registered handler class does not exist
  190.      *          or does not inherit from {@link ezcImageAnalyzerHandler}.
  191.      */
  192.     protected function checkHandlers()
  193.     {
  194.         if issetezcImageAnalyzer::$availableHandlers && is_arrayezcImageAnalyzer::$availableHandlers ) )
  195.         {
  196.             return;
  197.         }
  198.         ezcImageAnalyzer::$availableHandlers array();
  199.         foreach ezcImageAnalyzer::$knownHandlers as $handlerClass => $options )
  200.         {
  201.             if !ezcBaseFeatures::classExists$handlerClass || !is_subclass_of$handlerClass'ezcImageAnalyzerHandler' ) )
  202.             {
  203.                 throw new ezcImageAnalyzerInvalidHandlerException$handlerClass );
  204.             }
  205.             $handler new $handlerClass$options );
  206.             if $handler->isAvailable() ) 
  207.             {
  208.                 ezcImageAnalyzer::$availableHandlers[clone$handler );
  209.             }
  210.         }
  211.     }
  212.  
  213.     /**
  214.      * Returns an array of known handler classes.
  215.      *
  216.      * This method returns an array of available handler classes. The array is
  217.      * indexed by the handler names, which are assigned to an array of options
  218.      * set for this handler.
  219.      *
  220.      * @return array(string=>array(string=>string)) Handlers and options.
  221.      */
  222.     public static function getHandlerClasses()
  223.     {
  224.         return ezcImageAnalyzer::$knownHandlers;
  225.     }
  226.  
  227.     /**
  228.      * Set the array of known handlers.
  229.      *
  230.      * Sets the available handlers. The array submitted must be indexed by
  231.      * the handler classes names (attention: handler classes must extend
  232.      * ezcImageAnalyzerHandler), assigned to an array of options for this
  233.      * handler. Most handlers don't have any options. Which options a handler
  234.      * may accept depends on the handler implementation.
  235.      *
  236.      * @param array(string=>array(string=>string)) $handlerClasses Handlers
  237.      *                                                              and options.
  238.      */
  239.     public static function setHandlerClassesarray $handlerClasses )
  240.     {
  241.         ezcImageAnalyzer::$knownHandlers $handlerClasses;
  242.         ezcImageAnalyzer::$availableHandlers null;
  243.     }
  244.  
  245.     /**
  246. /**
  247.      * Sets the property $name to $value.
  248.      *
  249.      * @throws ezcBasePropertyNotFoundException
  250.      *          If the property does not exist.
  251.      * @throws ezcBasePropertyPermissionException
  252.      *          If the property cannot be modified.
  253.      * @param string $name 
  254.      * @param mixed $value 
  255.      * @ignore
  256.      */
  257.     public function __set$name$value )
  258.     {
  259.         switch $name )
  260.         {
  261.             case 'mime':
  262.             case 'data':
  263.                 throw new ezcBasePropertyPermissionException$nameezcBasePropertyPermissionException::READ );
  264.             default:
  265.                 throw new ezcBasePropertyNotFoundException$name );
  266.         }
  267.     }
  268.  
  269.     /**
  270.      * Returns the property $name.
  271.      *
  272.      * @throws ezcBasePropertyNotFoundException
  273.      *          If the property does not exist.
  274.      * @param string $name Name of the property to access.
  275.      * @return mixed Value of the desired property.
  276.      * @ignore
  277.      */
  278.     public function __get$name )
  279.     {
  280.         switch $name )
  281.         {
  282.             case 'mime':
  283.                 return $this->properties['mime'];
  284.             case 'data':
  285.                 if !$this->isAnalyzed )
  286.                 {
  287.                     $this->analyzeImage();
  288.                 }
  289.                 return $this->properties[$name];
  290.             default:
  291.                 throw new ezcBasePropertyNotFoundException$name );
  292.         }
  293.     }
  294.  
  295.     /**
  296.      * Checks if the property $name exist and returns the result.
  297.      *
  298.      * @param string $name 
  299.      * @return bool 
  300.      * @ignore
  301.      */
  302.     public function __isset$name )
  303.     {
  304.         switch $name )
  305.         {
  306.             case 'mime':
  307.             case 'data':
  308.                 return true;
  309.             default:
  310.                 return false;
  311.         }
  312.     }
  313.  
  314.     /**
  315.      * Analyze the image file's MIME type.
  316.      * This method triggers a handler to analyze the MIME type of the given image file.
  317.      *
  318.      * @throws ezcImageAnalyzerFileNotProcessableException
  319.      *          If the no handler is capable to analyze the given image file.
  320.      */
  321.     public function analyzeType()
  322.     {
  323.         if !is_arrayezcImageAnalyzer::$availableHandlers ) )
  324.         {
  325.             $this->checkHandlers();
  326.         }
  327.         foreach ezcImageAnalyzer::$availableHandlers as $handler )
  328.         {
  329.             if ( ( $mime $handler->analyzeType$this->filePath ) ) !== false )
  330.             {
  331.                 $this->properties['mime'$mime;
  332.                 return;
  333.             }
  334.         }
  335.         throw new ezcImageAnalyzerFileNotProcessableException$this->filePath"Could not determine MIME type of file." );
  336.     }
  337.  
  338.     /**
  339.      * Analyze the image file.
  340.      *
  341.      * This method triggers a handler to analyze the given image file for more data.
  342.      * 
  343.      * @throws ezcImageAnalyzerFileNotProcessableException
  344.      *          If the no handler is capable to analyze the given image file.
  345.      * @throws ezcBaseFileIoException
  346.      *          If an error occurs while the file is read.
  347.      */
  348.     public function analyzeImage()
  349.     {
  350.         if !is_arrayezcImageAnalyzer::$availableHandlers ) )
  351.         {
  352.             $this->checkHandlers();
  353.         }
  354.         if !isset$this->properties['mime') )
  355.         {
  356.             $this->analyzeType();
  357.         }
  358.         foreach ezcImageAnalyzer::$availableHandlers as $handler )
  359.         {
  360.             if $handler->canAnalyze$this->properties['mime') )
  361.             {
  362.                 $this->properties['data'$handler->analyzeImage$this->filePath );
  363.                 $this->isAnalyzed = true;
  364.                 return;
  365.             }
  366.         }
  367.         throw new ezcImageAnalyzerFileNotProcessableException$this->filePath"No handler found to analyze MIME type '{$this->mime}'." );
  368.     }
  369. }
Documentation generated by phpDocumentor 1.4.3