TzDate: time/date manipulation with timezones

<?php

class TzDate {

    private static $_default_tz = 'UTC';
    private static $_default_format = 'r';

    private $_tz;
    private $_timestamp;

    /**
     * Returns instance of this class
     *
     * @param string (optional) Date value to create class from
     * @param string (optional) Valid time zone identifier
     * @param bool (optional) Use specified time zone for output (true: yes)
     * @return object Instance of this class
     */
    public static function factory($date = null, $tz = null, $set_timezone = false)
    {
        $class = __CLASS__;
        return new $class($date, $tz, $set_timezone);
    }

    /**
     * Set default output time zone for this class and returns it
     *
     * @param string Valid time zone identifier
     * @return string
     */
    public static function default_timezone($tz = null)
    {
        if ($tz !== null)
        {
            self::$_default_tz = $tz;
        }

        return self::$_default_tz;
    }

    /**
     * Set default date format string used in this class and returns it
     *
     * @param string Valid date() format string
     * @return string
     */
    public static function default_format($format = null)
    {
        if ($format !== null)
        {
            self::$_default_format = $format;
        }

        return self::$_default_format;
    }

    /**
     * Creates new instance of this class, (optionally) using specified date,
     * time zone (which, if specified, helps to correct given date back to UTC
     *
     * @param string (optional) Date value to create class from
     * @param string (optional) Valid time zone identifier
     * @param bool (optional) Use specified time zone for output (true: yes)
     */
    public function __construct($date = null, $tz = null, $set_timezone = false)
    {
        if ($set_timezone)
        {
            $this->timezone($tz);
        }

        if ($date !== null)
        {
            $this->set($date, $tz);
        }
    }

    /**
     * Set date stored in this object, using specified date and (optionally)
     * specified time zone
     *
     * @param string Date value to set in this object (can be relative value)
     * @param string (optional) Valid time zone identifier
     * @return object $this to allow method chaining
     */
    public function set($date, $tz = null)
    {
        if ($this->date_has_tz_info($date))
        {
            $date = $this->strip_tz_info($date);
        }

        $this->adjust($date, $tz);

        return $this;
    }

    /**
     * Adjusts this object's date value by specified value, considering
     * specified time zone (so that given value is relative to active time
     * zone setting)
     *
     * Value can be any valid strtotime() identifier.
     *
     * @param string Valid strtotime() identifier
     * @param string (optional) Valid time zone identifier
     * @return object $this to allow method chaining
     */
    public function adjust($value, $tz = null)
    {
        if ($tz !== null)
        {
            $tz = new DateTimeZone($tz);
        }
        else
        {
            $tz = new DateTimeZone(date_default_timezone_get());
        }

        $dt = null;

        if ($this->_timestamp)
        {
            $dt = new DateTime('@'.$this->_timestamp, $tz);
            $dt->modify($value);
        }
        else
        {
            $dt = new DateTime($value, $tz);
        }

        $this->_timestamp = $dt->format('U');

        return $this;
    }

    /**
     * Sets output time zone. This time zone is used when date is output from
     * this object.
     *
     * @param string Valid time zone identifier
     * @return object $this to allow method chaining
     */
    public function timezone($tz)
    {
        if (is_object($tz) and $tz instanceof DateTimeZone)
        {
            $this->_tz = $tz->getName();
        }
        else if ($tz !== null)
        {
            $this->_tz = $tz;
        }

        return $this;
    }

    /**
     * Returns date in specified time zone, using default date format.
     *
     * @param string Valid time zone identifier
     * @return string
     */
    public function convert($tz)
    {
        return $this->format($this->default_format, $tz);
    }

    /**
     * Returns date in specified format and (optionally) specified time zone.
     *
     * @param string Valid date() format string
     * @param string (optional) Valid time zone identifier
     * @return string
     */
    public function format($format, $tz = null)
    {
        if ($tz === null)
        {
            $tz = $this->timezone;
        }

        $dto = new DateTime('@'.($this->_timestamp ? $this->_timestamp : 0));
        $dto->setTimezone(new DateTimeZone($tz));

        return $dto->format($format);
    }

    /**
     * Checks if passed date contains time zone identifier.
     *
     * Note: This method is twice as fast as it would have been if it was
     * written using preg_match method! (tested and confirmed.)
     *
     * @param string Date string to test
     * @return bool
     */
    private function date_has_tz_info($date_string)
    {
        if (
            substr($date_string, -1) == 'z' // date ends with Z, meaning UTC (US NAVY spelling: Zulu)
            or ($sign = substr($date_string, -6, 1) and ($sign == '+' or $sign == '-')) // ends with +dd:dd
            or ($sign = substr($date_string, -5, 1) and ($sign == '+' or $sign == '-')) // ends with +dddd
        )
        {
            return true;
        }
        else
        {
            return false;
        }
    }

    /**
     * Strips time zone information embeded in date string.
     *
     * Examples:
     * - 2010-01-01T20:00:13Z (removes "Z")
     * - 2010-01-01T20:00:13+0100 (removes "+0100")
     * - 2010-01-01 20:00:13 -0300 (removes " -0300")
     *
     * @param string Date string
     * @return string
     */
    private function strip_tz_info($date_string)
    {
        return preg_replace('/\s*(z|[\+\-](\d{2}:\d{2}|\d{2,4}))$/i', '', $date_string);
    }

    /**
     * Public getter for current class.
     *
     * Properties defined:
     * - timezone (or tz): returns output timezone
     * - timestamp: returns current timestamp value
     * - default_format: returns default date formatting string
     * - date: returns date stored in this object, using default format
     *
     * @return string
     */
    public function __get($column)
    {
        if ($column == 'timezone' or $column == 'tz')
        {
            if ($this->_tz)
            {
                return $this->_tz;
            }
            else
            {
                return self::$_default_tz;
            }
        }
        else if ($column == 'timestamp')
        {
            return $this->_timestamp;
        }
        else if ($column == 'default_format')
        {
            return self::$_default_format;
        }
        else if ($column == 'date')
        {
            return $this->format($this->default_format);
        }
    }

    /**
     * Public setter for this class.
     *
     * Properties defined:
     * - timezone (or tz): sets output timezone
     * - date: sets date stored in this object
     *
     * @return void
     */
    public function __set($column, $value)
    {
        if ($column == 'timezone' or $column == 'tz')
        {
            $this->timezone($value);
        }
        else if ($column == 'date')
        {
            $this->set($value);
        }
    }

    /**
     * Returns string representation of this object, which is the date
     * contained in it, using default date format, and selected (or default)
     * output time zone setting
     *
     * @return string
     */
    public function __toString()
    {
        return $this->date;
    }
}