path: root/modules/autorotate/lib/pel/Pel.php

<?php

/**
 *  PEL: PHP Exif Library.  A library with support for reading and
 *  writing all Exif headers in JPEG and TIFF images using PHP.
 *
 *  Copyright (C) 2004, 2005, 2006, 2007  Martin Geisler.
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program in the file COPYING; if not, write to the
 *  Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
 *  Boston, MA 02110-1301 USA
 */

/* $Id$ */


/**
 * Miscellaneous stuff for the overall behavior of PEL.
 *
 * @author Martin Geisler <mgeisler@users.sourceforge.net>
 * @version $Revision$
 * @date $Date$
 * @license http://www.gnu.org/licenses/gpl.html GNU General Public
 * License (GPL)
 * @package PEL
 */


/* Initialize Gettext, if available.  This must be done before any
 * part of PEL calls Pel::tra() or Pel::fmt() --- this is ensured if
 * every piece of code using those two functions require() this file.
 *
 * If Gettext is not available, wrapper functions will be created,
 * allowing PEL to function, but without any translations.
 *
 * The PEL translations are stored in './locale'.  It is important to
 * use an absolute path here because the lookups will be relative to
 * the current directory. */

if (function_exists('dgettext')) {
    bindtextdomain('pel', dirname(__FILE__) . '/locale');
} else {

    /**
     * Pretend to lookup a message in a specific domain.
     *
     * This is just a stub which will return the original message
     * untranslated.  The function will only be defined if the Gettext
     * extension has not already defined it.
     *
     * @param string $domain the domain.
     *
     * @param string $str the message to be translated.
     *
     * @return string the original, untranslated message.
     */
    function dgettext($domain, $str) {
        return $str;
    }
}


/**
 * Class with miscellaneous static methods.
 *
 * This class will contain various methods that govern the overall
 * behavior of PEL.
 *
 * Debugging output from PEL can be turned on and off by assigning
 * true or false to {@link Pel::$debug}.
 *
 * @author Martin Geisler <mgeisler@users.sourceforge.net>
 * @package PEL
 */
class Pel {

    /**
     * Flag for controlling debug information.
     *
     * The methods producing debug information ({@link debug()} and
     * {@link warning()}) will only output something if this variable is
     * set to true.
     *
     * @var boolean
     */
    private static $debug = false;

    /**
     * Flag for strictness of parsing.
     *
     * If this variable is set to true, then most errors while loading
     * images will result in exceptions being thrown.  Otherwise a
     * warning will be emitted (using {@link Pel::warning}) and the
     * exceptions will be appended to {@link Pel::$exceptions}.
     *
     * Some errors will still be fatal and result in thrown exceptions,
     * but an effort will be made to skip over as much garbage as
     * possible.
     *
     * @var boolean
     */
    private static $strict = false;

    /**
     * Stored exceptions.
     *
     * When {@link Pel::$strict} is set to false exceptions will be
     * accumulated here instead of being thrown.
     */
    private static $exceptions = array();

    /**
     * Quality setting for encoding JPEG images.
     *
     * This controls the quality used then PHP image resources are
     * encoded into JPEG images. This happens when you create a
     * {@link PelJpeg} object based on an image resource.
     *
     * The default is 75 for average quality images, but you can change
     * this to an integer between 0 and 100.
     *
     * @var int
     */
    private static $quality = 75;


    /**
     * Set the JPEG encoding quality.
     *
     * @param int $quality an integer between 0 and 100 with 75 being
     * average quality and 95 very good quality.
     */
    function setJPEGQuality($quality) {
        self::$quality = $quality;
    }


    /**
     * Get current setting for JPEG encoding quality.
     *
     * @return int the quality.
     */
    function getJPEGQuality() {
        return self::$quality;
    }


    /**
     * Return list of stored exceptions.
     *
     * When PEL is parsing in non-strict mode, it will store most
     * exceptions instead of throwing them.  Use this method to get hold
     * of them when a call returns.
     *
     * Code for using this could look like this:
     *
     * <code>
     * Pel::setStrictParsing(true);
     * Pel::clearExceptions();
     *
     * $jpeg = new PelJpeg($file);
     *
     * // Check for exceptions.
     * foreach (Pel::getExceptions() as $e) {
     *     printf("Exception: %s\n", $e->getMessage());
     *     if ($e instanceof PelEntryException) {
     *       // Warn about entries that couldn't be loaded.
     *       printf("Warning: Problem with %s.\n",
     *              PelTag::getName($e->getType(), $e->getTag()));
     *     }
     * }
     * </code>
     *
     * This gives applications total control over the amount of error
     * messages shown and (hopefully) provides the necessary information
     * for proper error recovery.
     *
     * @return array the exceptions.
     */
    static function getExceptions() {
        return self::$exceptions;
    }


    /**
     * Clear list of stored exceptions.
     *
     * Use this function before a call to some method if you intend to
     * check for exceptions afterwards.
     */
    static function clearExceptions() {
        self::$exceptions = array();
    }


    /**
     * Conditionally throw an exception.
     *
     * This method will throw the passed exception when strict parsing
     * in effect (see {@link setStrictParsing()}).  Otherwise the
     * exception is stored (it can be accessed with {@link
     * getExceptions()}) and a warning is issued (with {@link
     * Pel::warning}).
     *
     * @param PelException $e the exceptions.
     */
    static function maybeThrow(PelException $e) {
        if (self::$strict) {
            throw $e;
        } else {
            self::$exceptions[] = $e;
            self::warning('%s (%s:%s)', $e->getMessage(),
            basename($e->getFile()), $e->getLine());
        }
    }


    /**
     * Enable/disable strict parsing.
     *
     * If strict parsing is enabled, then most errors while loading
     * images will result in exceptions being thrown.  Otherwise a
     * warning will be emitted (using {@link Pel::warning}) and the
     * exceptions will be stored for later use via {@link
     * getExceptions()}.
     *
     * Some errors will still be fatal and result in thrown exceptions,
     * but an effort will be made to skip over as much garbage as
     * possible.
     *
     * @param boolean $flag use true to enable strict parsing, false to
     * diable.
     */
    function setStrictParsing($flag) {
        self::$strict = $flag;
    }


    /**
     * Get current setting for strict parsing.
     *
     * @return boolean true if strict parsing is in effect, false
     * otherwise.
     */
    function getStrictParsing() {
        return self::$strict;
    }


    /**
     * Enable/disable debugging output.
     *
     * @param boolean $flag use true to enable debug output, false to
     * diable.
     */
    function setDebug($flag) {
        self::$debug = $flag;
    }


    /**
     * Get current setting for debug output.
     *
     * @return boolean true if debug is enabled, false otherwise.
     */
    function getDebug() {
        return self::$debug;
    }


    /**
     * Conditionally output debug information.
     *
     * This method works just like printf() except that it always
     * terminates the output with a newline, and that it only outputs
     * something if the {@link Pel::$debug} is true.
     *
     * @param string $format the format string.
     *
     * @param mixed $args,... any number of arguments can be given.  The
     * arguments will be available for the format string as usual with
     * sprintf().
     */
    static function debug() {
        if (self::$debug) {
            $args = func_get_args();
            $str = array_shift($args);
            vprintf($str . "\n", $args);
        }
    }


    /**
     * Conditionally output a warning.
     *
     * This method works just like printf() except that it prepends the
     * output with the string 'Warning: ', terminates the output with a
     * newline, and that it only outputs something if the PEL_DEBUG
     * defined to some true value.
     *
     * @param string $format the format string.
     *
     * @param mixed $args,... any number of arguments can be given.  The
     * arguments will be available for the format string as usual with
     * sprintf().
     */
    static function warning() {
        if (self::$debug) {
            $args = func_get_args();
            $str = array_shift($args);
            vprintf('Warning: ' . $str . "\n", $args);
        }
    }


    /**
     * Translate a string.
     *
     * This static function will use Gettext to translate a string.  By
     * always using this function for static string one is assured that
     * the translation will be taken from the correct text domain.
     * Dynamic strings should be passed to {@link fmt} instead.
     *
     * @param string the string that should be translated.
     *
     * @return string the translated string, or the original string if
     * no translation could be found.
     */
    static function tra($str) {
        return dgettext('pel', $str);
    }


    /**
     * Translate and format a string.
     *
     * This static function will first use Gettext to translate a format
     * string, which will then have access to any extra arguments.  By
     * always using this function for dynamic string one is assured that
     * the translation will be taken from the correct text domain.  If
     * the string is static, use {@link tra} instead as it will be
     * faster.
     *
     * @param string $format the format string.  This will be translated
     * before being used as a format string.
     *
     * @param mixed $args,... any number of arguments can be given.  The
     * arguments will be available for the format string as usual with
     * sprintf().
     *
     * @return string the translated string, or the original string if
     * no translation could be found.
     */
    static function fmt() {
        $args = func_get_args();
        $str = array_shift($args);
        return vsprintf(dgettext('pel', $str), $args);
    }

}