Zend Framework 1.10.9 Manual
|
|
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 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 "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
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.
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
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
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).
Ejemplo #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');
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()
.
Ejemplo #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);
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.
| Date Part | Explanation |
|---|---|
| » 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. |
| » 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.
| 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.
|
| 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. |
The following basic operations do not have corresponding convenience methods for the date parts listed in Zend_Date API Overview .
| 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
|
| 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() |
Several methods support retrieving values related to a
Zend_Date
instance.
| 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:
|
| 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 .
|
| 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 get() for more information. |
| now() |
now($locale = null)
This convenience function is equivalent to
new
Zend_Date()
. It returns the current date as a
|
Several methods support retrieving values related to a
Zend_Date
instance.
| 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.
| 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 |
|
|
|