Previous topic

Next topic

14.1. Introduction

The Zend_Date component offers a detailed, but simple API for
manipulating dates and times. Its methods accept a wide variety of types of information,
including date parts, in numerous combinations yielding many features and possibilities
above and beyond the existing PHP date related functions. For the very latest manual
updates, please see our
online manual (frequently synced to Subversion).

Although simplicity remains the goal, working with localized dates and times while
modifying, combining, and comparing parts involves some unavoidable complexity. Dates, as
well as times, are often written differently in different locales. For example, some place
the month first, while other write the year first when expressing calendar dates. For more
information about handling localization and normalization, please refer to Zend_Locale.

Zend_Date also supports abbreviated names of months in many
languages. Zend_Locale facilitates the normalization of localized
month and weekday names to timestamps, which may, in turn, be shown localized to other
regions.

14.1.1. Always Set a Default Timezone

Before using any date related functions in PHP or Zend Framework, first make certain
your application has a correct default timezone, by either setting the TZ environment
variable, using the date.timezone php.ini setting, or using date_default_timezone_set().
In PHP, we can adjust all date and time related functions to work for a particular user
by setting a default timezone according to the user's expectations. For a complete list
of timezone settings, see the CLDR
Timezone Identifier List.

Example 14.1. Setting a Default Timezone

// timezone for an American in California
date_default_timezone_set('America/Los_Angeles');
// timezone for a German in Germany
date_default_timezone_set('Europe/Berlin');

When creating Zend_Date instances, their timezone will automatically become
the current default timezone! Thus, the timezone setting will account for any
Daylight Savings Time (DST) in effect, eliminating the need to explicitly specify DST.

Keep in mind that the timezones UTC and
GMT do not include Daylight Saving Time. This means that even if
you define per hand that Zend_Date should work with DST, it would
automatically be switched back for the instances of Zend_Date
which have been set to UTC or GMT.

14.1.2. Why Use Zend_Date?

Zend_Date offers the following features, which extend the scope
of PHP date functions:

Simple API

Zend_Date offers a very simple API, which combines the
best of date/time functionality from four programming languages. It is possible,
for example, to add or compare two times within a single row.

Completely internationalized

All full and abbreviated names of months and weekdays are supported for more
than 130 languages. Methods support both input and the output of dates using the
localized names of months and weekdays, in the conventional format associated
with each locale.

Unlimited timestamps

Although PHP 5.2 docs state, "The valid range of a timestamp is typically from
Fri, 13 Dec 1901 20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT,"
Zend_Date supports a nearly unlimited range, with the
help of the BCMath extension. If BCMath is not available, then Zend_Date will
have reduced support only for timestamps within the range of the
float type supported by your server. "The size of a float is
platform-dependent, although a maximum of ~1.8e308 with a precision of roughly
14 decimal digits is a common value (that's 64 bit IEEE format)." [ http://www.php.net/float ].
Additionally, inherent limitations of float data types, and rounding error of
float numbers may introduce errors into calculations. To avoid these problems,
the Zend Framework I18n components use BCMath extension, if available.

Support for ISO_8601 date specifications

ISO_8601 date specifications are supported. Even partially compliant ISO_8601
date specifications will be identified. These date formats are particularly
useful when working with databases. for example, even though MsSQL and MySQL
differ a little from each other, both are supported by
Zend_Date using the Zend_Date::ISO_8601 format
specification constant. When date strings conform to "Y/m/d" or "Y-m-d H:i:s",
according to PHP date() format tokens, use Zend_Date's built-in support for ISO
8601 formatted dates.

Calculate sunrise and sunset

For any place and day, the times for sunrise and sunset can be displayed, so
that you won't miss a single daylight second for working on your favorite PHP
project :)