While the 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 PHP's 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
Раздел 9.6.4, «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/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".
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 ZF 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.
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));.
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 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
Раздел 9.6.2, «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).
Пример 9.8. User-specified input date format
<?php
$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"
$date3 = new Zend_Date('Feb 31, 2007', 'MM.dd.yyyy'); // strictly restricts interpretation to specified format
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.
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().
Пример 9.9. Operating on Parts of Dates
<?php
require_once 'Zend/Date.php';
$date = new Zend_Date(); // $date's timestamp === time()
// changes $date by adding 12 hours
$date->add('12', Zend_Date::HOUR);
print $date;
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.
Таблица 9.1. 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
|
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.
Таблица 9.2. Basic Operations
| Basic Operation | Explanation |
|---|---|
| get() |
get($part = null, $locale = null)
Use |
| set() |
set($date, $part = null, $locale = null)
Sets the |
| add() |
add($date, $part = null, $locale = null)
Adds the |
| sub() |
sub($date, $part = null, $locale = null)
Subtracts the |
| copyPart() |
copyPart($part, $locale = null)
Returns a cloned object, with only |
| compare() |
compare($date, $part = null, $locale = null)
compares |
The following basic operations do not have corresponding convenience methods for the date parts listed in Раздел 9.4, «Zend_Date API Overview» .
Таблица 9.3. Date Comparison Methods
| Method | Explanation |
|---|---|
| equals() |
equals($date, $part = null, $locale = null)
returns true, if |
| isEarlier() |
isEarlier($date, $part = null, $locale = null)
returns true, if |
| isLater() |
isLater($date, $part = null, $locale = null)
returns true, if |
| 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 |
| 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 |
Several methods support retrieving values related to a Zend_Date instance.
Таблица 9.4. Date Output Methods
| Method | Explanation |
|---|---|
| toString() |
toString($format = null, $locale = null)
Invoke directly or via the magic method |
| 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:
|
| toValue() |
toValue($part = null)
Returns an integer representation of the selected date |
| get() |
get($part = null, $locale = null)
This method returns the |
| now() |
now($locale = null)
This convenience function is equivalent to |
Several methods support retrieving values related to a Zend_Date instance.
Таблица 9.5. Date Output Methods
| Method | Explanation |
|---|---|
|
getFractionalPrecision() |
Return the precision of the part seconds |
|
setFractionalPrecision() |
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.
Таблица 9.6. 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 |