Source for file Driver.php

<?php
/* vim: set expandtab tabstop=4 shiftwidth=4: */
/**
 * Driver.php
 *
 * PHP Version 4
 *
 * Copyright (c) 1997-2008 The PHP Group
 *
 * This source file is subject to version 2.0 of the PHP license,
 * that is bundled with this package in the file LICENSE, and is
 * available at through the world-wide-web at
 * http://www.php.net/license/2_02.txt.
 * If you did not receive a copy of the PHP license and are unable to
 * obtain it through the world-wide-web, please send a note to
 * license@php.net so we can mail you a copy immediately.
 *
 * Authors:   Carsten Lucke <luckec@tool-garage.de>
 *
 * CVS file id: $Id: Driver.php,v 1.31 2008/03/17 11:13:36 kguest Exp $
 *
 * @category Date
 * @package  Date_Holidays
 * @author   Carsten Lucke <luckec@tool-garage.de>
 * @license  http://www.php.net/license/3_01.txt PHP License 3.0.1
 * @version  CVS: $Id: Driver.php,v 1.31 2008/03/17 11:13:36 kguest Exp $
 * @link     http://pear.php.net/package/Date_Holidays
 */
 
/**
 * DriverClass and associated defines.
 *
 * @abstract
 * @category Date
 * @package  Date_Holidays
 * @author   Carsten Lucke <luckec@tool-garage.de>
 * @license  http://www.php.net/license/3_01.txt PHP License 3.0.1
 * @version  CVS: $Id: Driver.php,v 1.31 2008/03/17 11:13:36 kguest Exp $
 * @link     http://pear.php.net/package/Date_Holidays
 */
 
/**
 * uses PEAR_Errorstack
 */
require_once 'PEAR/ErrorStack.php';
require_once 'Date/Holidays/Filter.php';
require_once 'Date/Holidays/Filter/Whitelist.php';
require_once 'Date/Holidays/Filter/Blacklist.php';
 
/**
 * invalid internal name
 *
 * @access  public
 */
define('DATE_HOLIDAYS_INVALID_INTERNAL_NAME', 51);
 
/**
 * title for a holiday is not available
 *
 * @access  public
 */
define('DATE_HOLIDAYS_TITLE_UNAVAILABLE', 52);
 
/**
 * date could not be converted into a PEAR::Date object
 *
 * date was neither a timestamp nor a string
 *
 * @access  public
 * @deprecated   will certainly be removed
 */
define('DATE_HOLIDAYS_INVALID_DATE', 53);
 
/**
 * string that represents a date has wrong format
 *
 * format must be YYYY-MM-DD
 *
 * @access  public
 * @deprecated   will certainly be removed
 */
define('DATE_HOLIDAYS_INVALID_DATE_FORMAT', 54);
 
/**
 * date for a holiday is not available
 *
 * @access  public
 */
define('DATE_HOLIDAYS_DATE_UNAVAILABLE', 55);
 
/**
 * language-file doesn't exist
 *
 * @access  public
 */
define('DATE_HOLIDAYS_LANGUAGEFILE_NOT_FOUND', 56);
 
/**
 * unable to read language-file
 *
 * @access  public
 */
define('DATE_HOLIDAYS_UNABLE_TO_READ_TRANSLATIONDATA', 57);
 
/**
 * Name of the static {@link Date_Holidays_Driver} method returning
 * a array of possible ISO3166 codes that identify itself.
 *
 * @access  public
 */
define('DATE_HOLIDAYS_DRIVER_IDENTIFY_ISO3166_METHOD', 'getISO3166Codes');
 
/**
 * class that helps you to locate holidays for a year
 *
 * @abstract
 * @category   Date
 * @package    Date_Holidays
 * @subpackage Driver
 * @author     Carsten Lucke <luckec@tool-garage.de>
 * @license    http://www.php.net/license/3_01.txt PHP License 3.0.1
 * @version    CVS: $Id: Driver.php,v 1.31 2008/03/17 11:13:36 kguest Exp $
 * @link       http://pear.php.net/package/Date_Holidays
 */
class Date_Holidays_Driver
{
 
    /**
     * locale setting for output
     *
     * @access   protected
     * @var      string 
     */
    var $_locale;
 
    /**
     * locales for which translations of holiday titles are available
     *
     * @access   private
     * @var      array 
     */
    var $_availableLocales = array('C');
 
    /**
     * object's current year
     *
     * @access   protected
     * @var      int 
     */
    var $_year;
 
    /**
     * internal names for the available holidays
     *
     * @access   protected
     * @var      array 
     */
    var $_internalNames = array();
 
    /**
     * dates of the available holidays
     *
     * @access   protected
     * @var      array 
     */
    var $_dates = array();
 
    /**
     * array of the available holidays indexed by date
     *
     * @access   protected
     * @var      array 
     */
    var $_holidays = array();
 
    /**
     * localized names of the available holidays
     *
     * @access   protected
     * @var      array 
     */
    var $_titles = array();
 
    /**
     * Array of holiday-properties indexed by internal-names and
     * furthermore by locales.
     *
     * <code>
     * $_holidayProperties = array(
     *       'internalName1' =>  array(
     *                               'de_DE' => array(),
     *                               'en_US' => array(),
     *                               'fr_FR' => array()
     *                           )
     *       'internalName2' =>  array(
     *                               'de_DE' => array(),
     *                               'en_US' => array(),
     *                               'fr_FR' => array()
     *                           )
     * );
     * </code>
     */
    var $_holidayProperties = array();
 
    /**
     * Constructor
     *
     * Use the Date_Holidays::factory() method to construct an object of a
     * certain driver
     *
     * @access   protected
     */
    function Date_Holidays_Driver()
    {
    }
 
    /**
     * Method that returns an array containing the ISO3166 codes that may possibly
     * identify a driver.
     *
     * @static
     * @access public
     * @return array possible ISO3166 codes
     */
    function getISO3166Codes()
    {
        return array();
    }
 
    /**
     * Sets the driver's current year
     *
     * Calling this method forces the object to rebuild the holidays
     *
     * @param int $year year
     *
     * @access   public
     * @return   boolean true on success, otherwise a PEAR_ErrorStack object
     * @throws   object PEAR_ErrorStack
     * @uses     _buildHolidays()
     */
    function setYear($year)
    {
        $this->_year = $year;
        return $this->_buildHolidays();
    }
 
    /**
     * Returns the driver's current year
     *
     * @access   public
     * @return   int     current year
     */
    function getYear()
    {
        return $this->_year;
    }
 
    /**
     * Build the internal arrays that contain data about the calculated holidays
     *
     * @abstract
     * @access   protected
     * @return   boolean true on success, otherwise a PEAR_ErrorStack object
     * @throws   object PEAR_ErrorStack
     */
    function _buildHolidays()
    {
    }
 
    /**
     * Add a driver component
     *
     * @param object $driver Date_Holidays_Driver object
     *
     * @abstract
     * @access public
     * @return void 
     */
    function addDriver($driver)
    {
    }
 
    /**
     * Remove a driver component
     *
     * @param object $driver Date_Holidays_Driver driver-object
     *
     * @abstract
     * @access   public
     * @return   boolean true on success, otherwise a PEAR_Error object
     * @throws   object PEAR_Error   DATE_HOLIDAYS_DRIVER_NOT_FOUND
     */
    function removeDriver($driver)
    {
    }
 
    /**
     * Returns the internal names of holidays that were calculated
     *
     * @access   public
     * @return   array 
     */
    function getInternalHolidayNames()
    {
        return $this->_internalNames;
    }
 
    /**
     * Returns localized titles of all holidays or those accepted by the filter
     *
     * @param Date_Holidays_Filter $filter filter-object (or an array !DEPRECATED!)
     * @param string               $locale locale setting that shall be used
     *                                      by this method
     *
     * @access   public
     * @return   array   $filter array with localized holiday titles on success,
     *                            otherwise a PEAR_Error object
     * @throws   object PEAR_Error   DATE_HOLIDAYS_INVALID_INTERNAL_NAME
     * @uses     getHolidayTitle()
     */
    function getHolidayTitles($filter = null, $locale = null)
    {
        if (is_null($filter)) {
            $filter = new Date_Holidays_Filter_Blacklist(array());
        } elseif (is_array($filter)) {
            $filter = new Date_Holidays_Filter_Whitelist($filter);
        }
 
        $titles =   array();
 
        foreach ($this->_internalNames as $internalName) {
            if ($filter->accept($internalName)) {
                $title = $this->getHolidayTitle($internalName, $locale);
                if (Date_Holidays::isError($title)) {
                    return $title;
                }
                $titles[$internalName] = $title;
            }
        }
 
        return $titles;
    }
 
    /**
     * Returns localized title for a holiday
     *
     * @param string $internalName internal name for holiday
     * @param string $locale       locale setting to be used by this method
     *
     * @access   public
     * @return   string  title on success, otherwise a PEAR_Error object
     * @throws   object PEAR_Error DATE_HOLIDAYS_INVALID_INTERNAL_NAME
     * @throws   object PEAR_Error DATE_HOLIDAYS_TITLE_UNAVAILABLE
     */
    function getHolidayTitle($internalName, $locale = null)
    {
        if (! in_array($internalName, $this->_internalNames)) {
            $msg = 'Invalid internal name: ' . $internalName;
            return Date_Holidays::raiseError(DATE_HOLIDAYS_INVALID_INTERNAL_NAME,
                                             $msg);
 
        }
 
        if (is_null($locale)) {
            $locale = $this->_findBestLocale($this->_locale);
        } else {
            $locale = $this->_findBestLocale($locale);
        }
 
        if (! isset($this->_titles[$locale][$internalName])) {
            if (Date_Holidays::staticGetProperty('DIE_ON_MISSING_LOCALE')) {
                $err = DATE_HOLIDAYS_TITLE_UNAVAILABLE;
                $msg = 'The internal name (' . $internalName . ') ' .
                       'for the holiday was correct but no ' .
                       'localized title could be found';
                return Date_Holidays::raiseError($err, $msg);
            }
        }
 
        if (isset($this->_titles[$locale][$internalName])) {
            return $this->_titles[$locale][$internalName];
        } else {
            return $this->_titles['C'][$internalName];
        }
    }
 
 
    /**
     * Returns the localized properties of a holiday. If no properties have
     * been stored an empty array will be returned.
     *
     * @param string $internalName internal name for holiday
     * @param string $locale       locale setting that shall be used by this method
     *
     * @access   public
     * @return   array   array of properties on success, otherwise
     *                    a PEAR_Error object
     * @throws   object PEAR_Error   DATE_HOLIDAYS_INVALID_INTERNAL_NAME
     */
    function getHolidayProperties($internalName, $locale = null)
    {
        if (! in_array($internalName, $this->_internalNames)) {
            $msg = 'Invalid internal name: ' . $internalName;
            return Date_Holidays::raiseError(DATE_HOLIDAYS_INVALID_INTERNAL_NAME,
                                             $msg);
        }
 
        if (is_null($locale)) {
            $locale =   $this->_findBestLocale($this->_locale);
        } else {
            $locale =   $this->_findBestLocale($locale);
        }
 
 
        $properties = array();
        if (isset($this->_holidayProperties[$internalName][$locale])) {
            $properties = $this->_holidayProperties[$internalName][$locale];
        }
        return $properties;
    }
 
 
    /**
     * Returns all holidays that the driver knows.
     *
     * You can limit the holidays by passing a filter, then only those
     * holidays accepted by the filter will be returned.
     *
     * Return format:
     * <pre>
     *   array(
     *       'easter'        =>  object of type Date_Holidays_Holiday,
     *       'eastermonday'  =>  object of type Date_Holidays_Holiday,
     *       ...
     *   )
     * </pre>
     *
     * @param Date_Holidays_Filter $filter filter-object
     *                                      (or an array !DEPRECATED!)
     * @param string               $locale locale setting that shall be used
     *                                       by this method
     *
     * @access   public
     * @return   array   numeric array containing objects of
     *                    Date_Holidays_Holiday on success, otherwise a
     *                    PEAR_Error object
     * @throws   object PEAR_Error   DATE_HOLIDAYS_INVALID_INTERNAL_NAME
     * @see      getHoliday()
     */
    function getHolidays($filter = null, $locale = null)
    {
        if (is_null($filter)) {
            $filter = new Date_Holidays_Filter_Blacklist(array());
        } elseif (is_array($filter)) {
            $filter = new Date_Holidays_Filter_Whitelist($filter);
        }
 
        if (is_null($locale)) {
            $locale = $this->_locale;
        }
 
        $holidays = array();
 
        foreach ($this->_internalNames as $internalName) {
            if ($filter->accept($internalName)) {
                // no need to check for valid internal-name, will be
                // done by #getHoliday()
                $holidays[$internalName] = $this->getHoliday($internalName,
                                                             $locale);
            }
        }
 
        return $holidays;
    }
 
    /**
     * Returns the specified holiday
     *
     * Return format:
     * <pre>
     *   array(
     *       'title' =>  'Easter Sunday'
     *       'date'  =>  '2004-04-11'
     *   )
     * </pre>
     *
     * @param string $internalName internal name of the holiday
     * @param string $locale       locale setting that shall be used
     *                               by this method
     *
     * @access   public
     * @return   object Date_Holidays_Holiday holiday's information on
     *                                          success, otherwise a PEAR_Error
     *                                          object
     * @throws   object PEAR_Error       DATE_HOLIDAYS_INVALID_INTERNAL_NAME
     * @uses     getHolidayTitle()
     * @uses     getHolidayDate()
     */
    function getHoliday($internalName, $locale = null)
    {
        if (! in_array($internalName, $this->_internalNames)) {
            return Date_Holidays::raiseError(DATE_HOLIDAYS_INVALID_INTERNAL_NAME,
                'Invalid internal name: ' . $internalName);
        }
        if (is_null($locale)) {
            $locale = $this->_locale;
        }
 
        $title = $this->getHolidayTitle($internalName, $locale);
        if (Date_Holidays::isError($title)) {
            return $title;
        }
        $date = $this->getHolidayDate($internalName);
        if (Date_Holidays::isError($date)) {
            return $date;
        }
        $properties = $this->getHolidayProperties($internalName, $locale);
        if (Date_Holidays::isError($properties)) {
            return $properties;
        }
 
        $holiday = new Date_Holidays_Holiday($internalName,
                                             $title,
                                             $date,
                                             $properties);
        return $holiday;
    }
 
    /**
     * Determines whether a date represents a holiday or not
     *
     * @param mixed                $date   a timestamp, string or PEAR::Date object
     * @param Date_Holidays_Filter $filter filter-object (or an array !DEPRECATED!)
     *
     * @access   public
     * @return   boolean true if date represents a holiday, otherwise false
     * @throws   object PEAR_Error   DATE_HOLIDAYS_INVALID_DATE_FORMAT
     * @throws   object PEAR_Error   DATE_HOLIDAYS_INVALID_DATE
     */
    function isHoliday($date, $filter = null)
    {
        if (! is_a($date, 'Date')) {
            $date = $this->_convertDate($date);
            if (Date_Holidays::isError($date)) {
                return $date;
            }
        }
 
        //rebuild internal array of holidays if required.
        $compare_year = $date->getYear();
        $this_year = $this->getYear();
        if ($this_year !== $compare_year) {
            $this->setYear($compare_year);
        }
 
        if (is_null($filter)) {
            $filter = new Date_Holidays_Filter_Blacklist(array());
        } elseif (is_array($filter)) {
            $filter = new Date_Holidays_Filter_Whitelist($filter);
        }
 
        foreach (array_keys($this->_dates) as $internalName) {
            if ($filter->accept($internalName)) {
                if (Date_Holidays_Driver::dateSloppyCompare($date,
                                          $this->_dates[$internalName]) != 0) {
                    continue;
                }
                $this->setYear($this_year);
                return true;
            }
        }
        $this->setYear($this_year);
        return false;
    }
 
    /**
     * Returns a <code>Date_Holidays_Holiday</code> object, if any was found,
     * matching the specified date.
     *
     * Normally the method will return the object of the first holiday matching
     * the date. If you want the method to continue searching holidays for the
     * specified date, set the 4th param to true.
     *
     * If multiple holidays match your date, the return value will be an array
     * containing a number of <code>Date_Holidays_Holiday</code> items.
     *
     * @param mixed   $date     date (timestamp | string | PEAR::Date object)
     * @param string  $locale   locale setting that shall be used by this method
     * @param boolean $multiple if true, continue searching holidays for
     *                            specified date
     *
     * @access   public
     * @return   object  object of type Date_Holidays_Holiday on success
     *                    (numeric array of those on multiple search),
     *                    if no holiday was found, matching this date,
     *                    null is returned
     * @throws   object PEAR_Error   DATE_HOLIDAYS_INVALID_DATE_FORMAT
     * @throws   object PEAR_Error   DATE_HOLIDAYS_INVALID_DATE
     * @uses     getHoliday()
     * @uses     getHolidayTitle()
     * @see      getHoliday()
     ***/
    function getHolidayForDate($date, $locale = null, $multiple = false)
    {
        if (!is_a($date, 'Date')) {
            $date = $this->_convertDate($date);
            if (Date_Holidays::isError($date)) {
                return $date;
            }
        }
        $isodate = mktime(0,
                          0,
                          0,
                          $date->getMonth(),
                          $date->getDay(),
                          $date->getYear());
        unset($date);
        if (is_null($locale)) {
            $locale = $this->_locale;
        }
        if (array_key_exists($isodate, $this->_holidays)) {
            if (!$multiple) {
                //get only the first feast for this day
                $internalName = $this->_holidays[$isodate][0];
                $result       = $this->getHoliday($internalName, $locale);
                return Date_Holidays::isError($result) ? null : $result;
            }
            // array that collects data, if multiple searching is done
            $data = array();
            foreach ($this->_holidays[$isodate] as $internalName) {
                $result = $this->getHoliday($internalName, $locale);
                if (Date_Holidays::