Zend_Date API remains simplistic and
unitary, its design remains flexible and powerful through the rich permutations of
operations and operands.
Several methods use date format strings, in a way similar to
date(). If you are more
comfortable with PHP's date format specifier than with
ISO format specifiers, then you can use
Zend_Date::setOptions(array('format_type' => 'php')).
Afterward, use PHP's date format specifiers for all functions
which accept a
$format parameter. Use
Zend_Date::setOptions(array('format_type' => 'iso')) to
switch back to the default mode of supporting only ISO date
format tokens. For a list of supported format codes, see
Self-Defined OUTPUT Formats
Using PHP's date() Format Specifiers
When dates are manipulated, sometimes they cross over a DST
change, normally resulting in the date losing or gaining an hour. For exmaple, when
adding months to a date before a DST change, if the resulting
date is after the DST change, then the resulting date will appear
to lose or gain an hour, resulting in the time value of the date changing. For
boundary dates, such as midnight of the first or last day of a month, adding enough
months to cross a date boundary results in the date losing an hour and becoming the
last hour of the preceding month, giving the appearance of an "off by 1" error. To
avoid this situation, the DST change ignored by using the
fix_dst option. When crossing the Summer or Winter
DST boundary, normally an hour is substracted or added depending
on the date. For example, date math crossing the Spring DST leads
to a date having a day value one less than expected, if the time part of the date
was originally 00:00:00. Since
Zend_Date is based on
timestamps, and not calendar dates with a time component, the timestamp loses an
hour, resulting in the date having a calendar day value one less than expected. To
prevent such problems use the option fix_dst, which defaults to
TRUE, causing DST to have no effect on date
Zend_Date::setOptions(array('fix_dst' => false)) to
enable the subtraction or addition of the DST adjustment when
performing date "math".
If your actual timezone within the instance of
Zend_Date is set to UTC or
GMT the option 'fix_dst' will not be
used because these two timezones do not work with DST.
When you change the timezone for this instance again to a timezone which is not
UTC or GMT the previous set 'fix_dst' option
will be used again for date "math".
When adding or substracting months from an existing date, the resulting value for
the day of the month might be unexpected, if the original date fell on a day close
to the end of the month. For example, when adding one month to January 31st, people
familiar with SQL will expect February 28th as the result. On the
other side, people familiar with Excel and OpenOffice will expect March 3rd as the
result. The problem only occurs, if the resulting month does not have the day, which
is set in the original date. For Zend Framework developers, the desired behavior is
selectable using the extend_month option to choose either the
SQL behaviour, if set to
FALSE, or the
spreadsheet behaviour when set to
TRUE. The default behaviour
for extend_month is
behavior compatible to SQL. By default,
Zend_Date computes month calculations by truncating dates to
the end of the month (if necessary), without wrapping into the next month when the
original date designates a day of the month exceeding the number of days in the
resulting month. Use
true)) to make month calculations work like popular spreadsheet
You can speed up
Zend_Date by using an
Zend_Cache adapter. This speeds up all methods of
Zend_Date when you are using localized data. For example all
methods which accept
Zend_Date::TIME constants would benefit from this. To set an
Zend_Cache adapter to
Zend_Date::setOptions(array('cache' => $adapter)).
Normally the clocks from servers and computers differ from each other.
Zend_Date is able to handle such problems with the help of
Zend_TimeSync. You can set a timeserver with
Zend_Date::setOptions(array('timesync' => $timeserver))
which will set the offset between the own actual timestamp and the real actual
timestamp for all instances of
Zend_Date. Using this option
does not change the timestamp of existing instances. So best usage is to set it
within the bootstrap file.
Once input has been normalized via the creation of a
object, it will have an associated timezone, but an internal representation using
standard UNIX timestamps.
In order for a date to be rendered in a localized manner, a timezone must be known
first. The default timezone is always GMT or UTC.
To examine an object's timezone use
getTimeZone(). To change an
object's timezone, use
setTimeZone(). All manipulations of
these objects are assumed to be relative to this timezone.
Beware of mixing and matching operations with date parts between date objects for
different timezones, which generally produce undesireable results, unless the
manipulations are only related to the timestamp. Operating on
Zend_Date objects having different timezones generally works,
except as just noted, since dates are normalized to UNIX timestamps
on instantiation of
Most methods expect a constant selecting the desired
$part of a date,
Zend_Date::HOUR. These constants are valid for all of the
functions below. A list of all available constants is provided in
list of all constants.
Zend_Date::TIMESTAMP is assumed. Alternatively, a
user-specified format may be used for
$part, using the same
underlying mechanism and format codes as
If a date object is constructed using an obviously invalid date (e.g. a month number
greater than 12), then
Zend_Date will throw an exception, unless
no specific date format has been selected -i.e.
$part is either
Zend_Date::DATES (a "loose" format).
Example 26.8. User-Specified Input Date Format
$date1 = new Zend_Date('Feb 31, 2007', null, 'en_US');
echo $date1, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"
$date2 = new Zend_Date('Feb 31, 2007', Zend_Date::DATES, 'en_US');
echo $date2, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"
// strictly restricts interpretation to specified format
$date3 = new Zend_Date('Feb 31, 2007', 'MM.dd.yyyy');
echo $date3, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"
If the optional
$locale parameter is provided, then the
$locale disambiguates the
$date operand by
replacing month and weekday names for string
$date operands, and even
parsing date strings expressed according to the conventions of that locale (see
The automatic normalization of localized
$date operands of a
string type occurs when
$part is one of the
constants. The locale identifies which language should be used to parse month names and
weekday names, if the
$date is a string containing a date. If there
$date input parameter, then the
parameter specifies the locale to use for localizing output (e.g. the date format for a
string representation). Note that the
$date input parameter might
actually have a type name instead (e.g.
addHour()), although that does not prevent the use of
Zend_Date objects as arguments for that parameter. If no
$locale was specified, then the locale of the current object is used
$date, or select the localized format for output.
Since Zend Framework 1.7.0
Zend_Date does also support the usage
of an application wide locale. You can simply set a
instance to the registry like shown below. With this notation you can forget about
setting the locale manually with each instance when you want to use the same locale
// in your bootstrap file
$locale = new Zend_Locale('de_AT');
// somewhere in your application
$date = new Zend_Date('31.Feb.2007');
set() operate generically on dates. In each case, the
operation is performed on the date held in the instance object. The
$date operand is required for all of these methods, except
get(), and may be a
object, a numeric string, or an integer. These methods assume
is a timestamp, if it is not an object. However, the
controls which logical part of the two dates are operated on, allowing operations on
parts of the object's date, such as year or minute, even when
contains a long form date string, such as, "December 31, 2007 23:59:59". The result of
the operation changes the date in the object, except for
Example 26.9. Operating on Parts of Dates
$date = new Zend_Date(); // $date's timestamp === time()
// changes $date by adding 12 hours
Convenience methods exist for each combination of the basic operations and several
common date parts as shown in the tables below. These convenience methods help us lazy
programmers avoid having to type out the date
part constants when using the general methods above. Conveniently, they are
named by combining a prefix (name of a basic operation) with a suffix (type of date
part), such as
addYear(). In the list below, all combinations
of "Date Parts" and "Basic Operations" exist. For example, the operation "add" exists
for each of these date parts, including
These convenience methods have the same equivalent functionality as the basic operation
methods, but expect string and integer
$date operands containing only
the values representing the type indicated by the suffix of the convenience method.
Thus, the names of these methods (e.g. "Year" or "Minute") identify the units of the
$date operand, when
$date is a string or integer.
Table 26.1. Date Parts
|Timestamp||UNIX timestamp, expressed in seconds elapsed since January 1st, 1970 00:00:00 GMT.|
|Year||Gregorian calendar year (e.g. 2006)|
|Month||Gregorian calendar month (1-12, localized names supported)|
|24 hour clock||Hours of the day (0-23) denote the hours elapsed, since the start of the day.|
|minute||Minutes of the hour (0-59) denote minutes elapsed, since the start of the hour.|
|Second||Seconds of the minute (0-59) denote the elapsed seconds, since the start of the minute.|
Milliseconds denote thousandths of a second (0-999).
Weekdays are represented numerically as 0 (for Sunday) through 6
Arpa dates (i.e. RFC 822 formatted dates) are
supported. Output uses either a "GMT" or "Local differential
hours+min" format (see section 5 of RFC 822).
Before PHP 5.2.2, using the
|Iso||Only complete ISO 8601 dates are supported for output. Example: 2009-02-14T00:31:30+01:00|
The basic operations below can be used instead of the convenience operations for
specific date parts, if the
is used for the
Table 26.2. Basic Operations
Returns a cloned object, with only
The following basic operations do not have corresponding convenience methods for the date parts listed in Zend_Date API Overview.
Table 26.3. Date Comparison Methods
Tests if today's year, month, and day match this object's date value, using this object's timezone.
Tests if tomorrow's year, month, and day match this object's date value, using this object's timezone.
Tests if yesterday's year, month, and day match this object's date value, using this object's timezone.
This method checks if a given date is a real date and returns
Several methods support retrieving values related to a
Table 26.4. Date Output Methods
Invoke directly or via the magic method
Returns an array representation of the selected date according to the conventions of the object's locale. The returned array is equivalent to PHP's getdate() function and includes:
Returns an integer representation of the selected date
This method returns the
This convenience function is equivalent to new
Zend_Date(). It returns the current date as a
Several methods support retrieving values related to a
Table 26.5. Date Output Methods
||Return the precision of the part seconds|
||Set the precision of the part seconds|
Three methods provide access to geographically localized information about the Sun, including the time of sunrise and sunset.
Table 26.6. Miscellaneous Methods
||Return the date's time of sunrise|
||Return the date's time of sunset|
||Return an array with the date's sun dates|