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 API 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 PHP 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 role="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 role="strong">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 role="strong">UTC</emphasis> and
            <emphasis role="strong">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 DST, it would automatically
            be switched back for the instances of <classname>Zend_Date</classname> which have been set to UTC or GMT.
        </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 PHP date functions:
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    Simple API
                </para>
                <para>
                    <classname>Zend_Date</classname> offers a very simple API, 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 PHP 5.2 docs state, "The valid range of a timestamp is typically from Fri, 13 Dec 1901
                    20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT," <classname>Zend_Date</classname> supports a nearly unlimited
                    range, with the help of the BCMath extension. If BCMath is not available, then Zend_Date 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 ZF 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
                    PHP date() format tokens, use Zend_Date's built-in support for ISO 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 PHP project :)
                </para>
            </listitem>
        </itemizedlist>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->