| blob | ab4ce17b00cc337bb3b3cbf10e017bc96217890b |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.date.overview">
4 <title>Zend_Date API Overview</title>
6 <para>
7 While the <classname>Zend_Date</classname> <acronym>API</acronym> remains simplistic and
8 unitary, its design remains flexible and powerful through the rich permutations of
9 operations and operands.
10 </para>
12 <sect2 id="zend.date.options">
13 <title>Zend_Date Options</title>
15 <sect3 id="zend.date.options.formattype">
16 <title>Selecting the Date Format Type</title>
18 <para>
19 Several methods use date format strings, in a way similar to
20 <acronym>PHP</acronym>'s <methodname>date()</methodname>. If you are more
21 comfortable with <acronym>PHP</acronym>'s date format specifier than with
22 <acronym>ISO</acronym> format specifiers, then you can use
23 <methodname>Zend_Date::setOptions(array('format_type' => 'php'))</methodname>.
24 Afterward, use <acronym>PHP</acronym>'s date format specifiers for all functions
25 which accept a <varname>$format</varname> parameter. Use
26 <methodname>Zend_Date::setOptions(array('format_type' => 'iso'))</methodname> to
27 switch back to the default mode of supporting only <acronym>ISO</acronym> date
28 format tokens. For a list of supported format codes, see
29 <link linkend="zend.date.constants.phpformats">Self-Defined OUTPUT Formats
30 Using PHP's date() Format Specifiers</link>
31 </para>
32 </sect3>
34 <sect3 id="zend.date.options.fixdst">
35 <title>DST and Date Math</title>
37 <para>
38 When dates are manipulated, sometimes they cross over a <acronym>DST</acronym>
39 change, normally resulting in the date losing or gaining an hour. For exmaple, when
40 adding months to a date before a <acronym>DST</acronym> change, if the resulting
41 date is after the <acronym>DST</acronym> change, then the resulting date will appear
42 to lose or gain an hour, resulting in the time value of the date changing. For
43 boundary dates, such as midnight of the first or last day of a month, adding enough
44 months to cross a date boundary results in the date losing an hour and becoming the
45 last hour of the preceding month, giving the appearance of an "off by 1" error. To
46 avoid this situation, the <acronym>DST</acronym> change ignored by using the
47 <property>fix_dst</property> option. When crossing the Summer or Winter
48 <acronym>DST</acronym> boundary, normally an hour is substracted or added depending
49 on the date. For example, date math crossing the Spring <acronym>DST</acronym> leads
50 to a date having a day value one less than expected, if the time part of the date
51 was originally 00:00:00. Since <classname>Zend_Date</classname> is based on
52 timestamps, and not calendar dates with a time component, the timestamp loses an
53 hour, resulting in the date having a calendar day value one less than expected. To
54 prevent such problems use the option <property>fix_dst</property>, which defaults to
55 <constant>TRUE</constant>, causing <acronym>DST</acronym> to have no effect on date
56 "math" (<methodname>addMonth()</methodname>, <methodname>subMonth()</methodname>).
57 Use <methodname>Zend_Date::setOptions(array('fix_dst' => false))</methodname> to
58 enable the subtraction or addition of the <acronym>DST</acronym> adjustment when
59 performing date "math".
60 </para>
62 <para>
63 <emphasis>If your actual timezone within the instance of
64 <classname>Zend_Date</classname> is set to <acronym>UTC</acronym> or
65 <acronym>GMT</acronym> the option '<property>fix_dst</property>' will not be
66 used</emphasis> because these two timezones do not work with <acronym>DST</acronym>.
67 When you change the timezone for this instance again to a timezone which is not
68 <acronym>UTC</acronym> or <acronym>GMT</acronym> the previous set 'fix_dst' option
69 will be used again for date "math".
70 </para>
71 </sect3>
73 <sect3 id="zend.date.options.extendmonth">
74 <title>Month Calculations</title>
76 <para>
77 When adding or substracting months from an existing date, the resulting value for
78 the day of the month might be unexpected, if the original date fell on a day close
79 to the end of the month. For example, when adding one month to January 31st, people
80 familiar with <acronym>SQL</acronym> will expect February 28th as the result. On the
81 other side, people familiar with Excel and OpenOffice will expect March 3rd as the
82 result. The problem only occurs, if the resulting month does not have the day, which
83 is set in the original date. For Zend Framework developers, the desired behavior is
84 selectable using the <property>extend_month</property> option to choose either the
85 <acronym>SQL</acronym> behaviour, if set to <constant>FALSE</constant>, or the
86 spreadsheet behaviour when set to <constant>TRUE</constant>. The default behaviour
87 for <property>extend_month</property> is <constant>FALSE</constant>, providing
88 behavior compatible to <acronym>SQL</acronym>. By default,
89 <classname>Zend_Date</classname> computes month calculations by truncating dates to
90 the end of the month (if necessary), without wrapping into the next month when the
91 original date designates a day of the month exceeding the number of days in the
92 resulting month. Use <methodname>Zend_Date::setOptions(array('extend_month' =>
93 true))</methodname> to make month calculations work like popular spreadsheet
94 programs.
95 </para>
96 </sect3>
98 <sect3 id="zend.date.options.cache">
99 <title>Speed up Date Localization and Normalization with Zend_Cache</title>
101 <para>
102 You can speed up <classname>Zend_Date</classname> by using an
103 <classname>Zend_Cache</classname> adapter. This speeds up all methods of
104 <classname>Zend_Date</classname> when you are using localized data. For example all
105 methods which accept <constant>Zend_Date::DATE</constant> and
106 <constant>Zend_Date::TIME</constant> constants would benefit from this. To set an
107 <classname>Zend_Cache</classname> adapter to <classname>Zend_Date</classname> just
108 use <methodname>Zend_Date::setOptions(array('cache' => $adapter))</methodname>.
109 </para>
110 </sect3>
112 <sect3 id="zend.date.options.timesync">
113 <title>Receiving Syncronised Timestamps with Zend_TimeSync</title>
115 <para>
116 Normally the clocks from servers and computers differ from each other.
117 <classname>Zend_Date</classname> is able to handle such problems with the help of
118 <classname>Zend_TimeSync</classname>. You can set a timeserver with
119 <methodname>Zend_Date::setOptions(array('timesync' => $timeserver))</methodname>
120 which will set the offset between the own actual timestamp and the real actual
121 timestamp for all instances of <classname>Zend_Date</classname>. Using this option
122 does not change the timestamp of existing instances. So best usage is to set it
123 within the bootstrap file.
124 </para>
125 </sect3>
126 </sect2>
128 <sect2 id="zend.date.values">
129 <title>Working with Date Values</title>
131 <para>
132 Once input has been normalized via the creation of a <classname>Zend_Date</classname>
133 object, it will have an associated timezone, but an internal representation using
134 standard <ulink url="http://en.wikipedia.org/wiki/Unix_Time">UNIX timestamps</ulink>.
135 In order for a date to be rendered in a localized manner, a timezone must be known
136 first. The default timezone is always <acronym>GMT</acronym> or <acronym>UTC</acronym>.
137 To examine an object's timezone use <methodname>getTimeZone()</methodname>. To change an
138 object's timezone, use <methodname>setTimeZone()</methodname>. All manipulations of
139 these objects are assumed to be relative to this timezone.
140 </para>
142 <para>
143 Beware of mixing and matching operations with date parts between date objects for
144 different timezones, which generally produce undesireable results, unless the
145 manipulations are only related to the timestamp. Operating on
146 <classname>Zend_Date</classname> objects having different timezones generally works,
147 except as just noted, since dates are normalized to <acronym>UNIX</acronym> timestamps
148 on instantiation of <classname>Zend_Date</classname>.
149 </para>
151 <para>
152 Most methods expect a constant selecting the desired <varname>$part</varname> of a date,
153 such as <constant>Zend_Date::HOUR</constant>. These constants are valid for all of the
154 functions below. A list of all available constants is provided in
155 <link linkend="zend.date.constants.list">list of all constants</link>.
156 If no <varname>$part</varname> is
157 specified, then <constant>Zend_Date::TIMESTAMP</constant> is assumed. Alternatively, a
158 user-specified format may be used for <varname>$part</varname>, using the same
159 underlying mechanism and format codes as <link
160 linkend="zend.locale.date.normalize"><methodname>Zend_Locale_Format::getDate()</methodname></link>.
161 If a date object is constructed using an obviously invalid date (e.g. a month number
162 greater than 12), then <classname>Zend_Date</classname> will throw an exception, unless
163 no specific date format has been selected -i.e. <varname>$part</varname> is either
164 <constant>NULL</constant> or <constant>Zend_Date::DATES</constant> (a "loose" format).
165 </para>
167 <example id="zend.date.values.example-1">
168 <title>User-Specified Input Date Format</title>
170 <programlisting language="php"><![CDATA[
171 $date1 = new Zend_Date('Feb 31, 2007', null, 'en_US');
172 echo $date1, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"
174 $date2 = new Zend_Date('Feb 31, 2007', Zend_Date::DATES, 'en_US');
175 echo $date2, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"
177 // strictly restricts interpretation to specified format
178 $date3 = new Zend_Date('Feb 31, 2007', 'MM.dd.yyyy');
179 echo $date3, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"
180 ]]></programlisting>
181 </example>
183 <para>
184 If the optional <varname>$locale</varname> parameter is provided, then the
185 <varname>$locale</varname> disambiguates the <varname>$date</varname> operand by
186 replacing month and weekday names for string <varname>$date</varname> operands, and even
187 parsing date strings expressed according to the conventions of that locale (see
188 <link linkend="zend.locale.date.normalize">Zend_Locale_Format::getDate()</link>).
189 The automatic normalization of localized <varname>$date</varname> operands of a
190 string type occurs when <varname>$part</varname> is one of the
191 <constant>Zend_Date::DATE</constant>* or <constant>Zend_Date::TIME</constant>*
192 constants. The locale identifies which language should be used to parse month names and
193 weekday names, if the <varname>$date</varname> is a string containing a date. If there
194 is no <varname>$date</varname> input parameter, then the <varname>$locale</varname>
195 parameter specifies the locale to use for localizing output (e.g. the date format for a
196 string representation). Note that the <varname>$date</varname> input parameter might
197 actually have a type name instead (e.g. <varname>$hour</varname> for
198 <methodname>addHour()</methodname>), although that does not prevent the use of
199 <classname>Zend_Date</classname> objects as arguments for that parameter. If no
200 <varname>$locale</varname> was specified, then the locale of the current object is used
201 to interpret <varname>$date</varname>, or select the localized format for output.
202 </para>
204 <para>
205 Since Zend Framework 1.7.0 <classname>Zend_Date</classname> does also support the usage
206 of an application wide locale. You can simply set a <classname>Zend_Locale</classname>
207 instance to the registry like shown below. With this notation you can forget about
208 setting the locale manually with each instance when you want to use the same locale
209 multiple times.
210 </para>
212 <programlisting language="php"><![CDATA[
213 // in your bootstrap file
214 $locale = new Zend_Locale('de_AT');
215 Zend_Registry::set('Zend_Locale', $locale);
217 // somewhere in your application
218 $date = new Zend_Date('31.Feb.2007');
219 ]]></programlisting>
220 </sect2>
222 <sect2 id="id.date.basic">
223 <title>Basic Zend_Date Operations Common to Many Date Parts</title>
225 <para>
226 The methods <methodname>add()</methodname>, <methodname>sub()</methodname>,
227 <methodname>compare()</methodname>, <methodname>get()</methodname>, and
228 <methodname>set()</methodname> operate generically on dates. In each case, the
229 operation is performed on the date held in the instance object. The
230 <varname>$date</varname> operand is required for all of these methods, except
231 <methodname>get()</methodname>, and may be a <classname>Zend_Date</classname> instance
232 object, a numeric string, or an integer. These methods assume <varname>$date</varname>
233 is a timestamp, if it is not an object. However, the <varname>$part</varname> operand
234 controls which logical part of the two dates are operated on, allowing operations on
235 parts of the object's date, such as year or minute, even when <varname>$date</varname>
236 contains a long form date string, such as, "December 31, 2007 23:59:59". The result of
237 the operation changes the date in the object, except for
238 <methodname>compare()</methodname>, and <methodname>get()</methodname>.
239 </para>
241 <example id="zend.date.basic.example-1">
242 <title>Operating on Parts of Dates</title>
244 <programlisting language="php"><![CDATA[
245 $date = new Zend_Date(); // $date's timestamp === time()
247 // changes $date by adding 12 hours
248 $date->add('12', Zend_Date::HOUR);
249 print $date;
250 ]]></programlisting>
251 </example>
253 <para>
254 Convenience methods exist for each combination of the basic operations and several
255 common date parts as shown in the tables below. These convenience methods help us lazy
256 programmers avoid having to type out the <link linkend="zend.date.constants.list">date
257 part constants</link> when using the general methods above. Conveniently, they are
258 named by combining a prefix (name of a basic operation) with a suffix (type of date
259 part), such as <methodname>addYear()</methodname>. In the list below, all combinations
260 of "Date Parts" and "Basic Operations" exist. For example, the operation "add" exists
261 for each of these date parts, including <methodname>addDay()</methodname>,
262 <methodname>addYear()</methodname>, etc.
263 </para>
265 <para>
266 These convenience methods have the same equivalent functionality as the basic operation
267 methods, but expect string and integer <varname>$date</varname> operands containing only
268 the values representing the type indicated by the suffix of the convenience method.
269 Thus, the names of these methods (e.g. "Year" or "Minute") identify the units of the
270 <varname>$date</varname> operand, when <varname>$date</varname> is a string or integer.
271 </para>
273 <sect3 id="id.date.basic.parts">
274 <title>List of Date Parts</title>
276 <table id="id.date.basic.parts.table">
277 <title>Date Parts</title>
279 <tgroup cols="2">
280 <thead>
281 <row>
282 <entry>Date Part</entry>
283 <entry>Explanation</entry>
284 </row>
285 </thead>
287 <tbody>
288 <row>
289 <entry>
290 <ulink
291 url="http://en.wikipedia.org/wiki/Unix_Time">Timestamp</ulink>
292 </entry>
294 <entry>
295 UNIX timestamp, expressed in seconds elapsed since January 1st, 1970
296 00:00:00 <acronym>GMT</acronym>.
297 </entry>
298 </row>
300 <row>
301 <entry>
302 <ulink
303 url="http://en.wikipedia.org/wiki/Gregorian_calendar">Year</ulink>
304 </entry>
306 <entry>Gregorian calendar year (e.g. 2006)</entry>
307 </row>
309 <row>
310 <entry>
311 <ulink
312 url="http://en.wikipedia.org/wiki/Month#Julian_and_Gregorian_calendars">Month</ulink>
313 </entry>
315 <entry>
316 Gregorian calendar month (1-12, localized names supported)
317 </entry>
318 </row>
320 <row>
321 <entry>
322 <ulink
323 url="http://en.wikipedia.org/wiki/24-hour_clock">24 hour
324 clock</ulink>
325 </entry>
327 <entry>
328 Hours of the day (0-23) denote the hours elapsed, since the start of
329 the day.
330 </entry>
331 </row>
333 <row>
334 <entry>
335 <ulink url="http://en.wikipedia.org/wiki/Minute">minute</ulink>
336 </entry>
338 <entry>
339 Minutes of the hour (0-59) denote minutes elapsed, since the start
340 of the hour.
341 </entry>
342 </row>
344 <row>
345 <entry>
346 <ulink url="http://en.wikipedia.org/wiki/Second">Second</ulink>
347 </entry>
349 <entry>
350 Seconds of the minute (0-59) denote the elapsed seconds, since the
351 start of the minute.
352 </entry>
353 </row>
355 <row>
356 <entry>
357 <ulink
358 url="http://en.wikipedia.org/wiki/Millisecond">millisecond</ulink>
359 </entry>
361 <entry>
362 Milliseconds denote thousandths of a second (0-999).
363 <classname>Zend_Date</classname> supports two additional methods
364 for working with time units smaller than seconds. By default,
365 <classname>Zend_Date</classname> instances use a precision
366 defaulting to milliseconds, as seen using
367 <methodname>getFractionalPrecision()</methodname>. To change the
368 precision use
369 <methodname>setFractionalPrecision($precision)</methodname>.
370 However, precision is limited practically to microseconds, since
371 <classname>Zend_Date</classname> uses <ulink
372 url="http://php.net/microtime">microtime()</ulink>.
373 </entry>
374 </row>
376 <row>
377 <entry>
378 <ulink url="http://en.wikipedia.org/wiki/Day">Day</ulink>
379 </entry>
381 <entry>
382 <constant>Zend_Date::DAY_SHORT</constant> is extracted from
383 <varname>$date</varname> if the <varname>$date</varname> operand is
384 an instance of <classname>Zend_Date</classname> or a numeric string.
385 Otherwise, an attempt is made to extract the day according to the
386 conventions documented for these constants:
387 <constant>Zend_Date::WEEKDAY_NARROW</constant>,
388 <constant>Zend_Date::WEEKDAY_NAME</constant>,
389 <constant>Zend_Date::WEEKDAY_SHORT</constant>,
390 <constant>Zend_Date::WEEKDAY</constant> (Gregorian calendar
391 assumed)
392 </entry>
393 </row>
395 <row>
396 <entry>
397 <ulink url="http://en.wikipedia.org/wiki/Week">Week</ulink>
398 </entry>
400 <entry>
401 <constant>Zend_Date::WEEK</constant> is extracted from
402 <varname>$date</varname> if the <varname>$date</varname> operand is
403 an instance of <classname>Zend_Date</classname> or a numeric string.
404 Otherwise an exception is raised. (Gregorian calendar assumed)
405 </entry>
406 </row>
408 <row>
409 <entry>Date</entry>
411 <entry>
412 <constant>Zend_Date::DAY_MEDIUM</constant> is extracted from
413 <varname>$date</varname> if the <varname>$date</varname> operand is
414 an instance of <classname>Zend_Date</classname>. Otherwise, an
415 attempt is made to normalize the <varname>$date</varname> string
416 into a <constant>Zend_Date::DATE_MEDIUM</constant> formatted date.
417 The format of <constant>Zend_Date::DAY_MEDIUM</constant> depends on
418 the object's locale.
419 </entry>
420 </row>
422 <row>
423 <entry>Weekday</entry>
425 <entry>
426 Weekdays are represented numerically as 0 (for Sunday) through 6
427 (for Saturday). <constant>Zend_Date::WEEKDAY_DIGIT</constant> is
428 extracted from <varname>$date</varname>, if the
429 <varname>$date</varname> operand is an instance of
430 <classname>Zend_Date</classname> or a numeric string. Otherwise, an
431 attempt is made to extract the day according to the conventions
432 documented for these constants:
433 <constant>Zend_Date::WEEKDAY_NARROW</constant>,
434 <constant>Zend_Date::WEEKDAY_NAME</constant>,
435 <constant>Zend_Date::WEEKDAY_SHORT</constant>,
436 <constant>Zend_Date::WEEKDAY</constant> (Gregorian calendar
437 assumed)
438 </entry>
439 </row>
441 <row>
442 <entry>DayOfYear</entry>
444 <entry>
445 In <classname>Zend_Date</classname>, the day of the year represents
446 the number of calendar days elapsed since the start of the year
447 (0-365). As with other units above, fractions are rounded down to
448 the nearest whole number. (Gregorian calendar assumed)
449 </entry>
450 </row>
452 <row>
453 <entry>
454 <ulink url="http://www.faqs.org/rfcs/rfc822.html">Arpa</ulink>
455 </entry>
457 <entry>
458 Arpa dates (i.e. <acronym>RFC</acronym> 822 formatted dates) are
459 supported. Output uses either a "GMT" or "Local differential
460 hours+min" format (see section 5 of <acronym>RFC</acronym> 822).
461 Before <acronym>PHP</acronym> 5.2.2, using the
462 <constant>DATE_RFC822</constant> constant with
463 <acronym>PHP</acronym> date functions sometimes produces <ulink
464 url="http://bugs.php.net/bug.php?id=40308">incorrect
465 results</ulink>. <classname>Zend_Date</classname>'s results are
466 correct. Example: Mon, 31 Dec 06 23:59:59 <acronym>GMT</acronym>
467 </entry>
468 </row>
470 <row>
471 <entry>
472 <ulink url="http://en.wikipedia.org/wiki/ISO_8601">Iso</ulink>
473 </entry>
475 <entry>
476 Only complete <acronym>ISO</acronym> 8601 dates are supported for
477 output. Example: 2009-02-14T00:31:30+01:00
478 </entry>
479 </row>
480 </tbody>
481 </tgroup>
482 </table>
483 </sect3>
485 <sect3 id="id.date.basic.operations">
486 <title>List of Date Operations</title>
488 <para>
489 The basic operations below can be used instead of the convenience operations for
490 specific date parts, if the
491 <link linkend="zend.date.constants.list">appropriate constant</link>
492 is used for the <varname>$part</varname> parameter.
493 </para>
495 <table id="id.date.basic.operations.table">
496 <title>Basic Operations</title>
498 <tgroup cols="2">
499 <thead>
500 <row>
501 <entry>Basic Operation</entry>
502 <entry>Explanation</entry>
503 </row>
504 </thead>
506 <tbody>
507 <row>
508 <entry><methodname>get()</methodname></entry>
510 <entry>
511 <para>
512 <emphasis><methodname>get($part = null, $locale =
513 null)</methodname></emphasis>
514 </para>
516 <para>
517 Use <methodname>get($part)</methodname> to retrieve the date
518 <varname>$part</varname> of this object's date localized to
519 <varname>$locale</varname> as a formatted string or integer.
520 When using the BCMath extension, numeric strings might be
521 returned instead of integers for large values.
522 </para>
524 <note>
525 <title>Behaviour of get()</title>
527 <para>
528 Unlike <methodname>get()</methodname>, the other
529 get*() convenience methods only return instances of
530 <classname>Zend_Date</classname> containing a date
531 representing the selected or computed date or time.
532 </para>
533 </note>
534 </entry>
535 </row>
537 <row>
538 <entry><methodname>set()</methodname></entry>
540 <entry>
541 <para>
542 <emphasis><methodname>set($date, $part = null, $locale =
543 null)</methodname></emphasis>
544 </para>
546 <para>
547 Sets the <varname>$part</varname> of the current object to the
548 corresponding value for that part found in the input
549 <varname>$date</varname> having a locale
550 <varname>$locale</varname>.
551 </para>
552 </entry>
553 </row>
555 <row>
556 <entry><methodname>add()</methodname></entry>
558 <entry>
559 <para>
560 <emphasis><methodname>add($date, $part = null, $locale =
561 null)</methodname></emphasis>
562 </para>
564 <para>
565 Adds the <varname>$part</varname> of <varname>$date</varname>
566 having a locale <varname>$locale</varname> to the current
567 object's date.
568 </para>
569 </entry>
570 </row>
572 <row>
573 <entry><methodname>sub()</methodname></entry>
575 <entry>
576 <para>
577 <emphasis><methodname>sub($date, $part = null, $locale =
578 null)</methodname></emphasis>
579 </para>
581 <para>
582 Subtracts the <varname>$part</varname> of
583 <varname>$date</varname> having a locale
584 <varname>$locale</varname> from the current object's date.
585 </para>
586 </entry>
587 </row>
589 <row>
590 <entry><methodname>copyPart()</methodname></entry>
592 <entry>
593 <para>
594 <emphasis><methodname>copyPart($part, $locale =
595 null)</methodname></emphasis>
596 </para>
598 <para>
599 Returns a cloned object, with only <varname>$part</varname> of
600 the object's date copied to the clone, with the clone have its
601 locale arbitrarily set to <varname>$locale</varname> (if
602 specified).
603 </para>
604 </entry>
605 </row>
607 <row>
608 <entry><methodname>compare()</methodname></entry>
610 <entry>
611 <para>
612 <emphasis><methodname>compare($date, $part = null, $locale =
613 null)</methodname></emphasis>
614 </para>
616 <para>
617 compares <varname>$part</varname> of <varname>$date</varname> to
618 this object's timestamp, returning 0 if they are equal, 1 if
619 this object's part was more recent than
620 <varname>$date</varname>'s part, otherwise -1.
621 </para>
622 </entry>
623 </row>
624 </tbody>
625 </tgroup>
626 </table>
627 </sect3>
628 </sect2>
630 <sect2 id="zend.date.others.comparison">
631 <title>Comparing Dates</title>
633 <para>
634 The following basic operations do not have corresponding convenience methods for the
635 date parts listed in <link linkend="zend.date.overview">Zend_Date API Overview</link>.
636 </para>
638 <table id="zend.date.others.comparison.table">
639 <title>Date Comparison Methods</title>
641 <tgroup cols="2">
642 <thead>
643 <row>
644 <entry>Method</entry>
645 <entry>Explanation</entry>
646 </row>
647 </thead>
649 <tbody>
650 <row>
651 <entry><methodname>equals()</methodname></entry>
653 <entry>
654 <para>
655 <emphasis><methodname>equals($date, $part = null, $locale =
656 null)</methodname></emphasis>
657 </para>
659 <para>
660 returns <constant>TRUE</constant>, if <varname>$part</varname> of
661 <varname>$date</varname> having locale <varname>$locale</varname> is
662 the same as this object's date <varname>$part</varname>, otherwise
663 <constant>FALSE</constant>
664 </para>
665 </entry>
666 </row>
668 <row>
669 <entry><methodname>isEarlier()</methodname></entry>
671 <entry>
672 <para>
673 <emphasis><methodname>isEarlier($date, $part = null, $locale =
674 null)</methodname></emphasis>
675 </para>
677 <para>
678 returns <constant>TRUE</constant>, if <varname>$part</varname> of
679 this object's date is earlier than <varname>$part</varname> of
680 <varname>$date</varname> having a locale <varname>$locale</varname>
681 </para>
682 </entry>
683 </row>
685 <row>
686 <entry><methodname>isLater()</methodname></entry>
688 <entry>
689 <para>
690 <emphasis><methodname>isLater($date, $part = null, $locale =
691 null)</methodname></emphasis>
692 </para>
694 <para>
695 returns <constant>TRUE</constant>, if <varname>$part</varname> of
696 this object's date is later than <varname>$part</varname> of
697 <varname>$date</varname> having a locale <varname>$locale</varname>
698 </para>
699 </entry>
700 </row>
702 <row>
703 <entry><methodname>isToday()</methodname></entry>
705 <entry>
706 <para>
707 <emphasis><methodname>isToday()</methodname></emphasis>
708 </para>
710 <para>
711 Tests if today's year, month, and day match this object's date
712 value, using this object's timezone.
713 </para>
714 </entry>
715 </row>
717 <row>
718 <entry><methodname>isTomorrow()</methodname></entry>
720 <entry>
721 <para>
722 <emphasis><methodname>isTomorrow()</methodname></emphasis>
723 </para>
725 <para>
726 Tests if tomorrow's year, month, and day match this object's date
727 value, using this object's timezone.
728 </para>
729 </entry>
730 </row>
732 <row>
733 <entry><methodname>isYesterday()</methodname></entry>
735 <entry>
736 <para>
737 <emphasis><methodname>isYesterday()</methodname></emphasis>
738 </para>
740 <para>
741 Tests if yesterday's year, month, and day match this object's date
742 value, using this object's timezone.
743 </para>
744 </entry>
745 </row>
747 <row>
748 <entry><methodname>isLeapYear()</methodname></entry>
750 <entry>
751 <para>
752 <emphasis><methodname>isLeapYear()</methodname></emphasis>
753 </para>
755 <para>
756 Use <methodname>isLeapYear()</methodname> to determine if the
757 current object is a leap year, or use
758 <methodname>Zend_Date::checkLeapYear($year)</methodname> to check
759 <varname>$year</varname>, which can be a string, integer, or
760 instance of <classname>Zend_Date</classname>. Is the year a leap
761 year?
762 </para>
763 </entry>
764 </row>
766 <row>
767 <entry><methodname>isDate()</methodname></entry>
769 <entry>
770 <para>
771 <emphasis><methodname>isDate($date, $format = null, $locale =
772 null)</methodname></emphasis>
773 </para>
775 <para>
776 This method checks if a given date is a real date and returns
777 <constant>TRUE</constant> if all checks are ok. It works like
778 <acronym>PHP</acronym>'s <methodname>checkdate()</methodname>
779 function but can also check for localized month names and for dates
780 extending the range of <methodname>checkdate()</methodname>
781 </para>
782 </entry>
783 </row>
784 </tbody>
785 </tgroup>
786 </table>
787 </sect2>
789 <sect2 id="zend.date.others.gettingparts">
790 <title>Getting Dates and Date Parts</title>
792 <para>
793 Several methods support retrieving values related to a <classname>Zend_Date</classname>
794 instance.
795 </para>
797 <table id="zend.date.others.gettingparts.table">
798 <title>Date Output Methods</title>
800 <tgroup cols="2">
801 <thead>
802 <row>
803 <entry>Method</entry>
804 <entry>Explanation</entry>
805 </row>
806 </thead>
808 <tbody>
809 <row>
810 <entry><methodname>toString()</methodname></entry>
812 <entry>
813 <para>
814 <emphasis><methodname>toString($format = null, $locale =
815 null)</methodname></emphasis>
816 </para>
818 <para>
819 Invoke directly or via the magic method
820 <methodname>__toString()</methodname>. The
821 <methodname>toString()</methodname> method automatically formats
822 the date object's value according to the conventions of the
823 object's locale, or an optionally specified
824 <varname>$locale</varname>. For a list of supported format codes,
825 see <link
826 linkend="zend.date.constants.selfdefinedformats">Self-Defined
827 OUTPUT Formats with ISO</link>.
828 </para>
829 </entry>
830 </row>
832 <row>
833 <entry><methodname>toArray()</methodname></entry>
835 <entry>
836 <para>
837 <emphasis><methodname>toArray()</methodname></emphasis>
838 </para>
840 <para>
841 Returns an array representation of the selected date according to
842 the conventions of the object's locale. The returned array is
843 equivalent to <acronym>PHP</acronym>'s <ulink
844 url="http://php.net/getdate">getdate()</ulink> function and
845 includes:
846 </para>
848 <itemizedlist>
849 <listitem>
850 <para>
851 Number of day as '<emphasis>day</emphasis>'
852 (<constant>Zend_Date::DAY_SHORT</constant>)
853 </para>
854 </listitem>
856 <listitem>
857 <para>
858 Number of month as '<emphasis>month</emphasis>'
859 (<constant>Zend_Date::MONTH_SHORT</constant>)
860 </para>
861 </listitem>
863 <listitem>
864 <para>
865 Year as '<emphasis>year</emphasis>'
866 (<constant>Zend_Date::YEAR</constant>)
867 </para>
868 </listitem>
870 <listitem>
871 <para>
872 Hour as '<emphasis>hour</emphasis>'
873 (<constant>Zend_Date::HOUR_SHORT</constant>)
874 </para>
875 </listitem>
877 <listitem>
878 <para>
879 Minute as '<emphasis>minute</emphasis>'
880 (<constant>Zend_Date::MINUTE_SHORT</constant>)
881 </para>
882 </listitem>
884 <listitem>
885 <para>
886 Second as '<emphasis>second</emphasis>'
887 (<constant>Zend_Date::SECOND_SHORT</constant>)
888 </para>
889 </listitem>
891 <listitem>
892 <para>
893 Abbreviated timezone as '<emphasis>timezone</emphasis>'
894 (<constant>Zend_Date::TIMEZONE</constant>)
895 </para>
896 </listitem>
898 <listitem>
899 <para>
900 Unix timestamp as '<emphasis>timestamp</emphasis>'
901 (<constant>Zend_Date::TIMESTAMP</constant>)
902 </para>
903 </listitem>
905 <listitem>
906 <para>
907 Number of weekday as '<emphasis>weekday</emphasis>'
908 (<constant>Zend_Date::WEEKDAY_DIGIT</constant>)
909 </para>
910 </listitem>
912 <listitem>
913 <para>
914 Day of year as '<emphasis>dayofyear</emphasis>'
915 (<constant>Zend_Date::DAY_OF_YEAR</constant>)
916 </para>
917 </listitem>
919 <listitem>
920 <para>
921 Week as '<emphasis>week</emphasis>'
922 (<constant>Zend_Date::WEEK</constant>)
923 </para>
924 </listitem>
926 <listitem>
927 <para>
928 Delay of timezone to <acronym>GMT</acronym> as
929 '<emphasis>gmtsecs</emphasis>'
930 (<constant>Zend_Date::GMT_SECS</constant>)
931 </para>
932 </listitem>
933 </itemizedlist>
934 </entry>
935 </row>
937 <row>
938 <entry><methodname>toValue()</methodname></entry>
940 <entry>
941 <para>
942 <emphasis><methodname>toValue($part = null)</methodname></emphasis>
943 </para>
945 <para>
946 Returns an integer representation of the selected date
947 <varname>$part</varname> according to the conventions of the
948 object's locale. Returns <constant>FALSE</constant> when
949 <varname>$part</varname> selects a non-numeric value, such as
950 <constant>Zend_Date::MONTH_NAME_SHORT</constant>.
951 </para>
953 <note>
954 <title>Limitation of toValue()</title>
956 <para>
957 This method calls <link
958 linkend="id.date.basic.operations"><methodname>get()</methodname></link>
959 and casts the result to a <acronym>PHP</acronym> integer, which
960 will give unpredictable results, if
961 <methodname>get()</methodname> returns a numeric string
962 containing a number too large for a <acronym>PHP</acronym>
963 integer on your system. Use <methodname>get()</methodname>
964 instead.
965 </para>
966 </note>
967 </entry>
968 </row>
970 <row>
971 <entry>
972 <link linkend="id.date.basic.operations">get()</link>
973 </entry>
975 <entry>
976 <para>
977 <emphasis><methodname>get($part = null, $locale =
978 null)</methodname></emphasis>
979 </para>
981 <para>
982 This method returns the <varname>$part</varname> of object's date
983 localized to <varname>$locale</varname> as a formatted string or
984 integer. See <link linkend="id.date.basic.operations">get()</link>
985 for more information.
986 </para>
987 </entry>
988 </row>
990 <row>
991 <entry><methodname>now()</methodname></entry>
993 <entry>
994 <para>
995 <emphasis><methodname>now($locale = null)</methodname></emphasis>
996 </para>
998 <para>
999 This convenience function is equivalent to <command>new
1000 Zend_Date()</command>. It returns the current date as a
1001 <classname>Zend_Date</classname> object, having
1002 <varname>$locale</varname>
1003 </para>
1004 </entry>
1005 </row>
1006 </tbody>
1007 </tgroup>
1008 </table>
1009 </sect2>
1011 <sect2 id="zend.date.others.fractions">
1012 <title>Working with Fractions of Seconds</title>
1014 <para>
1015 Several methods support retrieving values related to a <classname>Zend_Date</classname>
1016 instance.
1017 </para>
1019 <table id="zend.date.others.fractions.table">
1020 <title>Date Output Methods</title>
1022 <tgroup cols="2">
1023 <thead>
1024 <row>
1025 <entry>Method</entry>
1026 <entry>Explanation</entry>
1027 </row>
1028 </thead>
1030 <tbody>
1031 <row>
1032 <entry>
1033 <para>
1034 <emphasis><methodname>getFractionalPrecision()</methodname></emphasis>
1035 </para>
1036 </entry>
1038 <entry>Return the precision of the part seconds</entry>
1039 </row>
1041 <row>
1042 <entry>
1043 <para>
1044 <emphasis><methodname>setFractionalPrecision()</methodname></emphasis>
1045 </para>
1046 </entry>
1048 <entry>Set the precision of the part seconds</entry>
1049 </row>
1050 </tbody>
1051 </tgroup>
1052 </table>
1053 </sect2>
1055 <sect2 id="zend.date.other.sun">
1056 <title>Sunrise / Sunset</title>
1058 <para>
1059 Three methods provide access to geographically localized information about the Sun,
1060 including the time of sunrise and sunset.
1061 </para>
1063 <table id="zend.date.other.sun.table">
1064 <title>Miscellaneous Methods</title>
1066 <tgroup cols="2">
1067 <thead>
1068 <row>
1069 <entry>Method</entry>
1070 <entry>Explanation</entry>
1071 </row>
1072 </thead>
1074 <tbody>
1075 <row>
1076 <entry>
1077 <para>
1078 <emphasis><methodname>getSunrise($location)</methodname></emphasis>
1079 </para>
1080 </entry>
1082 <entry>Return the date's time of sunrise</entry>
1083 </row>
1085 <row>
1086 <entry>
1087 <para>
1088 <emphasis><methodname>getSunset($location)</methodname></emphasis>
1089 </para>
1090 </entry>
1092 <entry>Return the date's time of sunset</entry>
1093 </row>
1095 <row>
1096 <entry>
1097 <para>
1098 <emphasis><methodname>getSunInfo($location)</methodname></emphasis>
1099 </para>
1100 </entry>
1102 <entry>Return an array with the date's sun dates</entry>
1103 </row>
1104 </tbody>
1105 </tgroup>
1106 </table>
1107 </sect2>
1108 </sect1>
1109 <!--
1110 vim:se ts=4 sw=4 et:
1111 -->