repo_zf1/documentation/manual/de/module_specs/Zend_Date-Additional.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15156 -->
<!-- Reviewed: no -->
<sect1 id="zend.date.additional">

    <title>Funktionierende Beispiele</title>

    <para>
        In diesem Kapitel werden wir verschiedene zusätzliche Funkionen beschreiben welche auch durch
        <classname>Zend_Date</classname> verfügbar sind. Natürlich haben alle beschriebene Funktionen auch Beispiele
        um die Arbeitsweise, und die einfache API für die richtige Benutzung von Ihnen, zu zeigen.
    </para>

    <sect2 id="zend.date.additional.checking">

        <title>Prüfen von Daten</title>

        <para>
            Normalerweise werden die meisten Daten als Zeichenketten übergeben. Aber das Problem mit Zeichenketten
            ist das man nicht sicher sein kann ob eine Zeichenkette ein echtes Datum enthält. Hierfür gibt es
            in <classname>Zend_Date</classname> eine eigene statische Funktion um Datums-Zeichenketten zu prüfen.
            <classname>Zend_Locale</classname> hat eine eigene Funktion <code>getDate($date, $locale);</code> welche ein
            Datum analysiert und die gültigen normalisierten Datumsabschnitte zurück gibt. Ein Monatsname
            wird zum Beispiel erkannt und anschließend nur die Nummer des Monats zurück gegeben. Aber da
            <classname>Zend_Locale</classname> nichts über Daten weiß, da es eine Klasse zum Normalisieren und
            Lokalisieren ist, haben wir eine eigene Funktion <code>isDate($date);</code> integriert welche das
            für uns prüft.
        </para>

        <para>
            <code>isDate($date, $format, $locale);</code> nimmt bis zu drei Parameter entgegen und benötigt mindestens
            einen Parameter. Deshalb ist alles was wir für das Prüfen eines Datums benötigen natürlich das Datum
            selbst als Zeichenkette. Der zweite Parameter kann das Format sein, in welchem das Datum erwartet wird.
            Wenn kein Format angegeben wurde, wird das Standardformat des verwendeten Gebietsschemas benutzt.
            Für Details darüber wie Formate aussehen müssen kann im Kapitel über
            <link linkend="zend.date.constants.selfdefinedformats">selbst definierte Formate</link> nachgeschaut werden.
        </para>

        <para>
            Der dritte Parameter ist auch optional genauso wie der zweite Parameter und kann verwendet werden um
            ein Gebietsschema anzugeben. Das gebietsschema wird benötigt um Monats- und Wochentagsnamen zu
            normalisieren. Mit dem dritten Parameter sind wir also in der Lage Daten zu erkennen wie
            '01.Jänner.2000' oder '01.January.2000' abhängig von dem angegebenen Gebietsschema.
        </para>

        <para>
            <code>isDate();</code> prüft natürlich auch ob ein Datum existiert. <classname>Zend_Date</classname> selbst
            prüft die Daten nicht. Deshalb ist es möglich ein Datum wie zum Beispiel '31.Februar.2000' mit
            <classname>Zend_Date</classname> zu erstellen  weil <classname>Zend_Date</classname> das Datum automatisch korrigiert und
            ein gültiges Datum zurück gibt. In unserem Fall den '03.März.2000'. Auf der anderen Seite führt
            <code>isDate()</code> diese Prüfung durch und gibt beim '31.Februar.2000' falsch zurück, weil sie weiß
            das dieses Datum unmöglich ist.
        </para>

        <example id="zend.date.additional.checking.example-1">
            <title>Prüfen von Daten</title>
            <programlisting role="php"><![CDATA[
// Prüfen des Datums
$date = '01.03.2000';
if (Zend_Date::isDate($date)) {
    print "Zeichenkette $date ist ein Datum";
} else {
    print "Zeichenkette $date ist KEIN Datum";
}

// Prüfen eines lokalisierten Datums
$date = '01 February 2000';
if (Zend_Date::isDate($date,'dd MMMM yyyy', 'en')) {
    print "Zeichenkette $date ist ein Datum";
} else {
    print "Zeichenkette $date ist KEIN Datum";
}

// Prüfen eines unmöglichen Datums
$date = '30 February 2000';
if (Zend_Date::isDate($date,'dd MMMM yyyy', 'en')) {
    print "Zeichenkette $date ist ein Datum";
} else {
    print "Zeichenkette $date ist KEIN Datum";
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.date.additional.sunrise-sunset">

        <title>Sonnenaufgang und Sonnenuntergang</title>

        <para>
            <classname>Zend_Date</classname> beinhaltet auch Funktionen um Informationen von der Sonne zu erhalten. Oft
            ist es notwendig die Zeit für Sonnenaugang oder Sonnenuntergang für einen bestimmten Tag zu erhalten.
            Das ist mit <classname>Zend_Date</classname> sehr einfach weil nur der gewünschte Tag angegeben werden muß, und
            zusätzlich die Ortsangabe für den Sonnenaufgang oder Sonnenuntergang berechnet werden soll.
        </para>

        <para>
            Da die meisten Personen die genaue Ortsangabe Ihrer Stadt nicht kennen haben wir auch eine Helferklasse
            spendiert die für etwa 250 Haupt- und Großstädte der ganzen Welt die Daten der Ortsangaben bereithält.
            Die meisten Personen können Städte in Ihrer näheren Umgebung benutzen, da die Differenz für Ortsangaben
            welche nahe beineinander liegen nur in Sekunden gemessen werden kann.
        </para>

        <para>
            Für die Erstellung einer Auswahlbox und der Auswahl einer speziellen Stadt kann die Funktion
            <classname>Zend_Date_Cities::getCityList</classname>  benutzt werden. Sie gibt die Namen aller verfügbaren
            vordefinierten Städte der Helferklasse zurück.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-1">
            <title>Alle verfügbaren Städte ausgeben</title>
            <programlisting role="php"><![CDATA[
// Ausgabe der kompletten Liste aller verfügbaren Städte
print_r (Zend_Date_Cities::getCityList());
]]></programlisting>
        </example>

        <para>
            Die Ortsangabe selbst erhält man mit der Funktion <classname>Zend_Date_Cities::City()</classname>.
            Sie akzeptiert den Namen einer Stadt wie durch die Funktion <classname>Zend_Date_Cities::getCityList()</classname>
            angegeben und optional als zweiten Parameter den zu setzenden Horizont.
        </para>

        <para>
            Es gibt 4 vordefinierte Horizonte welche mit einer Ortsangabe benutzt werden können um den genauen
            Zeitpunkt von Sonnenauf- und -untergang zu erhalten. Der '<code>horizon</code>' Parameter ist in allen
            Funktionen immer optional. Wenn er nicht gesetzt wird, wird der '<code>effective</code>' Horizont benutzt.
        </para>

        <table id="zend.date.additional.sunrise-sunset.table">
            <title>Arten von unterstützten Horizonten für Sonnenauf- und -untergang</title>
            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Horizont</entry>
                        <entry>Beschreibung</entry>
                        <entry>Verwendung</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>effective</entry>
                        <entry>Standard Horizont</entry>
                        <entry>Nimmt an das die Welt ein Ball ist. Dieser Horizont wird immer benutzt wenn keiner definiert wurde.</entry>
                    </row>
                    <row>
                        <entry>civil</entry>
                        <entry>Üblicher Horizont</entry>
                        <entry>Oft in den üblichen Medien wie Fernsehen und Radio benutzt.</entry>
                    </row>
                    <row>
                        <entry>nautic</entry>
                        <entry>Nautischer Horizont</entry>
                        <entry>Oft in der Navigation zu See benutzt.</entry>
                    </row>
                    <row>
                        <entry>astronomic</entry>
                        <entry>Astronomischer Horizont</entry>
                        <entry>Oft bei der Berechnung mit Sternen benutzt</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Natürlich kann auch eine selbst-definierte Ortsangabe für die Berechnung benutzt werden. Hierzu ist eine
            '<code>latitude</code>' und eine '<code>longitude</code>' anzugeben und optional der '<code>horizon</code>'.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-2">
            <title>Die Ortsangabe für eine Stadt auslesen</title>
            <programlisting role="php"><![CDATA[
// Die Ortsangabe für eine bestimmte Stadt auslesen
// Benutzt den effektiven Horizont da kein Horizont angegeben wurde
print_r (Zend_Date_Cities::City('Vienna'));

// Benutzt den nautischen Horizont
print_r (Zend_Date_Cities::City('Vienna', 'nautic'));

// Selbstdefinition einer Ortsangabe
$mylocation = array('latitude' => 41.5, 'longitude' => 13.2446);
]]></programlisting>
        </example>

        <para>
            Da nun alle benötigten Daten angegeben werde können ist der nächste Schritt die Erstellung eines
            <classname>Zend_Date</classname> Objekts mit dem Tag für welchen Sonnenauf- oder -untergang berechnet werden sollen.
            Für die Berechnung stehen 3 Funktionen bereit. Die Berechnung des Sonnenaufganges ist mit
            '<code>getSunset()</code>', des Sonnenuntergangs mit '<code>getSunrise()</code>' und alle
            möglichen Informationen welche die Sonne betreffen mit '<code>getSunInfo()</code>' möglich.
            Nach der Berechnung wird das <classname>Zend_Date</classname> Objekt mit der berechneten Zeit zurückgegeben.
        </para>

        <example id="zend.date.additional.sunrise-sunset.example-3">
            <title>Berechnung von Sonneninformationen</title>
            <programlisting role="php"><![CDATA[
// Die Ortsangabe einer bestimmten Stadt auslesen
$city = Zend_Date_Cities::City('Vienna');

// Ein Datumsobjekt erstellen für den Tag
// für den die Sonne berechnet werden soll
$date = new Zend_Date('10.03.2007', Zend_Date::ISO_8601, 'de');

// Sonnenuntergang berechnen
$sunset = $date->getSunset($city);
print $sunset->get(Zend_Date::ISO_8601);

// Alle Sonneninformationen berechnen
$info = $date->getSunInfo($city);
foreach ($info as $sun) {
    print "\n" . $sun->get(Zend_Date::ISO_8601);
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.date.additional.timezones">

        <title>Zeitzonen</title>

        <para>
            Zeitzonen sind genauso wichtig wie die Datumsangaben selbst. Es gibt einige Zeitzonen abhängig davon
            wo auf der Welt der Benutzer lebt. Deshalb bedeutet das Arbeiten mit Daten auch immer das eine
            gültige Zeitzone gesetzt ist. Das klingt eventuell kompliziert, ist aber viel einfacher als erwartet.
            Wie schon im ersten Kapitel von <classname>Zend_Date</classname> erwähnt muß immer eine Standardzeitzone
            ersetzt werden. Entweder durch <code>php.ini</code> oder durch Definition in der Bootstrap Datei.
        </para>

        <para>
            Ein <classname>Zend_Date</classname> Objekt speichert natürlich die aktuelle Zeitzone. Selbst wenn die
            Zeitzone nach der Erstellung des Objektes geändert wird, merkt sich das Objekt die originale
            Zeitzone und arbeitet mit Ihr. Es ist also nicht notwendig die Zeitzone im Code mithilfe von
            PHP Funktionen zu ändern. <classname>Zend_Date</classname> hat zwei eingebaute Funktionen die es ermöglichen
            damit zu Arbeiten.
        </para>

        <para>
            <code>getTimezone()</code> gibt die aktuell gesetzte Zeitzone des <classname>Zend_Date</classname> Objektes
            zurück. Man sollte in Erinnerung behalten das <classname>Zend_Date</classname> nicht mit den PHP Internas
            gekoppelt ist. Deshalb ist die zurückgegebene Zeitzone nicht die des PHP Skripts sondern jene des
            Objektes. <code>setTimezone($zone)</code> ist die zweite Funktion und ermöglicht es eine neue
            Zeitzone für <classname>Zend_Date</classname> zu setzen. Eine angegebene Zeitzone wird immer geprüft. Wenn diese
            nicht existiert wird eine Ausnahme geworfen. Zusätzlich kann die Zeitzone des aktuellen Skripts oder
            des Systems für das Datumsobjekt gesetzt werden indem <code>setTimezone()</code> ohne den Parameter
            zone aufgerufen wird. Das wird auch automatisch gemacht wenn das Datumsobjekt erstellt wird.
        </para>

        <example id="zend.date.additional.timezones.example-1">
            <title>Arbeiten mit Zeitzonen</title>
            <programlisting role="php"><![CDATA[
// Setzen einer Standardzeitzone... das muß in der Bootstrap Datei
// oder php.ini gemacht werden. Wir setzen Sie hier nur der Vollständigkeit
// halber um ein komplettes Beispiel zu erhalten.
date_default_timezone_set('Europe/Vienna');

// Erstellen des Datumsobjektes
$date = new Zend_Date('10.03.2007', Zend_Date::DATES, 'de');

// Ausgabe des Datumsobjektes
print $date->getIso();

// Welche Zeitzone ist gesetzt ?
print $date->getTimezone();

// Setzen einer anderen Zeitzone
$date->setTimezone('America/Chicago');

// Welche Zeitzone ist jetzt gesetzt ?
print $date->getTimezone();

// Ausgabe des geänderten Datumsobjektes
print $date->getIso();
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Date</classname> nimmt immer die aktuelle Zeitzone für das Erstellen eines Objektes wie in den
            ersten Zeilen des Beispiels gezeigt. Das Ändern der Zeitzone für ein erstelltes Objekt
            hat einen Effekt auf das Datum selbst. Daten sind immer relativ zu einer Zeitzone. Das Ändern der
            Zeitzone für ein <classname>Zend_Date</classname> Objekt ändert nicht die Zeit des <classname>Zend_Date</classname> Objektes
            selbst. Man muß sich in Erinnerung halten das Daten intern immer als Zeitpunkte und in der GMT
            gespeichert werden. Eine Zeitzone bedeutet also wieviele Stunden subtrahiert oder addiert werden müssen
            um die aktuelle globale Zeit für die eigene Zeitzone und Region er erhalten.
        </para>

        <para>
            Das koppeln der Zeitzone innerhalb von <classname>Zend_Date</classname> hat einen anderen positiven Nebeneffekt.
            Es ist möglich verschiedene Daten mit verschiedenen Zeitzonen zu haben.
        </para>

        <example id="zend.date.additional.timezones.example-2">
            <title>Mehrere Zeitzonen</title>
            <programlisting role="php"><![CDATA[
// Setzen einer Standardzeitzone... das muß in der Bootstrap Datei oder
// php.ini gemacht werden. Wir setzen Sie hier nur der Vollständigkeit
// halber um ein komplettes Beispiel zu erhalten.
date_default_timezone_set('Europe/Vienna');

// Erstellen des Datumsobjektes
$date = new Zend_Date('10.03.2007 00:00:00', Zend_Date::ISO_8601, 'de');

// Ausgabe des Datumsobjektes
print $date->getIso();

// Das Datum bleibt unverändert selbst nach einer Änderung der Zeitzone
date_default_timezone_set('America/Chicago');
print $date->getIso();

$otherdate = clone $date;
$otherdate->setTimezone('Brazil/Acre');

// Ausgabe des Datumsobjektes
print $otherdate->getIso();

// Setzen der aktuellen Zeitzone des Systems für das Objekt
$lastdate = clone $date;
$lastdate->setTimezone();

// Ausgabe des Datumsobjektes
print $lastdate->getIso();
]]></programlisting>
        </example>

    </sect2>

</sect1>