documentation/manual/en/module_specs/Zend_Date-Introduction.xml

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