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  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: Pel.php 463 2006-11-18 22:25:24Z mgeisler $ */
  25.  
  26.  
  27. /**
  28.  * Miscellaneous stuff for the overall behavior of PEL.
  29.  *
  30.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  31.  * @version $Revision: 463 $
  32.  * @date $Date: 2006-11-18 23:25:24 +0100 (Sat, 18 Nov 2006) $
  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.   /**
  124.    * Return list of stored exceptions.
  125.    *
  126.    * When PEL is parsing in non-strict mode, it will store most
  127.    * exceptions instead of throwing them.  Use this method to get hold
  128.    * of them when a call returns.
  129.    *
  130.    * Code for using this could look like this:
  131.    *
  132.    * <code>
  133.    * Pel::setStrictParsing(true);
  134.    * Pel::clearExceptions();
  135.    *
  136.    * $jpeg = new PelJpeg($file);
  137.    *
  138.    * // Check for exceptions.
  139.    * foreach (Pel::getExceptions() as $e) {
  140.    *     printf("Exception: %s\n", $e->getMessage());
  141.    *     if ($e instanceof PelEntryException) {
  142.    *       // Warn about entries that couldn't be loaded.
  143.    *       printf("Warning: Problem with %s.\n",
  144.    *              PelTag::getName($e->getType(), $e->getTag()));
  145.    *     }
  146.    * }
  147.    * </code>
  148.    *
  149.    * This gives applications total control over the amount of error
  150.    * messages shown and (hopefully) provides the necessary information
  151.    * for proper error recovery.
  152.    *
  153.    * @return array the exceptions.
  154.    */
  155.   static function getExceptions() {
  156.     return self::$exceptions;
  157.   }
  158.  
  159.  
  160.   /**
  161.    * Clear list of stored exceptions.
  162.    *
  163.    * Use this function before a call to some method if you intend to
  164.    * check for exceptions afterwards.
  165.    */
  166.   static function clearExceptions() {
  167.     self::$exceptions = array();
  168.   }
  169.  
  170.  
  171.   /**
  172.    * Conditionally throw an exception.
  173.    *
  174.    * This method will throw the passed exception when strict parsing
  175.    * in effect (see {@link setStrictParsing()}).  Otherwise the
  176.    * exception is stored (it can be accessed with {@link }
  177.    * getExceptions()}) and a warning is issued (with {@link }
  178.    * Pel::warning}).
  179.    *
  180.    * @param PelException $e the exceptions.
  181.    */
  182.   static function maybeThrow(PelException $e) {
  183.     if (self::$strict) {
  184.       throw $e;
  185.     } else {
  186.       self::$exceptions[] = $e;
  187.       self::warning('%s (%s:%s)', $e->getMessage(),
  188.                    basename($e->getFile()), $e->getLine());
  189.     }
  190.   }
  191.  
  192.  
  193.   /**
  194.    * Enable/disable strict parsing.
  195.    *
  196.    * If strict parsing is enabled, then most errors while loading
  197.    * images will result in exceptions being thrown.  Otherwise a
  198.    * warning will be emitted (using {@link Pel::warning}) and the
  199.    * exceptions will be stored for later use via {@link }
  200.    * getExceptions()}.
  201.    *
  202.    * Some errors will still be fatal and result in thrown exceptions,
  203.    * but an effort will be made to skip over as much garbage as
  204.    * possible.
  205.    *
  206.    * @param boolean $flag use true to enable strict parsing, false to
  207.    *  diable.
  208.    */
  209.   function setStrictParsing($flag) {
  210.     self::$strict = $flag;
  211.   }
  212.  
  213.  
  214.   /**
  215.    * Get current setting for strict parsing.
  216.    *
  217.    * @return boolean true if strict parsing is in effect, false
  218.    *  otherwise.
  219.    */
  220.   function getStrictParsing() {
  221.     return self::$strict;
  222.   }
  223.  
  224.  
  225.   /**
  226.    * Enable/disable debugging output.
  227.    *
  228.    * @param boolean $flag use true to enable debug output, false to
  229.    *  diable.
  230.    */
  231.   function setDebug($flag) {
  232.     self::$debug = $flag;
  233.   }
  234.  
  235.  
  236.   /**
  237.    * Get current setting for debug output.
  238.    *
  239.    * @return boolean true if debug is enabled, false otherwise.
  240.    */
  241.   function getDebug() {
  242.     return self::$debug;
  243.   }
  244.  
  245.  
  246.   /**
  247.    * Conditionally output debug information.
  248.    *
  249.    * This method works just like printf() except that it always
  250.    * terminates the output with a newline, and that it only outputs
  251.    * something if the {@link Pel::$debug} is true.
  252.    *
  253.    * @param string $format the format string.
  254.    *
  255.    * @param mixed $args,... any number of arguments can be given.  The
  256.    *  arguments will be available for the format string as usual with
  257.    *  sprintf().
  258.    */
  259.   static function debug() {
  260.     if (self::$debug) {
  261.       $args = func_get_args();
  262.       $str = array_shift($args);
  263.       vprintf($str . "\n", $args);
  264.     }
  265.   }
  266.  
  267.   
  268.   /**
  269.    * Conditionally output a warning.
  270.    *
  271.    * This method works just like printf() except that it prepends the
  272.    * output with the string 'Warning: ', terminates the output with a
  273.    * newline, and that it only outputs something if the PEL_DEBUG
  274.    * defined to some true value.
  275.    *
  276.    * @param string $format the format string.
  277.    *
  278.    * @param mixed $args,... any number of arguments can be given.  The
  279.    *  arguments will be available for the format string as usual with
  280.    *  sprintf().
  281.    */
  282.   static function warning() {
  283.     if (self::$debug) {
  284.       $args = func_get_args();
  285.       $str = array_shift($args);
  286.       vprintf('Warning: ' . $str . "\n", $args);
  287.     }
  288.   }
  289.  
  290.  
  291.   /**
  292.    * Translate a string.
  293.    *
  294.    * This static function will use Gettext to translate a string.  By
  295.    * always using this function for static string one is assured that
  296.    * the translation will be taken from the correct text domain.
  297.    * Dynamic strings should be passed to {@link fmt} instead.
  298.    *
  299.    * @param string the string that should be translated.
  300.    *
  301.    * @return string the translated string, or the original string if
  302.    *  no translation could be found.
  303.    */
  304.   static function tra($str) {
  305.     return dgettext('pel', $str);
  306.   }
  307.   
  308.  
  309.   /**
  310.    * Translate and format a string.
  311.    *
  312.    * This static function will first use Gettext to translate a format
  313.    * string, which will then have access to any extra arguments.  By
  314.    * always using this function for dynamic string one is assured that
  315.    * the translation will be taken from the correct text domain.  If
  316.    * the string is static, use {@link tra} instead as it will be
  317.    * faster.
  318.    *
  319.    * @param string $format the format string.  This will be translated
  320.    *  before being used as a format string.
  321.    *
  322.    * @param mixed $args,... any number of arguments can be given.  The
  323.    *  arguments will be available for the format string as usual with
  324.    *  sprintf().
  325.    *
  326.    * @return string the translated string, or the original string if
  327.    *  no translation could be found.
  328.    */
  329.   static function fmt() {
  330.     $args = func_get_args();
  331.     $str = array_shift($args);
  332.     return vsprintf(dgettext('pel', $str), $args);
  333.   }
  334.  
  335. }
  336.  
  337. ?>

Documentation generated on Tue, 19 Dec 2006 01:08:12 +0100 by phpDocumentor 1.3.0 SourceForge.net Logo