1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.date.introduction">
<title>Introduction</title>
<para>
The <classname>Zend_Date</classname> component offers a detailed, but simple
<acronym>API</acronym> for manipulating dates and times. Its methods accept a wide variety
of types of information, including date parts, in numerous combinations yielding many
features and possibilities above and beyond the existing <acronym>PHP</acronym> date related
functions. For the very latest manual updates, please see <ulink
url="http://framework.zend.com/wiki/display/ZFDOCDEV/Home">our online manual (frequently
synced to Subversion)</ulink>.
</para>
<para>
Although simplicity remains the goal, working with localized dates and times while
modifying, combining, and comparing parts involves some unavoidable complexity. Dates, as
well as times, are often written differently in different locales. For example, some place
the month first, while other write the year first when expressing calendar dates. For more
information about handling localization and normalization, please refer to <link
linkend="zend.locale.date.datesandtimes"><classname>Zend_Locale</classname></link>.
</para>
<para>
<classname>Zend_Date</classname> also supports abbreviated names of months in many
languages. <classname>Zend_Locale</classname> facilitates the normalization of localized
month and weekday names to timestamps, which may, in turn, be shown localized to other
regions.
</para>
<sect2 id="zend.date.setdefaulttimezone">
<title>Always Set a Default Timezone</title>
<para>
Before using any date related functions in <acronym>PHP</acronym> or Zend Framework,
first make certain your application has a correct default timezone, by either setting
the TZ environment variable, using the <property>date.timezone</property>
<filename>php.ini</filename> setting, or using <ulink
url="http://php.net/date_default_timezone_set">date_default_timezone_set()</ulink>.
In <acronym>PHP</acronym>, we can adjust all date and time related functions to work for
a particular user by setting a default timezone according to the user's expectations.
For a complete list of timezone settings, see the <ulink
url="http://unicode.org/cldr/data/diff/supplemental/territory_containment_un_m_49.html">CLDR
Timezone Identifier List</ulink>.
</para>
<example id="zend.date.setdefaulttimezone.example-1">
<title>Setting a Default Timezone</title>
<programlisting language="php"><![CDATA[
// timezone for an American in California
date_default_timezone_set('America/Los_Angeles');
// timezone for a German in Germany
date_default_timezone_set('Europe/Berlin');
]]></programlisting>
</example>
<para>
<emphasis>When creating <classname>Zend_Date</classname> instances, their timezone will
automatically become the current default timezone!</emphasis> Thus, the timezone setting
will account for any Daylight Savings Time (<acronym>DST</acronym>) in effect,
eliminating the need to explicitly specify <acronym>DST</acronym>.
</para>
<para>
Keep in mind that the timezones <emphasis><acronym>UTC</acronym></emphasis> and
<emphasis><acronym>GMT</acronym></emphasis> do not include Daylight Saving Time. This
means that even if you define per hand that <classname>Zend_Date</classname> should work
with <acronym>DST</acronym>, it would automatically be switched back for the instances
of <classname>Zend_Date</classname> which have been set to <acronym>UTC</acronym> or
<acronym>GMT</acronym>.
</para>
</sect2>
<sect2 id="zend.date.why">
<title>Why Use Zend_Date?</title>
<para>
<classname>Zend_Date</classname> offers the following features, which extend the scope
of <acronym>PHP</acronym> date functions:
</para>
<itemizedlist mark='opencircle'>
<listitem>
<para>
Simple <acronym>API</acronym>
</para>
<para>
<classname>Zend_Date</classname> offers a very simple <acronym>API</acronym>,
which combines the best of date and time functionality from four programming
languages. It is possible, for example, to add or compare two times within a
single row.
</para>
</listitem>
<listitem>
<para>
Completely internationalized
</para>
<para>
All full and abbreviated names of months and weekdays are supported for more
than 130 languages. Methods support both input and the output of dates using the
localized names of months and weekdays, in the conventional format associated
with each locale.
</para>
</listitem>
<listitem>
<para>
Unlimited timestamps
</para>
<para>
Although <acronym>PHP</acronym> 5.2 docs state, "The valid range of a timestamp
is typically from Fri, 13 Dec 1901 20:45:54 <acronym>GMT</acronym> to Tue, 19
Jan 2038 03:14:07 <acronym>GMT</acronym>," <classname>Zend_Date</classname>
supports a nearly unlimited range, with the help of the BCMath extension. If
BCMath is not available, then <classname>Zend_Date</classname> will have reduced
support only for timestamps within the range of the float type
supported by your server. "The size of a float is platform-dependent, although a
maximum of <command>~1.8e308</command> with a precision of roughly 14 decimal
digits is a common value (that's 64 bit <acronym>IEEE</acronym> format)." [
<ulink url="http://www.php.net/float">http://www.php.net/float</ulink> ].
Additionally, inherent limitations of float data types, and rounding error of
float numbers may introduce errors into calculations. To avoid these problems,
Zend Framework's I18n components use BCMath extension, if available.
</para>
</listitem>
<listitem>
<para>
Support for <acronym>ISO-8601</acronym> date specifications
</para>
<para>
<acronym>ISO-8601</acronym> date specifications are supported. Even partially
compliant <acronym>ISO-8601</acronym> date specifications will be identified.
These date formats are particularly useful when working with databases. for
example, even though MsSQL and <ulink
url="http://dev.mysql.com/doc/refman/5.0/en/date-and-time-functions.html">MySQL</ulink>
differ a little from each other, both are supported by
<classname>Zend_Date</classname> using the <link
linkend="zend.date.constants.list">Zend_Date::ISO_8601</link> format
specification constant. When date strings conform to "<command>Y/m/d</command>"
or "<command>Y-m-d H:i:s</command>", according to <acronym>PHP</acronym>
<methodname>date()</methodname> format tokens, use
<classname>Zend_Date</classname>'s built-in support for
<acronym>ISO-8601</acronym> formatted dates.
</para>
</listitem>
<listitem>
<para>
Calculate sunrise and sunset
</para>
<para>
For any place and day, the times for sunrise and sunset can be displayed, so
that you won't miss a single daylight second for working on your favorite
<acronym>PHP</acronym> project :)
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
|
