repo_zf1/documentation/manual/de/module_specs/Zend_Locale-DatesTimes.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 22752 -->
<!-- Reviewed: no -->
<sect1 id="zend.locale.date.datesandtimes">
    <title>Arbeiten mit Daten und Zeiten</title>

    <para>
        <classname>Zend_Locale_Format</classname> bietet verschiedene Methoden für das Arbeiten mit
        Daten und Zeiten und hilft bei der Konvertierung und Normalisierung zwischen verschiedenen
        Formaten und verschiedenen Gebietsschemata. Für die Manipulation von Datumszeichenketten die
        bereits übereinstimmen mit <link linkend="zend.date.constants">einem der vielen
        international erkannten Standardformate, oder einem der lokalisierten Datumsformat welche
        von <classname>Zend_Date</classname> verwendet werden</link>. Die Verwendung von
        vordefinierten Formate bietet Vorteile, wie die Benutzung von gut getestetem Code, und die
        Sicherheit von Beweglichkeit und Interoperabilität (abhängig vom benutzten Standard). Das
        unten angeführte Beispiel folgt nicht dieser Empfehlung, da die Benutzung von nicht
        standardmäßigen Datumsformaten die Verständlichkeit der Beispiele unnötig erhöhen wurde.
    </para>

    <sect2 id="zend.locale.date.normalize">
        <title>Daten und Zeiten normalisieren</title>

        <para>
            Die Methode <methodname>getDate()</methodname> analysiert Zeichenketten welche Daten in
            einem lokalisierten Format enthalten. Das Ergebnis wird als strukturiertes Array zurück
            gegeben, mit gut definierten Schlüsseln für jeden Teil des Datums. Zusätzlich enthält
            das Array den Schlüssel 'date_format' der den Format String zeigt der benutzt wurde um
            die Zeichenkette mit dem Eingabedatum zu analysieren. Da ein lokalisiertes Datum nicht
            alle Teile eines Datums oder einer Zeit enthalten muß, sind alle Schüssel Paare des
            Arrays optional. Wenn zum Beispiel nur Jahr, Monat und Tag gegeben sind, dann werden
            alle Zeit Werte beim zurückgegebenen Array unterdrückt und umgekehrt wenn nur Stunde,
            Minute und Sekunde als Eingabe angegeben werden. Wenn weder ein Datum noch eine Zeit in
            der Eingabe gefunden werden, dann wird eine Ausnahme geworfen.
        </para>

        <para>
            Wenn <methodname>setOption(array('fix_date' => true))</methodname> gesetzt wird, enthält
            die Methode <methodname>getDate()</methodname> einen Schlüssel 'fixed' der eine Zahl
            enthält welche anzeigt ob die eingegebene Zeichenkette korrigiert wurde indem Tag, Monat
            oder Jahr getauscht wurden um in das Format zu passen das angegeben wurde.
        </para>

        <table id="zend.locale.date.normalize.table-1">
            <title>Schlüsselwerte für getDate() mit der Option 'fix_date'</title>

            <tgroup cols='2'>
                <thead>
                    <row>
                        <entry>Wert</entry>
                        <entry>Bedeutung</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>0</entry>
                        <entry>Nichts korrigiert</entry>
                    </row>

                    <row>
                        <entry>1</entry>
                        <entry>Falsches Monat wurde korrigiert</entry>
                    </row>

                    <row>
                        <entry>2</entry>
                        <entry>Tag und Jahr wurden getauscht</entry>
                    </row>

                    <row>
                        <entry>3</entry>
                        <entry>Monat und Jahr wurden getauscht</entry>
                    </row>

                    <row>
                        <entry>4</entry>
                        <entry>Monat und Tag wurden getauscht</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Für jene die ein spezielles Format für Datumseingaben definieren müssen, werden die
            nachfolgend angegebenen Format Zeichen unterstützt. Wenn ein ungültiges Format Zeichen
            verwendet wird, so wie <acronym>PHP</acronym>'s 'i' Zeichen in einem
            <acronym>ISO</acronym> Format, dann wird ein Fehler von den Methoden, die
            benutzerdefinierte Formate in <classname>Zend_Locale_Format</classname> unterstützen,
            geworfen.
        </para>

        <para>
            Die unten angegebenen Zeichen sind nur ein kleiner Teil des kompletten "ISO" Sets
            welches von <classname>Zend_Date</classname>'s <methodname>toString()</methodname>
            unterstützt werden. Wenn <acronym>PHP</acronym> <methodname>date()</methodname>
            kompatible Format Zeichen benutzt werden müssen, dann muß zuerst
            <methodname>setOptions(array('format_type' => 'php'))</methodname> aufgerufen werden.
            Und wenn eine spezielle Format Zeichenkette vom <acronym>PHP</acronym>
            <methodname>date()</methodname> kompatiblen Format in ein "ISO" Format konvertiert
            werden muß kann <methodname>convertPhpToIsoFormat()</methodname> benutzt werden. Aktuell
            besteht die einzige praktische Differenz darin dass das Zeichen für Minuten
            unterschiedlich ist ('m' wird im <acronym>ISO</acronym> Format und 'i' im
            <acronym>PHP</acronym> date Format verwendet).
        </para>

        <table id="zend.locale.date.normalize.table-2">
            <title>Rückgabewerte</title>

            <tgroup cols='5'>
                <thead>
                    <row>
                        <entry>getDate() Format Zeichen</entry>
                        <entry>Array Schlüssel</entry>
                        <entry>Rückgabewert</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>kein Limit</entry>
                        <entry>PHP's Maximum für Integer</entry>
                    </row>

                    <row>
                        <entry>h</entry>
                        <entry>hour</entry>
                        <entry>Integer</entry>
                        <entry>0</entry>
                        <entry>PHP's Maximum für Integer</entry>
                    </row>

                    <row>
                        <entry>m</entry>
                        <entry>minute</entry>
                        <entry>Integer</entry>
                        <entry>0</entry>
                        <entry>PHP's Maximum für Integer</entry>
                    </row>

                    <row>
                        <entry>s</entry>
                        <entry>second</entry>
                        <entry>Integer</entry>
                        <entry>0</entry>
                        <entry>PHP's Maximum für Integer</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <example id="zend.locale.date.normalize.example-1">
            <title>Normalisieren von Daten</title>

            <programlisting language="php"><![CDATA[
$dateString = Zend_Locale_Format::getDate('13.04.2006',
                                          array('date_format' =>
                                                    'dd.MM.yyyy')
                                         );

// Erstellt ein Zend_Date Objekt für dieses Datum
$dateObject = Zend_Date('13.04.2006',
                        array('date_format' => 'dd.MM.yyyy'));

print_r($dateString); // Ausgabe

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

// Alternativ können einige Arten von Problemen mit
// den Eingabedaten automatisch korrigiert werden
$date = Zend_Locale_Format::getDate('04.13.2006',
                                    array('date_format' => 'dd.MM.yyyy',
                                          'fix_date' => true)
                                   );

print_r($date); // Ausgabe

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

        <para>
            Da <methodname>getDate()</methodname> "lokalisierbar" ist, ist die Angabe von
            <varname>$locale</varname> ausreichend um Datumseingaben einem Gebietsschema Format
            zuzuordnen. Die Option '<property>fix_date</property>' verwendet einfache Tests um
            herauszufinden ob Tag oder Monat ungültig sind, um dann eine Heuristik anzuwenden die
            versucht alle gefundenen Probleme zu korrigieren. Anzumerken ist auch die Verwendung von
            '<constant>Zend_Locale_Format::STANDARD</constant>' als Wert für
            '<property>date_format</property>' bei der Funktion
            <methodname>setOptions()</methodname> um zu verhindern dass das klassenweit gesetzte
            standardmäßige Datumsformat verwendet wird. Das zwingt getDate dazu das standardmäßige
            Datumsformat dieser <varname>$locale</varname> zu verwenden.
        </para>

        <example id="zend.locale.date.normalize.example-2">
            <title>Normalisieren eines Datums durch ein Gebietsschema</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>
            Ein komplettes Datum mit Uhrzeit wird zurückgegeben, wenn die Eingabe beides, ein Datum
            und eine Uhrzeit, um erwarteten Format enthält.
        </para>

        <example id="zend.locale.date.normalize.example-3">
            <title>Normalisieren eines Datums mit Uhrzeit</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>
            Wenn ein spezielles Format gewünscht ist, muß das <varname>$format</varname> Argument
            definiert werden, ohne der Angabe von <varname>$locale</varname>. Nur die einzelnen
            Zeichen (H, m, s, y, M, d), und MMMM und EEEE werden bei <varname>$format</varname>
            unterstützt.
        </para>

        <example id="zend.locale.date.normalize.example-4">
            <title>Normalisieren eines Benutzerdefinierten Datums</title>

            <programlisting language="php"><![CDATA[
$date = Zend_Locale_Format::getDate('13200504T551422',
                                    array('date_format' =>
                                              'ddyyyyMM ssmmHH')
                                   );

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

        <para>
            Ein Format kann die folgenden Zeichen enthalten:
        </para>

        <table id="zend.locale.date.normalize.table-3">
            <title>Format Definition</title>

            <tgroup cols='2'>
                <thead>
                    <row>
                        <entry>Format Buchstabe</entry>
                        <entry>Beschreibung</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>d oder dd</entry>
                        <entry>Tag mit 1 oder 2 Ziffern</entry>
                    </row>

                    <row>
                        <entry>M oder MM</entry>
                        <entry>Monat mit 1 oder 2 Ziffern</entry>
                    </row>

                    <row>
                        <entry>y oder yy</entry>
                        <entry>Jahr mit 1 or 2 Ziffern</entry>
                    </row>

                    <row>
                        <entry>yyyy</entry>
                        <entry>Jahr mit 4 Ziffern</entry>
                    </row>

                    <row>
                        <entry>h</entry>
                        <entry>Stunde mit 1 oder 2 Ziffern</entry>
                    </row>

                    <row>
                        <entry>m</entry>
                        <entry>Minute mit 1 oder 2 Ziffern</entry>
                    </row>

                    <row>
                        <entry>s</entry>
                        <entry>Sekunde mit 1 oder 2 Ziffern</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Beispiele für gültige Formate sind
        </para>

        <table id="zend.locale.date.normalize.table-4">
            <title>Beispielformate</title>

            <tgroup cols='3'>
                <thead>
                    <row>
                        <entry>Formate</entry>
                        <entry>Eingabe</entry>
                        <entry>Ausgabe</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>Datumsformate für Datenbanken</title>
            <para>
                Um einen Datumswert einer Datenbank zu analysieren (zum Beispiel MySql oder MsSql)
                sollte <classname>Zend_Date</classname>'s ISO_8601 Format statt
                getDate() benutzt werden.
            </para>
        </note>

        <para>
            Die Option '<property>fix_date</property>' benutzt einfache Tests um herauszufinden ob
            der Tag oder das Monat ungültig sind, und wendet dann eine Heuristik an die versucht die
            erkannten Probleme zu beheben. <methodname>getDate()</methodname> erkennt und behebt
            automatisch einige Problem mit falschen Eingabe, wie zum Beispiel ein falsch plaziertes
            Jahr:
        </para>

        <example id="zend.locale.date.normalize.example-5">
            <title>Automatische Korrektur von Datumsangaben</title>

            <programlisting language="php"><![CDATA[
$date = Zend_Locale_Format::getDate('41.10.20',
                                    array('date_format' => 'ddMMyy',
                                          'fix_date' => true)
                                   );

// Statt 41 für den Tag wird die 41 als Wert für das Jahr zurück gegeben
print_r ($date);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.date.test">
        <title>Testen von Daten</title>

        <para>
            <methodname>checkDateFormat($inputString, array('date_format' => $format,
                $locale))</methodname> kann benutzt werden um zu prüfen ob eine Zeichenkette alle
            erwarteten Datumsteile enthält. Die Methode <methodname>checkDateFormat()</methodname>
            benutzt <methodname>getDate()</methodname> aber ohne die Verwendung der Option
            '<property>fixdate</property>' um zu verhindern das <constant>TRUE</constant> zurück
            gegeben wird wenn die Eingabe nicht dem Datumsformat entspricht. Wenn Fehler in der
            Eingabe gefunden werden, wie zum Beispiel getauschte Werte für Monat oder Jahr, wendet
            die Option '<property>fixdate</property>' eine Heuristik an um das "richtige" Datum zu
            eruieren bevor dieses auf Gültigkeit geprüft wird.
        </para>

        <example id="zend.locale.date.test.example-1">
            <title>Testen von Daten</title>

            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
// Standard Datumsformate für 'de_AT' benutzen... ist es ein gültiges Datum ?
if (Zend_Locale_Format::checkDateFormat('13.Apr.2006',
                                        array('date_format' =>
                                                  Zend_Locale_Format::STANDARD,
                                              $locale)
                                       ) {
    print "Datum";
} else {
    print "kein Datum";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.time.normalizing">
        <title>Normalisieren von Zeiten</title>

        <para>
            Normalerweise werden Zeiten zusammen mit einem Datum zurückgegeben, wenn die Eingabe
            beide Werte enthält. Wenn das richtige Format nicht bekannt ist, aber das Gebietsschema
            für die Eingabe des Benutzers bekannt ist, sollte <methodname>getTime()</methodname>
            verwendet werden, weil es das standardmäßige Zeitformat für das ausgewählte
            Gebietsschema benutzt.
        </para>

        <example id="zend.locale.time.normalizing.example-1">
            <title>Normalisieren einer unbekannten Zeit</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 "Zeit";
} else {
    print "keine Zeit";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.time.test">
        <title>Testen von Zeiten</title>

        <para>
            <methodname>checkDateFormat()</methodname> kann verwendet werden um zu prüfen ob eine
            Zeichenkette eine gültige Zeit enthält. Die Verwendung ist genau die gleiche wie beim
            Prüfen von Daten und <property>date_format</property> sollte die Teile enthalten von
            denen erwartet wird das man Sie erhält.
        </para>

        <example id="zend.locale.time.test.example-1">
            <title>Testen einer Zeit</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 "Zeit";
} else {
    print "keine Zeit";
}
]]></programlisting>
        </example>
    </sect2>
</sect1>