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

Source for file handler.php

Documentation is available at handler.php

  1. <?php
  2. /**
  3.  * This file contains the ezcImageHandler interface.
  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 ImageConversion
  23.  * @version //autogentag//
  24.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  25.  * @filesource
  26.  */
  27.  
  28. /**
  29.  * Driver interface to access different image manipulation backends of PHP.
  30.  * This interface has to be implemented by a handler class in order to be
  31.  * used with the ImageConversion package.
  32.  *
  33.  * @see ezcImageConverter
  34.  *
  35.  * @package ImageConversion
  36.  * @version //autogentag//
  37.  */
  38. abstract class ezcImageHandler
  39. {
  40.     /**
  41.      * Container to hold the properties
  42.      *
  43.      * @var array(string=>mixed) 
  44.      */
  45.     protected $properties;
  46.  
  47.     /**
  48.      * Settings of the handlers
  49.      * 
  50.      * @var ezcImageHandlerSettings 
  51.      */
  52.     protected $settings;
  53.  
  54.     /**
  55.      * Create a new image handler.
  56.      * Creates an image handler. This should never be done directly,
  57.      * but only through the manager for configuration reasons. One can
  58.      * get a direct reference through manager afterwards. When overwriting
  59.      * the constructor.
  60.      *
  61.      * @param ezcImageHandlerSettings $settings 
  62.      *         Settings for the handler.
  63.      */
  64.     public function __constructezcImageHandlerSettings $settings )
  65.     {
  66.         $this->properties['name'$settings->referenceName;
  67.         $this->settings = $settings;
  68.     }
  69.  
  70.     /**
  71.      * Sets the property $name to $value.
  72.      *
  73.      * @throws ezcBasePropertyNotFoundException if the property does not exist.
  74.      * @throws ezcBasePropertyReadOnlyException if the property cannot be modified.
  75.      * @param string $name 
  76.      * @param mixed $value 
  77.      * @ignore
  78.      */
  79.     public function __set$name$value )
  80.     {
  81.         switch $name )
  82.         {
  83.             case 'name':
  84.                 throw new ezcBasePropertyPermissionException$nameezcBasePropertyPermissionException::READ );
  85.             default:
  86.                 throw new ezcBasePropertyNotFoundException$name );
  87.         }
  88.     }
  89.  
  90.     /**
  91.      * Returns the property $name.
  92.      *
  93.      * @throws ezcBasePropertyNotFoundException if the property does not exist.
  94.      * @param string $name 
  95.      * @return mixed 
  96.      * @ignore
  97.      */
  98.     public function __get$name )
  99.     {
  100.         switch $name )
  101.         {
  102.             case 'name':
  103.                 return $this->properties[$name];
  104.             default:
  105.                 throw new ezcBasePropertyNotFoundException$name );
  106.         }
  107.     }
  108.  
  109.     /**
  110.      * Checks if the property $name exist and returns the result.
  111.      *
  112.      * @param string $name 
  113.      * @return bool 
  114.      * @ignore
  115.      */
  116.     public function __isset$name )
  117.     {
  118.         switch $name )
  119.         {
  120.             case 'name':
  121.                 return true;
  122.             default:
  123.                 return false;
  124.         }
  125.     }
  126.  
  127.     /**
  128.      * Checks a file name for illegal characters.
  129.      * Checks if a file name contains illegal characters, which are ", ' and $.
  130.      * 
  131.      * @param string $file The file name to check.
  132.      * @return void 
  133.      *
  134.      * @throws ezcImageFileNameInvalidException
  135.      *          If an invalid character (", ', $) is found in the file name.
  136.      */
  137.     protected function checkFileName$file )
  138.     {
  139.         if strpos$file"'" !== false || strpos$file"'" !== false || strpos$file'$' !== false )
  140.         {
  141.             throw new ezcImageFileNameInvalidException$file );
  142.         }
  143.     }
  144.  
  145.     /**
  146.      * Returns if a MIME conversion needs transparent color replacement.
  147.      *
  148.      * In case a transparency supporting MIME type (like image/png) is
  149.      * converted to one that does not support transparency, special steps need
  150.      * to be performed. This method returns if the given conversion from
  151.      * $inMime to $outMime is affected by this.
  152.      *
  153.      * @param string $inMime 
  154.      * @param string $outMime 
  155.      * @return bool 
  156.      */
  157.     protected function needsTransparencyConversion$inMime$outMime )
  158.     {
  159.         $transparencyMimes array(
  160.             'image/gif' => true,
  161.             'image/png' => true,
  162.         );
  163.         return (
  164.                $outMime !== null
  165.             && $inMime !== $outMime
  166.             && isset$transparencyMimes[$inMime)
  167.             && !isset$transparencyMimes[$outMime)
  168.         );
  169.     }
  170.  
  171.     /**
  172.      * Load an image file.
  173.      * Loads an image file and returns a reference to it.
  174.      *
  175.      * For developers: The use of ezcImageHandler::loadCommon() is highly
  176.      * recommended for the implementation of this method!
  177.      *
  178.      * @param string $file File to load.
  179.      * @param string $mime The MIME type of the file.
  180.      * @return string Reference to the file in this handler.
  181.      */
  182.     abstract public function load$file$mime null );
  183.  
  184.     /**
  185.      * Save an image file.
  186.      * Saves a given open file. Can optionally save to a new file name.
  187.      * The image reference is not freed automatically, so you need to call
  188.      * the close() method explicitly to free the referenced data.
  189.      *
  190.      * @see ezcImageHandler::load()
  191.      * @see ezcImageHandler::close()
  192.      *
  193.      * @param string $image                File reference created through.
  194.      * @param string $newFile              Filename to save the image to.
  195.      * @param string $mime                 New MIME type, if differs from
  196.      *                                      initial one.
  197.      * @param ezcImageSaveOptions $options Options for saving.
  198.      * @return void 
  199.      */
  200.     abstract public function save$image$newFile null$mime nullezcImageSaveOptions $options null );
  201.  
  202.     /**
  203.      * Close the file referenced by $image.
  204.      * Frees the image reference. You should call close() before.
  205.      *
  206.      * @see ezcImageHandler::load()
  207.      * @see ezcImageHandler::save()
  208.      * @param string $reference The image reference.
  209.      * @return void 
  210.      */
  211.     abstract public function close$reference );
  212.  
  213.     /**
  214.      * Check wether a specific MIME type is allowed as input for this handler.
  215.      *
  216.      * @param string $mime MIME type to check if it's allowed.
  217.      * @return bool 
  218.      */
  219.     abstract public function allowsInput$mime );
  220.  
  221.     /**
  222.      * Checks wether a specific MIME type is allowed as output for this handler.
  223.      *
  224.      * @param string $mime MIME type to check if it's allowed.
  225.      * @return bool 
  226.      */
  227.     abstract public function allowsOutput$mime );
  228.  
  229.     /**
  230.      * Checks if a given filter is available in this handler.
  231.      *
  232.      * @param string $name Name of the filter to check for.
  233.      * @return bool 
  234.      *
  235.      */
  236.     abstract public function hasFilter$name );
  237.  
  238.     /**
  239.      * Returns a list of filters this handler provides.
  240.      * The list returned is in format:
  241.      *
  242.      * <code>
  243.      * array(
  244.      *  0 => <string filtername>,
  245.      *  1 => <string filtername>,
  246.      *  ...
  247.      * )
  248.      * </code>
  249.      *
  250.      * @return array(string) 
  251.      */
  252.     abstract public function getFilterNames();
  253.  
  254.     /**
  255.      * Applies a filter to a given image.
  256.      *
  257.      * @internal This method is the main one, which will dispatch the
  258.      *  filter action to the specific function of the backend.
  259.      *
  260.      * @see ezcImageHandler::load()
  261.      * @see ezcImageHandler::save()
  262.      *
  263.      * @param string $image          Image reference to apply the filter on.
  264.      * @param ezcImageFilter $filter Contains which filter operation to apply.
  265.      * @return void 
  266.      * 
  267.      * @throws ezcImageFilterNotAvailableException
  268.      *          If the desired filter does not exist.
  269.      * @throws ezcImageMissingFilterParameterException
  270.      *          If a parameter for the filter is missing.
  271.      * @throws ezcImageFilterFailedException
  272.      *          If the operation performed by the the filter failed.
  273.      * @throws ezcBaseValueException
  274.      *          If a parameter was not within the expected range.
  275.      */
  276.     abstract public function applyFilter$imageezcImageFilter $filter );
  277.  
  278.     /**
  279.      * Converts an image to another MIME type.
  280.      *
  281.      * Use {@link ezcImageHandler::allowsOutput()} to determine,
  282.      * if the output MIME type is supported by this handler!
  283.      *
  284.      * @see ezcImageHandler::load()
  285.      * @see ezcImageHandler::save()
  286.      *
  287.      * @param string $image Image reference to convert.
  288.      * @param string $mime  MIME type to convert to.
  289.      * @return void 
  290.      *
  291.      * @throws ezcImageMimeTypeUnsupportedException
  292.      *          If the given MIME type is not supported by the filter.
  293.      */
  294.     abstract public function convert$image$mime );
  295. }
  296. ?>
Documentation generated by phpDocumentor 1.4.3