# Funktionierende Beispiele

In diesem Kapitel werden verschiedene zusätzliche Funkionen beschrieben welche auch durch `Zend_Date` verfügbar sind. Natürlich sind für alle beschriebenen Funktionen auch Beispiele vorhanden, um die Arbeitsweise und die einfache API für die richtige Benutzung zu zeigen.

## Prüfen von Daten

Normalerweise werden die meisten Daten als Zeichenketten übergeben. Aber das Problem mit Zeichenketten ist, dass man nicht sicher sein kann, ob eine Zeichenkette ein echtes Datum enthält. Hierfür gibt es in `Zend_Date` eine eigene statische Funktion um Datums-Zeichenketten zu prüfen. `Zend_Locale` hat eine eigene Funktion `getDate($date, $locale)`, 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. Da `Zend_Locale` lediglich eine Klasse zum Normalisieren und Lokalisieren ist und somit keine Kenntnis über die Daten hat, wurde die Funktion `isDate($date)` integriert, welche dies prüfen kann.

`isDate($date, $format, $locale)` nimmt bis zu drei Parameter entgegen und benötigt mindestens einen Parameter. Deshalb ist alles, was für die Prüfung eines Datums benötigt wird, 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. Details darüber, wie Formate aussehen müssen, sind im Kapitel über selbst definierte Formate nachzulesen.

Der dritte Parameter ist, wie schon der zweite Parameter, optional und kann für die Angabe eines Gebietsschemas verwendet werden. Das Gebietsschema wird zur Normalisierung von Monats- und Wochentagsnamen benötigt. Mit der Angabe des dritten Parameters ist es also möglich, Daten wie '`01.Jänner.2000`' oder '`01.January.2000`' abhängig vom angegebenen Gebietsschema, zu erkennen.

`isDate()` prüft auch ob ein Datum existiert. `Zend_Date` selbst prüft die Daten nicht. Deshalb ist es möglich ein Datum wie zum Beispiel '`31.Februar.2000`' mit `Zend_Date` zu erstellen, da `Zend_Date` das Datum automatisch korrigiert und eine gültige Datumsangabe zurück gibt. In unserem Fall den '`03.März.2000`'. Auf der anderen Seite führt `isDate()` diese Prüfung durch und gibt beim '`31.Februar.2000`' `FALSE` zurück, weil sie weiß das dieses Datum unmöglich ist.

### Prüfen von Daten

    // 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";
    }

## Sonnenaufgang und Sonnenuntergang

`Zend_Date` beinhaltet auch Funktionen um Informationen zur Sonne zu erhalten. Oft ist es notwendig, die Zeit für Sonnenaugang oder Sonnenuntergang für einen bestimmten Tag zu erhalten. Das ist mit `Zend_Date` sehr einfach, da nur der gewünschte Tag und die Ortsangabe für den Sonnenaufgang oder Sonnenuntergang angegeben werden muss.

Da die meisten Personen die genaue Ortsangabe Ihrer Stadt nicht kennen, wird eine eine Helferklasse bereitgestellt, 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.

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

### Alle verfügbaren Städte ausgeben

    // Ausgabe der kompletten Liste aller verfügbaren Städte
    print_r (Zend_Date_Cities::getCityList());

Die Ortsangabe selbst erhält man mit der Funktion `Zend_Date_Cities::city()`. Sie akzeptiert den Namen einer Stadt wie durch die Funktion `Zend_Date_Cities::getCityList()` angegeben und optional als zweiten Parameter für den zu setzenden Horizont.

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

### Arten von unterstützten Horizonten für Sonnenauf- und -untergang

Horizont | Beschreibung | Verwendung
--- | --- | ---
effective | Standard Horizont | Nimmt an das die Welt ein Ball ist. Dieser Horizont wird immer benutzt wenn keiner definiert wurde.
civil | Üblicher Horizont | Oft in den üblichen Medien wie Fernsehen und Radio benutzt.
nautic | Nautischer Horizont | Oft in der Navigation zu See benutzt.
astronomic | Astronomischer Horizont | Oft bei der Berechnung mit Sternen benutzt

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

### Die Ortsangabe für eine Stadt auslesen

    // 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);

Da nun alle benötigten Daten angegeben werden können, ist der nächste Schritt die Erstellung eines `Zend_Date` 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 '`getSunset()`', des Sonnenuntergangs mit '`getSunrise()`' und alle möglichen Informationen, welche die Sonne betreffen mit '`getSunInfo()`' möglich. Nach der Berechnung wird das `Zend_Date` Objekt mit der berechneten Zeit zurückgegeben.

### Berechnung von Sonneninformationen

    // 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);
    }

## Zeitzonen

Zeitzonen sind genauso wichtig wie die Datumsangaben selbst. Es gibt einige Zeitzonen abhängig vom Aufenthaltsort des Nutzers. Deshalb bedeutet das Arbeiten mit Daten auch immer, dass eine gültige Zeitzone gesetzt ist. Das klingt eventuell kompliziert, ist aber viel einfacher als erwartet. Wie schon im ersten Kapitel von `Zend_Date` erwähnt, muss immer eine Standardzeitzone gesetzt werden. Dies kann entweder in der `php.ini` oder durch Definition in der Bootstrap Datei durchgeführt werden.

Ein `Zend_Date` Objekt speichert 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 dieser. Es ist also nicht notwendig, die Zeitzone im Code mithilfe von PHP Funktionen zu ändern. `Zend_Date` hat zwei eingebaute Funktionen, die es ermöglichen damit zu arbeiten.

`getTimezone()` gibt die aktuell gesetzte Zeitzone des `Zend_Date` Objektes zurück. Man sollte in Erinnerung behalten, dass `Zend_Date` nicht mit den PHP Internas gekoppelt ist. Deshalb ist die zurückgegebene Zeitzone nicht die des PHP Skripts, sondern jene des Objektes. `setTimezone($zone)` ist die zweite Funktion und ermöglicht es eine neue Zeitzone für `Zend_Date` 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 `setTimezone()` ohne den Parameter zone aufgerufen wird. Das wird auch automatisch gemacht, wenn das Datumsobjekt erstellt wird.

### Arbeiten mit Zeitzonen

    // Setzen einer Standardzeitzone... das muß in der Bootstrap Datei
    // oder php.ini gemacht werden. Wir setzen diese 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();

`Zend_Date` 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 `Zend_Date` Objekt ändert nicht die Zeit des `Zend_Date` Objektes selbst. Man muß sich in Erinnerung halten, dass 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 zu erhalten.

Das Koppeln der Zeitzone innerhalb von `Zend_Date` hat einen anderen positiven Nebeneffekt. Es ist möglich verschiedene Daten mit verschiedenen Zeitzonen zu haben.

### Mehrere Zeitzonen

    // Setzen einer Standardzeitzone... das muß in der Bootstrap Datei oder
    // php.ini gemacht werden. Wir setzen diese 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();