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

<?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 PHP or Zend Framework, first make certain
            your application has a correct default timezone, by either setting the TZ environment
            variable, using the <code>date.timezone</code> php.ini setting, or using <ulink
                url="http://php.net/date_default_timezone_set">date_default_timezone_set()</ulink>.
            In PHP, 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>.
            <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>
            <emphasis>When creating Zend_Date instances, their timezone will automatically become
            the current default timezone!</emphasis> Thus, the timezone setting will account for any
            Daylight Savings Time (DST) in effect, eliminating the need to explicitly specify DST.
        </para>

        <para>
            Keep in mind that the timezones <emphasis>UTC</emphasis> and
            <emphasis>GMT</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/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 <code>float</code> type
                    supported by your server. "The size of a float is platform-dependent, although a
                    maximum of ~1.8e308 with a precision of roughly 14 decimal digits is a common
                    value (that's 64 bit IEEE 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,
                    the Zend Framework I18n components use BCMath extension, if available.
                </para>
            </listitem>
            <listitem>
                <para>
                    Support for ISO_8601 date specifications
                </para>
                <para>
                    ISO_8601 date specifications are supported. Even partially compliant ISO_8601
                    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 "Y/m/d" or "Y-m-d H:i:s",
                    according to <acronym>PHP</acronym> date() format tokens, use
                    <classname>Zend_Date</classname>'s built-in support for <acronym>ISO</acronym>
                    8601 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:
-->