Zend_Date API Overview
While the Zend_Date API remains simplistic and unitary, its design
remains flexible and powerful through the rich permutations of operations and operands.
Zend_Date Options
DST and Date Math
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/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 "math" ( addMonth(),
subMonth()). Use
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".
Month Calculations
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 FALSE, providing 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
Zend_Date::setOptions(array('extend_month' => true)); to make
month calculations work like popular spreadsheet programs.
Speed up Date Localization and Normalization with Zend_Cache
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::DATE and
Zend_Date::TIME constants would benefit from this. To set an
Zend_Cache adapter to Zend_Date just
use Zend_Date::setOptions(array('cache' => $adapter));.
Receiving Syncronised Timestamps with Zend_TimeSync
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.
Working with Date Values
Once input has been normalized via the creation of a Zend_Date
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/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
Zend_Date.
Most methods expect a constant selecting the desired $part of a date,
such as 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. If no $part is
specified, then Zend_Date::TIMESTAMP is assumed. Alternatively, a
user-specified format may be used for $part, using the same
underlying mechanism and format codes as Zend_Locale_Format::getDate().
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
NULL or Zend_Date::DATES (a "loose" format).
Example #1 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
Zend_Locale_Format::getDate()
). The automatic normalization of localized $date operands of a
string type occurs when $part is one of the
Zend_Date::DATE* or Zend_Date::TIME*
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
is no $date input parameter, then the $locale
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. $hour for
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
to interpret $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 Zend_Locale
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
multiple times.
// in your bootstrap file
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);
// somewhere in your application
$date = new Zend_Date('31.Feb.2007');
Basic Zend_Date Operations Common to Many Date Parts
The methods add(), sub(),
compare(), get(), and
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 Zend_Date instance
object, a numeric string, or an integer. These methods assume $date
is a timestamp, if it is not an object. However, the $part operand
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 $date
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
compare(), and get().
Example #2 Operating on Parts of Dates
$date = new Zend_Date(); // $date's timestamp === time()
// changes $date by adding 12 hours
$date->add('12', Zend_Date::HOUR);
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 addDay(),
addYear(), etc.
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.
List of Date Parts
Date Parts
Date Part |
Explanation |
» Timestamp
|
UNIX timestamp, expressed in seconds elapsed since January 1st, 1970
00:00:00 GMT/UTC.
|
» 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.
|
» millisecond
|
Milliseconds denote thousandths of a second (0-999).
Zend_Date supports two additional methods
for working with time units smaller than seconds. By default,
Zend_Date instances use a precision
defaulting to milliseconds, as seen using
getFractionalPrecision(). To change the
precision use
setFractionalPrecision($precision).
However, precision is limited practically to microseconds, since
Zend_Date uses » microtime() .
|
» Day
|
Zend_Date::DAY_SHORT is extracted from
$date if the $date operand is
an instance of Zend_Date or a numeric string.
Otherwise, an attempt is made to extract the day according to the
conventions documented for these constants:
Zend_Date::WEEKDAY_NARROW,
Zend_Date::WEEKDAY_NAME,
Zend_Date::WEEKDAY_SHORT,
Zend_Date::WEEKDAY (Gregorian calendar
assumed)
|
» Week
|
Zend_Date::WEEK is extracted from
$date if the $date operand is
an instance of Zend_Date or a numeric string.
Otherwise an exception is raised. (Gregorian calendar assumed)
|
Date |
Zend_Date::DAY_MEDIUM is extracted from
$date if the $date operand is
an instance of Zend_Date. Otherwise, an
attempt is made to normalize the $date string
into a Zend_Date::DATE_MEDIUM formatted date. The format of
Zend_Date::DAY_MEDIUM depends on the object's
locale.
|
Weekday |
Weekdays are represented numerically as 0 (for Sunday) through 6
(for Saturday). Zend_Date::WEEKDAY_DIGIT is
extracted from $date, if the
$date operand is an instance of
Zend_Date or a numeric string. Otherwise, an
attempt is made to extract the day according to the conventions
documented for these constants:
Zend_Date::WEEKDAY_NARROW,
Zend_Date::WEEKDAY_NAME,
Zend_Date::WEEKDAY_SHORT,
Zend_Date::WEEKDAY (Gregorian calendar
assumed)
|
DayOfYear |
In Zend_Date, the day of the year represents
the number of calendar days elapsed since the start of the year
(0-365). As with other units above, fractions are rounded down to
the nearest whole number. (Gregorian calendar assumed)
|
» Arpa
|
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 DATE_RFC822 constant with
PHP date functions sometimes produces » incorrect
results. Zend_Date's results are correct. Example:
Mon, 31 Dec 06 23:59:59 GMT
|
» Iso
|
Only complete ISO 8601 dates are supported for output. Example:
2009-02-14T00:31:30+01:00
|
List of Date Operations
The basic operations below can be used instead of the convenience operations for
specific date parts, if the
appropriate constant
is used for the $part parameter.
Basic Operations
Basic Operation |
Explanation |
get() |
get($part = null, $locale = null)
Use get($part) to retrieve the date
$part of this object's date localized to
$locale as a formatted string or integer.
When using the BCMath extension, numeric strings might be
returned instead of integers for large values.
NOTE: Unlike
get(), the other
get*() convenience methods only return instances of
Zend_Date containing a date representing
the selected or computed date/time.
|
set() |
set($date, $part = null, $locale = null)
Sets the $part of the current object to the
corresponding value for that part found in the input
$date having a locale
$locale.
|
add() |
add($date, $part = null, $locale = null)
Adds the $part of $date
having a locale $locale to the current
object's date.
|
sub() |
sub($date, $part = null, $locale = null)
Subtracts the $part of
$date having a locale
$locale from the current object's date.
|
copyPart() |
copyPart($part, $locale = null)
Returns a cloned object, with only $part of
the object's date copied to the clone, with the clone have its
locale arbitrarily set to $locale (if
specified).
|
compare() |
compare($date, $part = null, $locale = null)
compares $part of $date to
this object's timestamp, returning 0 if they are equal, 1 if
this object's part was more recent than $date's part, otherwise
-1.
|
Comparing Dates
The following basic operations do not have corresponding convenience methods for the
date parts listed in Zend_Date API Overview
.
Date Comparison Methods
Method |
Explanation |
equals() |
equals($date, $part = null, $locale = null)
returns TRUE, if $part of
$date having locale $locale is
the same as this object's date $part, otherwise
FALSE
|
isEarlier() |
isEarlier($date, $part = null, $locale = null)
returns TRUE, if $part of this object's date is
earlier than $part of $date
having a locale $locale
|
isLater() |
isLater($date, $part = null, $locale = null)
returns TRUE, if $part of this object's date is
later than $part of $date
having a locale $locale
|
isToday() |
isToday()
Tests if today's year, month, and day match this object's date
value, using this object's timezone.
|
isTomorrow() |
isTomorrow()
Tests if tomorrow's year, month, and day match this object's date
value, using this object's timezone.
|
isYesterday() |
isYesterday()
Tests if yesterday's year, month, and day match this object's date
value, using this object's timezone.
|
isLeapYear() |
isLeapYear()
Use isLeapYear() to determine if the
current object is a leap year, or use
Zend_Date::checkLeapYear($year) to check
$year, which can be a string, integer, or
instance of Zend_Date. Is the year a leap
year?
|
isDate() |
isDate($date, $format = null, $locale = null)
This method checks if a given date is a real date and returns TRUE
if all checks are ok. It works like PHP's checkdate() function but
can also check for localized month names and for dates extending the
range of checkdate() FALSE
|
Getting Dates and Date Parts
Several methods support retrieving values related to a Zend_Date
instance.
Date Output Methods
Method |
Explanation |
toString() |
toString($format = null, $locale = null)
Invoke directly or via the magic method
__toString(). The
toString() method automatically formats
the date object's value according to the conventions of the
object's locale, or an optionally specified
$locale. For a list of supported format codes,
see Self-Defined OUTPUT Formats with ISO.
|
toArray() |
toArray()
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:
-
Number of day as 'day'
(Zend_Date::DAY_SHORT)
-
Number of month as 'month'
(Zend_Date::MONTH_SHORT)
-
Year as 'year'
(Zend_Date::YEAR)
-
Hour as 'hour'
(Zend_Date::HOUR_SHORT)
-
Minute as 'minute'
(Zend_Date::MINUTE_SHORT)
-
Second as 'second'
(Zend_Date::SECOND_SHORT)
-
Abbreviated timezone as 'timezone'
(Zend_Date::TIMEZONE)
-
Unix timestamp as 'timestamp'
(Zend_Date::TIMESTAMP)
-
Number of weekday as 'weekday'
(Zend_Date::WEEKDAY_DIGIT)
-
Day of year as 'dayofyear'
(Zend_Date::DAY_OF_YEAR)
-
Week as 'week'
(Zend_Date::WEEK)
-
Delay of timezone to GMT as
'gmtsecs'
(Zend_Date::GMT_SECS)
|
toValue() |
toValue($part = null)
Returns an integer representation of the selected date
$part according to the conventions of the
object's locale. Returns FALSE when
$part selects a non-numeric value, such as
Zend_Date::MONTH_NAME_SHORT.
NOTE: This method calls get()
and casts the result to a PHP integer, which will give
unpredictable results, if get() returns a
numeric string containing a number too large for a PHP integer on
your system. Use get() instead.
|
get()
|
get($part = null, $locale = null)
This method returns the $part of object's date
localized to $locale as a formatted string or
integer. See List of Date Operations
for more information.
|
now() |
now($locale = null)
This convenience function is equivalent to new
Zend_Date(). It returns the current date as a
Zend_Date object, having
$locale
|
Working with Fractions of Seconds
Several methods support retrieving values related to a Zend_Date
instance.
Date Output Methods
Method |
Explanation |
getFractionalPrecision()
|
Return the precision of the part seconds |
setFractionalPrecision()
|
Set the precision of the part seconds |
Sunrise / Sunset
Three methods provide access to geographically localized information about the Sun,
including the time of sunrise and sunset.
Miscellaneous Methods
Method |
Explanation |
getSunrise($location)
|
Return the date's time of sunrise |
getSunset($location)
|
Return the date's time of sunset |
getSunInfo($location)
|
Return an array with the date's sun dates |
|
|