<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.locale.date.datesandtimes">

    <title>Working with Dates and Times</title>

    <para>
        <classname>Zend_Locale_Format</classname> provides several methods for working with dates and times to help convert and
        normalize between different formats for different locales. Use <classname>Zend_Date</classname> for manipulating dates,
        and working with date strings that already conform to
        <link linkend="zend.date.constants">one of the many internationally recognized standard formats, or one of the localized date formats supported by <classname>Zend_Date</classname>
        </link>
        . Using an existing, pre-defined format offers advantages, including the use of well-tested code, and the
        assurance of some degree of portability and interoperability (depending on the standard used). The examples
        below do not follow these recommendations, since using non-standard date formats would needlessly increase the
        difficulty of understanding these examples.
    </para>

    <sect2 id="zend.locale.date.normalize">

        <title>Normalizing Dates and Times</title>

        <para>
            The <code>getDate()</code> method parses strings containing dates in localized formats. The results are
            returned in a structured array, with well-defined keys for each part of the date. In addition, the array
            will contain a key 'date_format' showing the format string used to parse the input date string. Since a
            localized date string may not contain all parts of a date/time, the key-value pairs are optional. For
            example, if only the year, month, and day is given, then all time values are suppressed from the returned
            array, and vice-versa if only hour, minute, and second were given as input. If no date or time can be found
            within the given input, an exception will be thrown.
        </para>

        <para>
            If <code>setOption(array('fix_date' => true))</code> is set the <code>getDate()</code> method adds a key 'fixed'
            with a whole number value indicating if the input date string required "fixing" by rearranging the day,
            month, or year in the input to fit the format used.
        </para>

        <table id="zend.locale.date.normalize.table-1">
            <title>Key values for getDate() with option 'fix_date'</title>
            <tgroup cols='2'>
                <thead>
                    <row>
                        <entry>value</entry>
                        <entry>meaning</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>0</entry>
                        <entry>nothing to fix</entry>
                    </row>
                    <row>
                        <entry>1</entry>
                        <entry>fixed false month</entry>
                    </row>
                    <row>
                        <entry>2</entry>
                        <entry>swapped day and year</entry>
                    </row>
                    <row>
                        <entry>3</entry>
                        <entry>swapped month and year</entry>
                    </row>
                    <row>
                        <entry>4</entry>
                        <entry>swapped month and day</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            For those needing to specify explicitly the format of the date string, the following format token specifiers
            are supported. If an invalid format specifier is used, such as the PHP 'i' specifier when in ISO format
            mode, then an error will be thrown by the methods in <classname>Zend_Locale_Format</classname> that support user-defined formats.
        </para>

        <para>
            These specifiers (below) are a small subset of the full "ISO" set supported by <classname>Zend_Date</classname>'s
            <code>toString()</code>. If you need to use PHP <code>date()</code> compatible format specifiers, then first
            call <code>setOptions(array('format_type' => 'php'))</code>. And if you want to convert only one special format
            string from PHP <code>date()</code> compatible format to "ISO" format use <code>convertPhpToIsoFormat()</code>.
            Currently, the only practical difference relates to the specifier for minutes ('m' using the ISO default,
            and 'i' using the PHP date format).
        </para>

        <table id="zend.locale.date.normalize.table-2">
            <title>Return values</title>
            <tgroup cols='5'>
                <thead>
                    <row>
                        <entry>getDate() format character</entry>
                        <entry>Array key</entry>
                        <entry>Returned value</entry>
                        <entry>Minimum</entry>
                        <entry>Maximum</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>d</entry>
                        <entry>day</entry>
                        <entry>integer</entry>
                        <entry>1</entry>
                        <entry>31</entry>
                    </row>
                    <row>
                        <entry>M</entry>
                        <entry>month</entry>
                        <entry>integer</entry>
                        <entry>1</entry>
                        <entry>12</entry>
                    </row>
                    <row>
                        <entry>y</entry>
                        <entry>year</entry>
                        <entry>integer</entry>
                        <entry>no limit</entry>
                        <entry>PHP integer's maximum</entry>
                    </row>
                    <row>
                        <entry>h</entry>
                        <entry>hour</entry>
                        <entry>integer</entry>
                        <entry>0</entry>
                        <entry>PHP integer's maximum</entry>
                    </row>
                    <row>
                        <entry>m</entry>
                        <entry>minute</entry>
                        <entry>integer</entry>
                        <entry>0</entry>
                        <entry>PHP integer's maximum</entry>
                    </row>
                    <row>
                        <entry>s</entry>
                        <entry>second</entry>
                        <entry>integer</entry>
                        <entry>0</entry>
                        <entry>PHP integer's maximum</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <example id="zend.locale.date.normalize.example-1">
            <title>Normalizing a date</title>
            <programlisting language="php"><![CDATA[
$dateString = Zend_Locale_Format::getDate('13.04.2006',
                                          array('date_format' =>
                                                    'dd.MM.yyyy')
                                         );

// creates a Zend_Date object for this date
$dateObject = Zend_Date('13.04.2006',
                         array('date_format' => 'dd.MM.yyyy'));

print_r($dateString); // outputs:

Array
(
    [format] => dd.MM.yyyy
    [day] => 13
    [month] => 4
    [year] => 2006
)

// alternatively, some types of problems with input data can be
// automatically corrected
$date = Zend_Locale_Format::getDate('04.13.2006',
                                    array('date_format' => 'dd.MM.yyyy',
                                          'fix_date' => true)
                                   );

print_r($date); // outputs:

Array
(
    [format] => dd.MM.yyyy
    [day] => 13
    [month] => 4
    [year] => 2006
    [fixed] => 4
)
]]></programlisting>
        </example>

        <para>
            Since <code>getDate()</code> is "locale-aware", specifying the <code>$locale</code> is sufficient for date
            strings adhering to that locale's format. The option '<code>fix_date</code>' uses simple tests to
            determine if the day or month is not valid, and then applies heuristics to try and correct any detected
            problems. Note the use of '<classname>Zend_Locale_Format::STANDARD</classname>' as the value for
            '<code>date_format</code>' to prevent the use of a class-wide default date format set using
            <code>setOptions()</code>. This forces getDate to use the default date format for <code>$locale</code>.
        </para>

        <example id="zend.locale.date.normalize.example-2">
            <title>Normalizing a date by locale</title>
            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$date = Zend_Locale_Format::getDate('13.04.2006',
                                    array('date_format' =>
                                              Zend_Locale_Format::STANDARD,
                                          'locale' => $locale)
                                   );

print_r ($date);
]]></programlisting>
        </example>

        <para>
            A complete date and time is returned when the input contains both a date and time in the expected format.
        </para>

        <example id="zend.locale.date.normalize.example-3">
            <title>Normalizing a date with time</title>
            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$date = Zend_Locale_Format::getDate('13.04.2005 22:14:55',
                                    array('date_format' =>
                                                Zend_Locale_Format::STANDARD,
                                          'locale' => $locale)
                                    );

print_r ($date);
]]></programlisting>
        </example>

        <para>
            If a specific format is desired, specify the <code>$format</code> argument, without giving a
            <code>$locale</code>. Only single-letter codes (H, m, s, y, M, d), and MMMM and EEEE are supported in the
            <code>$format</code>.
        </para>

        <example id="zend.locale.date.normalize.example-4">
            <title>Normalizing a userdefined date</title>
            <programlisting language="php"><![CDATA[
$date = Zend_Locale_Format::getDate('13200504T551422',
                                    array('date_format' =>
                                              'ddyyyyMM ssmmHH')
                                   );

print_r ($date);
]]></programlisting>
        </example>

        <para>
            The format can include the following signs :
        </para>

        <table id="zend.locale.date.normalize.table-3">
            <title>Format definition</title>
            <tgroup cols='2'>
                <thead>
                    <row>
                        <entry>Format Letter</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>d or dd</entry>
                        <entry>1 or 2 digit day</entry>
                    </row>
                    <row>
                        <entry>M or MM</entry>
                        <entry>1 or 2 digit month</entry>
                    </row>
                    <row>
                        <entry>y or yy</entry>
                        <entry>1 or 2 digit year</entry>
                    </row>
                    <row>
                        <entry>yyyy</entry>
                        <entry>4 digit year</entry>
                    </row>
                    <row>
                        <entry>h</entry>
                        <entry>1 or 2 digit hour</entry>
                    </row>
                    <row>
                        <entry>m</entry>
                        <entry>1 or 2 digit minute</entry>
                    </row>
                    <row>
                        <entry>s</entry>
                        <entry>1 or 2 digit second</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Examples for proper formats are
        </para>

        <table id="zend.locale.date.normalize.table-4">
            <title>Example formats</title>
            <tgroup cols='3'>
                <thead>
                    <row>
                        <entry>Formats</entry>
                        <entry>Input</entry>
                        <entry>Output</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>dd.MM.yy</entry>
                        <entry>1.4.6</entry>
                        <entry>['day'] => 1,
                                   ['month'] => 4,
                                   ['year'] => 6</entry>
                    </row>
                    <row>
                        <entry>dd.MM.yy</entry>
                        <entry>01.04.2006</entry>
                        <entry>['day'] => 1, ['month'] => 4, ['year'] => 2006</entry>
                    </row>
                    <row>
                        <entry>yyyyMMdd</entry>
                        <entry>1.4.6</entry>
                        <entry>['day'] => 6, ['month'] => 4, ['year'] => 1</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <title>Database date format</title>
            <para>
                To parse a database date value (f.e. MySql or MsSql), use <classname>Zend_Date</classname>'s ISO_8601 format instead of
                getDate().
            </para>
        </note>

        <para>
            The option '<code>fix_date</code>' uses simple tests to determine if the day or month is not
            valid, and then applies heuristics to try and correct any detected problems. <code>getDate()</code>
            automatically detects and corrects some kinds of problems with input, such as misplacing the year:
        </para>

        <example id="zend.locale.date.normalize.example-5">
            <title>Automatic correction of input dates</title>
            <programlisting language="php"><![CDATA[
$date = Zend_Locale_Format::getDate('41.10.20',
                                    array('date_format' => 'ddMMyy',
                                          'fix_date' => true)
                                   );

// instead of 41 for the day, the 41 will be returned as year value
print_r ($date);
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.date.test">

        <title>Testing Dates</title>

        <para>
            Use <code>checkDateFormat($inputString, array('date_format' => $format, $locale))</code> to check if a given string
            contains all expected date parts. The <code>checkDateFormat()</code> method uses <code>getDate()</code>, but without
            the option <code>'fixdate'</code> to avoid returning true when the input fails to conform to the date
            format. If errors are detected in the input, such as swapped values for months and days, the
            option <code>'fixdate'</code> method will apply heuristics to "correct" dates before determining their
            validity.
        </para>

        <example id="zend.locale.date.test.example-1">
            <title>Date testing</title>
            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
// using the default date format for 'de_AT', is this a valid date?
if (Zend_Locale_Format::checkDateFormat('13.Apr.2006',
                                        array('date_format' =>
                                                  Zend_Locale_Format::STANDARD,
                                              $locale)
                                       ) {
    print "date";
} else {
    print "not a date";
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.time.normalizing">

        <title>Normalizing a Time</title>

        <para>
            Normally, a time will be returned with a date, if the input contains both. If the proper format is not
            known, but the locale relevant to the user input is known, then <code>getTime()</code> should be used,
            because it uses the default time format for the selected locale.
        </para>

        <example id="zend.locale.time.normalizing.example-1">
            <title>Normalize an unknown time</title>
            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
if (Zend_Locale_Format::getTime('13:44:42',
                                array('date_format' =>
                                          Zend_Locale_Format::STANDARD,
                                      'locale' => $locale)) {
    print "time";
} else {
    print "not a time";
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.time.test">

        <title>Testing Times</title>

        <para>
            Use <code>checkDateFormat()</code> to check if a given string contains a proper time.
            The usage is exact the same as with checking Dates, only <code>date_format</code>
            should contain the parts which you expect to have.
        </para>

        <example id="zend.locale.time.test.example-1">
            <title>Testing a time</title>
            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
if (Zend_Locale_Format::checkDateFormat('13:44:42',
                                        array('date_format' => 'HH:mm:ss',
                                              'locale' => $locale)) {
    print "time";
} else {
    print "not a time";
}
]]></programlisting>
        </example>

    </sect2>

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