4.2 Calendar 
| Besprochene Version: 0.5.2 | Lizenz: PHP-Lizenz |
| Klassendatei(en): siehe Tabelle 4.6 | |
Der primäre Fokus des Pakets Calendar besteht darin, Funktionalitäten zur Ausgabe von Kalendarien bereitzustellen. Das Paket besteht aus zwölf einzelnen Klassen, die sich wiederum in vier unterschiedliche Bereiche gliedern. Zum ersten sind das die Klassen, die zur Berechnung und Ausgabe der reinen Daten gedacht sind. Der zweite Bereich sind die tabellarischen Klassen, die für die Ausgabe von Kalendern gedacht sind. Hiermit können Sie sehr einfach einen Kalender mit der üblichen Einteilung in Wochentage ausgeben. Der dritte Teil wird durch die »Decorator Classes« dargestellt. Sie dienen dazu, die Datumszahlen z. B. mit Wochentagnamen zu »dekorieren«. Zu guter Letzt gibt es noch die Validator-Klassen, mit deren Hilfe Sie die Gültigkeit eines Datums prüfen können.
Der grundsätzliche Aufbau des Pakets sieht vor, dass die »übergeordneten« Datumsobjekte die »kleineren« beinhalten. Ein Jahr kann somit Monate beinhalten, und jeder Monat kann somit Tage generieren.
Möchten Sie alle Tage eines Jahres ausgeben, teilen Sie dem zuständigen Konstruktor zuerst mit, welches Jahr Sie benötigen. Das so generierte Calendar_Year-Objekt kann dann die Monate generieren. Für jedes so entstandene Calendar_Month-Objekt können Sie dann wiederum die einzelnen Tage generieren lassen. Natürlich müssen Sie nicht immer mit einem Jahr beginnen; es wäre genauso möglich, mit einem Tag zu beginnen und die Stunden, Minuten und Sekunden generieren zu lassen.
In Tabelle 4.6 finden Sie eine Übersicht darüber, welche Klasse in welcher Datei definiert wird.
Um ein neues Jahr zu generieren, nutzen Sie den Konstruktor Calendar_Year(), der die Information übergeben bekommt, um welches Jahr es sich handelt, also z. B. 2005:
Für die anderen Klassen stehen entsprechende Konstruktoren zur Verfügung, die alle das Datum bzw. die Zeit zugewiesen bekommen, die dargestellt werden soll. Die Reihenfolge, in der die Werte angegeben werden, ist hierbei immer »vom Großen zum Kleinen« – also Jahr, Monat, Tag, Stunde, Minute, Sekunde. Um die Uhrzeit 14:05 am 23. Oktober 2005 darzustellen, würde die Instanziierung des neuen Objekts so lauten:
Legen Sie ein neues Objekt an, so werden alle kleineren Zeiteinheiten, die nicht zu der eigentlichen Klasse gehören, mit dem jeweils kleinsten gültigen Wert initialisiert. Mit anderen Worten: Wenn Sie ein Calender_Year-Objekt ableiten, wird der erste Januar 00:00 Uhr angenommen.
Für jede der Zeiteinheiten sind Methoden vorgesehen, mit denen Sie den aktuellen Wert bzw. den nächsten oder vorhergehenden Monat, Tag etc. auslesen können.
require_once("Calendar/Hour.php"); //wird mit dem 23. Oktober 2005 14:00:00 Uhr initialisiert $Hour = new Calendar_Hour(2005,10,23,14); echo $Minute->thisYear(); // Gibt 2005 aus echo $Minute->nextYear(); // Gibt 2006 aus echo $Minute->prevYear(); // Gibt 2004 aus echo $Minute->prevMonth(); // Gibt 9 aus echo $Minute->prevMinute(); // Gibt 59 aus
Wie Sie nach diesem Beispiel schon ahnen werden, gibt es für jede der Zeiteinheiten eine Methode, die mit this beginnt und den aktuellen Wert zurückgibt. Es handelt sich hierbei um die Methoden thisYear(), thisMonth(), thisDay(), thisMinute() und thisSecond(). Um den vorhergehenden Wert zu ermitteln, steht ein Satz von Methoden zur Verfügung, die mit prev beginnen, wohingegen der jeweils nachfolgende Wert mit nextYear(), nextMonth() etc. ermittelt werden kann. Alle Methoden können Ihnen das enthaltene Datum als Timestamp zurückliefern, wenn sie true als Parameter übergeben bekommen. Hierbei ist zu beachten, dass die Methoden sich immer auf den aktuellen Wert des Objekts beziehen, der sich allerdings nicht ändert. Handelt es sich z. B. um den Ersten eines Monats und Sie lassen zweimal den Wert von $tag->nextMonth() ausgeben, so wird zweimal die 2 ausgegeben.
Nachdem Sie nun wissen, wie Sie ein neues Objekt instanziieren, stellen Sie sich sicher die Frage, wozu die Klasse denn nun gut ist. Eine der großen Stärken besteht in der Methode build(). Mit ihrer Hilfe können Sie in einem Objekt die Objekte der nächstkleineren Zeiteinheit erzeugen. Das heißt, wenn Sie die Methode auf ein Calendar_Year-Objekt anwenden, so werden in dem Objekt 12 Objekte vom Typ Calendar_Month erzeugt. Sollte ein Fehler auftreten, liefert die Methode ein false, andernfalls ein true zurück. Die neu erstellten Objekte werden nicht zurückgegeben, sondern in das genutzte Objekt integriert. Sie können die Objekte dann mit der Methode fetch() auslesen und weiterverarbeiten. Auf diesem Weg ist es z. B. sehr einfach möglich, einen Kalender für ein ganzes Jahr auszugeben.
require_once("Calendar/Year.php");
$jahr = new Calendar_Year(2005);
// Calendar_Month-Objekte instanziieren
$erg=$jahr->build();
if (false===$erg)
{
die ("Fehler beim Anlegen der Monate");
}
// Monate auslesen
while (false!=($monat = $jahr->fetch()))
{
echo ("<p>");
// Monat ausgeben
echo ("Monat: ".$monat->thisMonth()."<br />");
// Calendar_Day-Objekte anlegen
$erg=$monat->build();
if (false===$erg)
{
die ("Fehler beim Anlegen der Tage");
}
// Tage auslesen
while(false!=($tag = $monat->fetch()))
{
// Tag ausgeben
echo ($tag->thisDay()." ");
}
echo "</p>";
}Listing 4.1 Ausgabe eines Jahreskalenders mit Calendar
In Abbildung 4.1 sehen Sie die Ausgabe von Listing 4.1.
Entsprechend der Systematik, die in Listing 4.1 genutzt wird, können Sie natürlich auch noch die Stunden eines Tages ausgeben, nachdem Sie diese mit $tag–>build() generiert haben.
Abbildung 4.1 Die Ausgabe von Listing 4.1 im Browser
Ein so ausgegebenes Jahr beinhaltet zwar alle Daten, aber die Darstellung lässt sich sicher noch verbessern. Die meisten Kalender teilen das Jahr in Monate und dann in Wochen und Tage ein. Möchten Sie eine solche Einteilung nutzen, ist das auch möglich. Wichtig hierbei ist, dass die Klassen sich an den Wochen eines Monats orientieren. Das heißt, wenn also der Erste eines Monats ein Samstag ist, wird der Anfang der Woche mit leeren Tagen gefüllt.
Hierfür sind die tabellarischen Klassen vorgesehen, die Sie in Tabelle 4.7 finden.
Die Konstruktoren der beiden mit Calendar_Month beginnenden Klassen bekommen eine Jahreszahl und einen Monat als Parameter übergeben. Um ein Calendar_Week- bzw. ein Calendar_Day-Objekt zu erzeugen, müssen Sie das Datum eines kompletten Tages übergeben. Alle Konstruktoren, mit Ausnahme von Calendar_Day(), akzeptieren noch einen zusätzlichen Parameter, mit dem Sie den ersten Tag der Woche definieren können. Per Default wird der Montag als erster Tag genutzt. Geben Sie eine 0 an, ist der erste Tag der Woche der Sonntag, bei einer 2 ist es der Dienstag etc.
Für eine einfache kalendarische Ausgabe eines Monats eignet sich Calendar_Month_Weekdays besonders gut. Beim Aufruf der Methode build() generiert ein entsprechendes Objekt mindestens so viele Tage, wie der Monat hat. Wie gesagt sind es mindestens so viele Calendar_Date-Objekte wie der Monat Tage hat aber es können auch mehr sein. Das liegt daran, dass sich auch diese Funktion an Wochen orientiert. Sie liefert jede Woche, in der sich auch nur ein Tag des Monats befindet, komplett zurück. Wochentage, die nicht zu dem Monat gehören, werden als leere Objekte zurückgegeben. Um zu prüfen, ob ein Tag leer ist, steht die Methode isEmpty() zur Verfügung. Der erste Tag einer Woche kann mithilfe von isFirst() und der letzte mit isLast() identifiziert werden. Einen einfachen Kalender über zwei Monate können Sie so erzeugen:
require_once 'Calendar/Month/Weekdays.php';
echo "<table border=\"1\">";
// Schleife, um durch die Monate zu laufen
for ($monat_nr=3; $monat_nr < 6; $monat_nr+=1)
{
// Neuen Monat erstellen
$monat = new Calendar_Month_Weekdays(2005, $monat_nr);
$monat->build(); // Tage generieren
// Calendar_Day-Objekt auslesen
while ($tag = $monat->fetch())
{
// Ist es der erste Tag der Woche?
if (true===$tag->isFirst())
{
echo "<tr>";
}
// Ist der Tag leer?
if (true===$tag->isEmpty())
{
echo "<td> </td>";
}
else
{
echo "<td>".$tag->thisDay()."</td>";
}
// Ist es der letzte Tag der Woche?
if (true===$tag->isLast())
{
echo "</tr>";
}
}
// Leerzeile zum Abtrennen der Monate
echo ("<tr><td colspan=\"7\"> </td></tr>");
}
echo "</table>";Listing 4.2 Ausgabe von drei kompletten Monaten mit PEAR::Calendar
Allerdings ist auch ein solcher Kalender noch nicht perfekt. Die Wochennummern und auch die Namen der Monate und Tage wären hilfreich. Hierzu werde ich gleich auf die Klassen Calendar_Month_Weeks und Calendar_Week zurückgreifen. Zuvor möchte ich jedoch auf eine der Decorator-Klassen eingehen. Diese werden genutzt, um die Ausgabe eines Kalenders optisch aufzuwerten. Alle Decorator-Objekte, die aus einem Calendar-Objekt abgeleitet wurden, beinhalten nach wie vor das ursprüngliche Objekt, so dass also auch alle Methoden des ursprünglichen Objekts genutzt werden können. Mit der Klasse Calendar_Decorator_Textual, die in der Datei Calendar/Decorator/Textual.php definiert ist, können Sie die Namen von Tagen und Monaten ausgeben lassen. Möchten Sie wissen, auf welchen Tag ein bestimmtes Datum fällt, könnte das so aussehen:
setlocale(LC_ALL,"de_DE"); // Lokalisierung auf Deutsch $tag = new Calendar_Day(2005,12,31); // Neuen Tag anlegen // Neuen Decorator instanziieren $deco = new Calendar_Decorator_Textual($tag); echo ($deco->thisDayName()); //Tag ausgeben
Um die Klartext-Darstellung eines Tages zu erhalten, müssen Sie also erst ein neues Text_Decorator_Textual-Objekt ableiten. Der eigentliche Text wird dann mit der Methode thisDayName() ausgelesen. Um den Namen eines Monats auszulesen, steht die Methode thisMonthName() zur Verfügung. Des Weiteren stehen die Methoden prevDayName(), nextDayName(), prevMonthName() und nextMonthName() zur Verfügung, mit denen Sie in die Vergangenheit bzw. Zukunft »schauen« können. Alle Methoden liefern standardmäßig einen englischen Text zurück, können aber mit Hilfe der Funktion setlocale() auf eine andere Sprache eingestellt werden. Allerdings wäre es für einen ganzen Kalender recht aufwändig, für jeden Tag ein entsprechendes Objekt zu generieren. Daher bietet die Klasse auch die Möglichkeit, die Namen der Tage und Monate in Form von Arrays auszulesen. Die Methoden monthNames() und weekdayNames(), die das leisten, können statisch aufgerufen werden. Da die Namen auch nicht vom Datum abhängen, erscheint das auch sinnvoll.
Alle vorgenannten Methoden akzeptieren vier Parameter, mit denen Sie steuern können, wie lang die zurückgegebenen Bezeichner sind. Mit 'one' erhalten Sie nur den ersten Buchstaben des Monats bzw. Tags, wohingegen 'two' die ersten beiden liefert. Der Parameter 'short' gibt die »üblichen« Abkürzungen wie Jan, Feb, Mo, Di etc. zurück. Geben Sie keinen Parameter oder 'long' an, erhalten Sie die komplett ausgeschriebenen Namen.
Wichtig bei der Methode weekdayNames() ist, dass die Klasse Calendar üblicherweise den Montag als ersten Tag der Woche ansieht, diese Methode sich aber an den ISO-Standard hält und somit der Sonntag der erste Tag der Woche ist und sich daher im ersten Array-Element findet.
Möchten Sie ein Array mit den Wochentagen in der korrekten Reihenfolge erhalten, können Sie auf die Methode orderedWeekdays() zurückgreifen, die allerdings nicht statisch aufgerufen werden kann. Sie benötigt ein Calendar_Decorator_Textual-Objekt, das Sie aus einem Calendar_Month_Weeks-Objekt ableiten sollten. Wichtig hierbei ist, dass die Methode build() vor dem Aufruf der Methode orderedWeekdays() ausgeführt werden muss.
// Neuen Monat generieren $monat=new Calendar_Month_Weeks(2005,10); // Decorator-Objekt ableiten $decorator=new Calendar_Decorator_Textual($monat); // Wochen generieren; $decorator->build() ginge auch $monat->build(); // $ordered enthaelt jetzt die Tage, beginnend mit Montag $ordered=$decorator->orderedWeekdays();
Aber zurück zu den Klassen Calendar_Month_Weeks und Calendar_Week, die ich eingangs erwähnte: Die erste erzeugt Objekte der zweiten Klasse, sobald die Methode build() ausgeführt wird. Die Calendar_Week-Objekte generieren dann jeweils sieben einzelne Tage, die, wenn sie nicht zu dem Monat gehören, auch leer sein können. Die Calendar_Week-Objekte unterstützen die Methode thisWeek(), mit der die Wochennummer ausgelesen werden kann. Diese bezieht sich standardmäßig auf den Monat. Das heißt, für die erste Woche im Monat liefert sie die Zahl eins zurück, für die zweite die Zahl zwei etc. Um die Nummerierung auf das Jahr zu beziehen, können Sie der Methode den String 'n_in_year' übergeben.
require_once ('Calendar/Month/Weeks.php'); require_once ('Calendar/Decorator/Textual.php'); // Lokalisierung einstellen setlocale(LC_ALL,"de_DE"); // Monats- und Tagesnamen auslesen $monate=Calendar_Decorator_Textual::monthNames(); // Tage nur als short, um die Tabelle nicht zu sprengen $tage=Calendar_Decorator_Textual::weekdayNames('short'); echo ("<table border=\"1\">"); // Schleife, die durch die Monate geht for ($cnt_monat=1; $cnt_monat < 13; $cnt_monat+=1) { // Neuen Monat generieren $month = new Calendar_Month_Weeks(2004,$cnt_monat); $month->build(); // Wochen generieren // Leerzeile zum Abtrennen der Monate echo ("<tr><td colspan=\"8\"> </td></tr>"); // Monatsnamen ausgeben echo ("<tr><td colspan=\"8\">"); echo ($monate[$cnt_monat]); echo ("</td></tr>"); // Spaltenueberschriften (Tage) ausgeben echo ("<tr><td>Nr.</td>"); for ($cnt_tag=1; $cnt_tag < 8; $cnt_tag+=1) { // %7 da das Array $tage mit Sonntag=0 beginnt echo ("<td>".$tage[$cnt_tag % 7]."</td>"); } echo ("</tr>"); // Woche auslesen und abarbeiten while ($month_week=$month->fetch()) { $month_week->build(); // Tage generieren echo ("<tr>"); echo ("<td>"); // Wochennummer ausgeben echo ($month_week->thisWeek('n_in_year')); echo("</td>"); // Tag ausgeben while ($tag=$month_week->fetch()) { echo ("<td>"); if (true==$tag->isEmpty()) { echo (" "); } else { echo ($tag->thisDay()); } echo ("</td>"); } echo ("</tr>"); } } echo ("</table>");
Listing 4.3 Ausgabe eines Jahreskalenders mit Wochennummern
Einen Teil der Ausgabe von Listing 4.3 sehen Sie in Abbildung 4.2. Vielleicht wundern Sie sich, dass ich in Listing 4.3 die Methode weekdayNames() an Stelle von orderedWeekdays() nutze. Das ist zwar bei der Ausgabe ein wenig aufwändiger, bietet aber den Vorteil, dass ich keine weiteren Decorator-Objekte generieren muss.
Abbildung 4.2 Die Ausgabe des Kalenders im Browser
Neben der Klasse Calendar_Decorator_Textual gibt es noch die Decorator-Klassen Calendar_Decorator_Uri und Calendar_Decorator_Wrapper. Die Uri-Klasse ist in der Datei Calendar/Decorator/Uri.php definiert und ermöglicht es Ihnen, auf einfache Art und Weise Links zu erstellen, mit deren Hilfe ein Datum übergeben werden kann. Das ist immer dann hilfreich, wenn Sie z. B. Termine zu einem Tag anzeigen oder durch einen Kalender blättern wollen. Auch diese Decorator-Klasse setzt voraus, dass Sie eine neue Instanz ableiten, die mit einem Calendar-Objekt initialisiert wird, das eine Zeit enthält.
Um einen entsprechenden Link generieren zu können, müssen Sie zuerst die Methode setFragments() aufrufen, mit der definiert wird, welche Informationen der Link enthalten soll. Die Methode erwartet mindestens einen Parameter, akzeptiert aber bis zu sechs. Jeder steht für die zu übergebende Zeiteinheit. Hierbei steht der erste, obligatorische Parameter für das Jahr, der zweite für den Monat, der dritte für den Tag und so weiter, bis der letzte schließlich für die Sekunden steht. Die hier übergebenen Strings werden Teil des Query-Strings und finden sich somit in der aufgerufenen Seite als Schlüssel im Array $_GET wieder. Die dazugehörigen Werte, die auch mit dem Query-String übergeben werden, finden sich dann als Werte in dem Array.
Mit der Methode next() können Sie auf die nächste und mit prev() auf die vorhergehende Zeitperiode verweisen. Möchten Sie um einen Monat springen, sollten Sie ein Calendar_Month zum Initialisieren des Uri-Objekts nutzen. Soll es um einen Tag nach vorn oder hinten gehen, empfiehlt sich ein Calendar_Day-Objekt. Sie sollten also immer ein Objekt der passenden Zeitdimension wählen, da es andernfalls zu unerwünschten Nebeneffekten kommen kann. Zusätzlich erwarten die Methoden next() und prev() eine Information, welche Zeiteinheit verändert werden soll. Hierzu können Sie die Strings 'year', 'month', 'day', 'hour', 'minute' und 'second' verwenden.
require_once("Calendar/Month.php"); require_once("Calendar/Day.php"); require_once("Calendar/Decorator/Uri.php"); $tag = new Calendar_Day(2005, 10, 21); $uri = new Calendar_Decorator_Uri($tag); $uri->setFragments('jahr', 'monat', 'tag'); echo ("<a href='dummy.php?".$uri->prev('day')."'>"); echo ("Vorhergehender Tag</a><br />"); // Generierter Link: dummy.php?jahr=2005&monat=10&tag=20 // Auf dummy.php stehen $_GET["jahr"], $_GET["monat"] // etc. zur Verfuegung $monat = new Calendar_Month(2005, 10); $uri = new Calendar_Decorator_Uri($monat); $uri->setFragments('jahr', 'monat'); echo ("<a href='dummy.php?".$uri->next('month')."'>"); echo ("Nächster Monat</a>"); // Generierter Link: dummy.php?jahr=2005&monat=11
Listing 4.4 Link generieren mit PEAR::Calendar
Die letzte Decorator-Klasse ist Calendar_Decorator_Wrapper. Sie ist dazu gedacht, Ihnen eine einfache Möglichkeit zu geben, bestehende Methoden zu überladen bzw. zu erweitern. Die Wrapper-Klasse wird mit einem bestehenden Calendar-Objekt initialisiert und erbt alle in der dazugehörigen Klasse definierten Methoden und Eigenschaften. In Listing 4.2 habe ich einen Teil eines Kalenders ausgeben lassen. Bei jedem Tag wurde überprüft, ob es sich um den ersten, den letzten oder einen Tag mitten in der Woche handelt, um die entsprechenden HTML-Tabellen-Tags mit ausgeben zu können. Würde diese Routine in mehreren Scripts benötigt, würde es sich anbieten, sie in eine Wrapper-Klasse auszulagern, wie Listing 4.5 zeigt.
require_once 'Calendar/Month/Weekdays.php'; require_once 'Calendar/Decorator/Wrapper.php'; class Calendar_Tabelle_Tag extends Calendar_Decorator { // Fuer PHP4 muesste der Konstruktor // Calendar_Tabelle_Tag heissen function __construct ($Calendar) { parent::Calendar_Decorator($Calendar); } // Ueberschreiben der Methode thisDay() aus dem // original Calendar-Objekt function thisDay() { $ret_val=""; // Erster Tag der Woche? if (true===$this->isFirst()) { $ret_val.="<tr>"; } // Ist der Tag leer? if (true===$this->isEmpty()) { // Leeres Tabellenfeld zurueckgeben $ret_val.="<td> </td>"; } else { // Tabellenfeld mit Datum zureuckgeben $ret_val.="<td>".parent::thisDay()."</td>"; } // Ist es der letzte Tag der Woche? if (true===$this->isLast()) { $ret_val.="</tr>"; } return $ret_val; } } // Monat erstellen $monat = new Calendar_Month_Weekdays(2005, 10); // Objekt an ein neues Wrapper-Objekt uebergeben $wrapper= new Calendar_Decorator_Wrapper($monat); // Tage generieren $wrapper->build(); // Tabelle ausgeben echo "<table>"; // fetch() bekommt den Namen der Decorator-Klasse uebergeben while ($ein_tag = $wrapper->fetch('Calendar_Tabelle_Tag')) { // Aufruf der eigenen Methode thisDay() echo $ein_tag->thisDay(); } echo "</table>";
Listing 4.5 Generieren eines Kalenders mit einer Wrapper-Klasse
Ich möchte zum Schluss noch kurz darauf eingehen, wie Sie Zeitabstände berechnen können, also z. B., wie viele Tage es noch bis Weihnachten sind. Hierbei ist es am einfachsten, wenn Sie, wenn Sie nicht PEAR::Date nutzen wollen, auf Timestamps zurückgreifen, die Sie übrigens auch mit der Methode getTimestamp() auslesen können. Möchten Sie ein Calendar-Objekt mit einem Timestamp initialisieren, können Sie die Methode setTimestamp() nutzen.
require_once 'Calendar/Day.php';
// Objekt anlegen und mit aktuellem
// Datum bestuecken
$heute=new Calendar_Day(0,0,0);
$heute->setTimestamp(time());
$xmas=new Calendar_Day(date("Y"),12,24);
// Zwei Moeglichkeiten, um den Timestamp auszulesen
$differenz=$xmas->thisDay(true)-$heute->getTimestamp();
// Berechnung der Differenz etwas aufwaendiger
// geloest, um Rundungsfehler auszuschliessen
$rest=($differenz%86400);
$tage=round(($differenz-$rest)/86400);
$differenz=$rest;
$rest=$differenz%3600;
$stunden=round(($differenz-$rest)/3600);
$differenz=$rest;
$rest=$differenz%60;
$minuten=round(($differenz-$rest)/60);
$sekunden=$rest;
echo ("Es dauert noch $tage Tage, $stunden Stunden,
$minuten Minuten und $sekunden Sekunden bis Weihnachten");Listing 4.6 Berechnen der Zeitspanne bis Weihnachten
Zu guter Letzt sei noch die Validator-Klasse erwähnt. Mit ihr können Sie die Gültigkeit von Daten überprüfen, was in einigen Fällen sicher auch hilfreich sein kann.
