Source for file Pel.php

Documentation is available at Pel.php

  1. <?php
  2.  
  3. /*  PEL: PHP Exif Library.  A library with support for reading and
  4.  *  writing all Exif headers in JPEG and TIFF images using PHP.
  5.  *
  6.  *  Copyright (C) 2004, 2005, 2006, 2007  Martin Geisler.
  7.  *
  8.  *  This program is free software; you can redistribute it and/or modify
  9.  *  it under the terms of the GNU General Public License as published by
  10.  *  the Free Software Foundation; either version 2 of the License, or
  11.  *  (at your option) any later version.
  12.  *
  13.  *  This program is distributed in the hope that it will be useful,
  14.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16.  *  GNU General Public License for more details.
  17.  *
  18.  *  You should have received a copy of the GNU General Public License
  19.  *  along with this program in the file COPYING; if not, write to the
  20.  *  Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  21.  *  Boston, MA 02110-1301 USA
  22.  */
  23.  
  24. /* $Id$ */
  25.  
  26.  
  27. /**
  28.  * Miscellaneous stuff for the overall behavior of PEL.
  29.  *
  30.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  31.  * @version $Revision$
  32.  * @date $Date$
  33.  * @license http://www.gnu.org/licenses/gpl.html GNU General Public
  34.  *  License (GPL)
  35.  * @package PEL
  36.  */
  37.  
  38.  
  39. /* Initialize Gettext, if available.  This must be done before any
  40.  * part of PEL calls Pel::tra() or Pel::fmt() --- this is ensured if
  41.  * every piece of code using those two functions require() this file.
  42.  *
  43.  * If Gettext is not available, wrapper functions will be created,
  44.  * allowing PEL to function, but without any translations.
  45.  *
  46.  * The PEL translations are stored in './locale'.  It is important to
  47.  * use an absolute path here because the lookups will be relative to
  48.  * the current directory. */
  49.  
  50. if (function_exists('dgettext')) {
  51.   bindtextdomain('pel', dirname(__FILE__) . '/locale');
  52. } else {
  53.  
  54.   /**
  55.    * Pretend to lookup a message in a specific domain.
  56.    *
  57.    * This is just a stub which will return the original message
  58.    * untranslated.  The function will only be defined if the Gettext
  59.    * extension has not already defined it.
  60.    *
  61.    * @param string $domain the domain.
  62.    *
  63.    * @param string $str the message to be translated.
  64.    *
  65.    * @return string the original, untranslated message.
  66.    */
  67.   function dgettext($domain, $str) {
  68.     return $str;
  69.   }
  70. }
  71.  
  72.  
  73. /**
  74.  * Class with miscellaneous static methods.
  75.  *
  76.  * This class will contain various methods that govern the overall
  77.  * behavior of PEL.
  78.  *
  79.  * Debugging output from PEL can be turned on and off by assigning
  80.  * true or false to {@link Pel::$debug}.
  81.  *
  82.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  83.  * @package PEL
  84.  */
  85. class Pel {
  86.  
  87.   /**
  88.    * Flag for controlling debug information.
  89.    *
  90.    * The methods producing debug information ({@link debug()} and
  91.    * {@link warning()}) will only output something if this variable is
  92.    * set to true.
  93.    *
  94.    * @var boolean 
  95.    */
  96.   private static $debug = false;
  97.  
  98.   /**
  99.    * Flag for strictness of parsing.
  100.    *
  101.    * If this variable is set to true, then most errors while loading
  102.    * images will result in exceptions being thrown.  Otherwise a
  103.    * warning will be emitted (using {@link Pel::warning}) and the
  104.    * exceptions will be appended to {@link Pel::$exceptions}.
  105.    *
  106.    * Some errors will still be fatal and result in thrown exceptions,
  107.    * but an effort will be made to skip over as much garbage as
  108.    * possible.
  109.    *
  110.    * @var boolean 
  111.    */
  112.   private static $strict = false;
  113.   
  114.   /**
  115.    * Stored exceptions.
  116.    *
  117.    * When {@link Pel::$strict} is set to false exceptions will be
  118.    * accumulated here instead of being thrown.
  119.    */
  120.   private static $exceptions = array();
  121.  
  122.   /**
  123.    * Quality setting for encoding JPEG images.
  124.    *
  125.    * This controls the quality used then PHP image resources are
  126.    * encoded into JPEG images. This happens when you create a
  127.    * {@link PelJpeg} object based on an image resource.
  128.    *
  129.    * The default is 75 for average quality images, but you can change
  130.    * this to an integer between 0 and 100.
  131.    *
  132.    * @var int 
  133.    */
  134.   private static $quality = 75;
  135.  
  136.  
  137.   /**
  138.    * Set the JPEG encoding quality.
  139.    *
  140.    * @param int $quality an integer between 0 and 100 with 75 being
  141.    *  average quality and 95 very good quality.
  142.    */
  143.   function setJPEGQuality($quality) {
  144.     self::$quality = $quality;
  145.   }
  146.  
  147.  
  148.   /**
  149.    * Get current setting for JPEG encoding quality.
  150.    *
  151.    * @return int the quality.
  152.    */
  153.   function getJPEGQuality() {
  154.     return self::$quality;
  155.   }
  156.  
  157.  
  158.   /**
  159.    * Return list of stored exceptions.
  160.    *
  161.    * When PEL is parsing in non-strict mode, it will store most
  162.    * exceptions instead of throwing them.  Use this method to get hold
  163.    * of them when a call returns.
  164.    *
  165.    * Code for using this could look like this:
  166.    *
  167.    * <code>
  168.    * Pel::setStrictParsing(true);
  169.    * Pel::clearExceptions();
  170.    *
  171.    * $jpeg = new PelJpeg($file);
  172.    *
  173.    * // Check for exceptions.
  174.    * foreach (Pel::getExceptions() as $e) {
  175.    *     printf("Exception: %s\n", $e->getMessage());
  176.    *     if ($e instanceof PelEntryException) {
  177.    *       // Warn about entries that couldn't be loaded.
  178.    *       printf("Warning: Problem with %s.\n",
  179.    *              PelTag::getName($e->getType(), $e->getTag()));
  180.    *     }
  181.    * }
  182.    * </code>
  183.    *
  184.    * This gives applications total control over the amount of error
  185.    * messages shown and (hopefully) provides the necessary information
  186.    * for proper error recovery.
  187.    *
  188.    * @return array the exceptions.
  189.    */
  190.   static function getExceptions() {
  191.     return self::$exceptions;
  192.   }
  193.  
  194.  
  195.   /**
  196.    * Clear list of stored exceptions.
  197.    *
  198.    * Use this function before a call to some method if you intend to
  199.    * check for exceptions afterwards.
  200.    */
  201.   static function clearExceptions() {
  202.     self::$exceptions = array();
  203.   }
  204.  
  205.  
  206.   /**
  207.    * Conditionally throw an exception.
  208.    *
  209.    * This method will throw the passed exception when strict parsing
  210.    * in effect (see {@link setStrictParsing()}).  Otherwise the
  211.    * exception is stored (it can be accessed with {@link }
  212.    * getExceptions()}) and a warning is issued (with {@link }
  213.    * Pel::warning}).
  214.    *
  215.    * @param PelException $e the exceptions.
  216.    */
  217.   static function maybeThrow(PelException $e) {
  218.     if (self::$strict) {
  219.       throw $e;
  220.     } else {
  221.       self::$exceptions[] = $e;
  222.       self::warning('%s (%s:%s)', $e->getMessage(),
  223.                    basename($e->getFile()), $e->getLine());
  224.     }
  225.   }
  226.  
  227.  
  228.   /**
  229.    * Enable/disable strict parsing.
  230.    *
  231.    * If strict parsing is enabled, then most errors while loading
  232.    * images will result in exceptions being thrown.  Otherwise a
  233.    * warning will be emitted (using {@link Pel::warning}) and the
  234.    * exceptions will be stored for later use via {@link }
  235.    * getExceptions()}.
  236.    *
  237.    * Some errors will still be fatal and result in thrown exceptions,
  238.    * but an effort will be made to skip over as much garbage as
  239.    * possible.
  240.    *
  241.    * @param boolean $flag use true to enable strict parsing, false to
  242.    *  diable.
  243.    */
  244.   function setStrictParsing($flag) {
  245.     self::$strict = $flag;
  246.   }
  247.  
  248.  
  249.   /**
  250.    * Get current setting for strict parsing.
  251.    *
  252.    * @return boolean true if strict parsing is in effect, false
  253.    *  otherwise.
  254.    */
  255.   function getStrictParsing() {
  256.     return self::$strict;
  257.   }
  258.  
  259.  
  260.   /**
  261.    * Enable/disable debugging output.
  262.    *
  263.    * @param boolean $flag use true to enable debug output, false to
  264.    *  diable.
  265.    */
  266.   function setDebug($flag) {
  267.     self::$debug = $flag;
  268.   }
  269.  
  270.  
  271.   /**
  272.    * Get current setting for debug output.
  273.    *
  274.    * @return boolean true if debug is enabled, false otherwise.
  275.    */
  276.   function getDebug() {
  277.     return self::$debug;
  278.   }
  279.  
  280.  
  281.   /**
  282.    * Conditionally output debug information.
  283.    *
  284.    * This method works just like printf() except that it always
  285.    * terminates the output with a newline, and that it only outputs
  286.    * something if the {@link Pel::$debug} is true.
  287.    *
  288.    * @param string $format the format string.
  289.    *
  290.    * @param mixed $args,... any number of arguments can be given.  The
  291.    *  arguments will be available for the format string as usual with
  292.    *  sprintf().
  293.    */
  294.   static function debug() {
  295.     if (self::$debug) {
  296.       $args = func_get_args();
  297.       $str = array_shift($args);
  298.       vprintf($str . "\n", $args);
  299.     }
  300.   }
  301.  
  302.   
  303.   /**
  304.    * Conditionally output a warning.
  305.    *
  306.    * This method works just like printf() except that it prepends the
  307.    * output with the string 'Warning: ', terminates the output with a
  308.    * newline, and that it only outputs something if the PEL_DEBUG
  309.    * defined to some true value.
  310.    *
  311.    * @param string $format the format string.
  312.    *
  313.    * @param mixed $args,... any number of arguments can be given.  The
  314.    *  arguments will be available for the format string as usual with
  315.    *  sprintf().
  316.    */
  317.   static function warning() {
  318.     if (self::$debug) {
  319.       $args = func_get_args();
  320.       $str = array_shift($args);
  321.       vprintf('Warning: ' . $str . "\n", $args);
  322.     }
  323.   }
  324.  
  325.  
  326.   /**
  327.    * Translate a string.
  328.    *
  329.    * This static function will use Gettext to translate a string.  By
  330.    * always using this function for static string one is assured that
  331.    * the translation will be taken from the correct text domain.
  332.    * Dynamic strings should be passed to {@link fmt} instead.
  333.    *
  334.    * @param string the string that should be translated.
  335.    *
  336.    * @return string the translated string, or the original string if
  337.    *  no translation could be found.
  338.    */
  339.   static function tra($str) {
  340.     return dgettext('pel', $str);
  341.   }
  342.   
  343.  
  344.   /**
  345.    * Translate and format a string.
  346.    *
  347.    * This static function will first use Gettext to translate a format
  348.    * string, which will then have access to any extra arguments.  By
  349.    * always using this function for dynamic string one is assured that
  350.    * the translation will be taken from the correct text domain.  If
  351.    * the string is static, use {@link tra} instead as it will be
  352.    * faster.
  353.    *
  354.    * @param string $format the format string.  This will be translated
  355.    *  before being used as a format string.
  356.    *
  357.    * @param mixed $args,... any number of arguments can be given.  The
  358.    *  arguments will be available for the format string as usual with
  359.    *  sprintf().
  360.    *
  361.    * @return string the translated string, or the original string if
  362.    *  no translation could be found.
  363.    */
  364.   static function fmt() {
  365.     $args = func_get_args();
  366.     $str = array_shift($args);
  367.     return vsprintf(dgettext('pel', $str), $args);
  368.   }
  369.  
  370. }
  371.  
  372. ?>

Documentation generated on Thu, 05 May 2011 07:18:55 +0200 by phpDocumentor 1.4.3