Signatur
Beschreibung
IntlCalendar ist die abstrakte Basisklasse der ICU-basierten Kalender-API in PHP. Sie stellt Methoden bereit, um Datum und Uhrzeit in verschiedenen Kalendersystemen (Gregorianisch, Japanisch, Buddhistisch, Chinesisch etc.) und Zeitzonen korrekt zu verarbeiten. Instanzen werden in der Regel über die statische Fabrikmethode IntlCalendar::createInstance() oder IntlGregorianCalendar erzeugt.
Im Gegensatz zu PHPs eingebautem DateTime berücksichtigt IntlCalendar vollständig lokale Regeln für Wochenbeginn, Wochennummerierung, Schaltjahre in nicht-gregorianischen Systemen sowie Sommer-/Winterzeit gemäß ICU-Daten. Das macht sie unverzichtbar für internationale Anwendungen, die korrekte Datumsarithmetik über Locale-Grenzen hinweg benötigen.
Die Klasse bietet Methoden zum Lesen und Schreiben einzelner Kalenderfelder (FIELD_YEAR, FIELD_MONTH, FIELD_DAY_OF_MONTH etc.), zum Rechnen mit add() und roll(), zum Vergleichen von Zeitpunkten sowie zur Konvertierung in und aus Unix-Timestamps. Zeitzone und Locale werden beim Erzeugen der Instanz festgelegt, können aber nachträglich geändert werden.
Hinweis: Die Klasse selbst ist nicht direkt instantiierbar; verwende IntlCalendar::createInstance() oder konkrete Unterklassen wie IntlGregorianCalendar.
Beispiele
Gregorianisches Kalenderobjekt erzeugen und Felder auslesen
<?php
// Kalenderobjekt für Locale 'de_DE' und Berliner Zeitzone erzeugen
$cal = IntlCalendar::createInstance('Europe/Berlin', 'de_DE');
// Aktuellen Zeitpunkt auf einen bestimmten Zeitstempel setzen
$cal->setTime(mktime(12, 0, 0, 7, 4, 2025) * 1000); // ICU arbeitet mit Millisekunden
echo 'Jahr: ' . $cal->get(IntlCalendar::FIELD_YEAR) . PHP_EOL;
echo 'Monat: ' . ($cal->get(IntlCalendar::FIELD_MONTH) + 1) . PHP_EOL; // 0-basiert!
echo 'Tag: ' . $cal->get(IntlCalendar::FIELD_DAY_OF_MONTH) . PHP_EOL;
echo 'Stunde:' . $cal->get(IntlCalendar::FIELD_HOUR_OF_DAY) . PHP_EOL;Datumsarithmetik mit add() und Vergleich zweier Kalender
<?php
$cal1 = IntlCalendar::createInstance('UTC', 'en_US');
$cal1->setTime(mktime(0, 0, 0, 1, 31, 2025) * 1000);
// Einen Monat addieren – IntlCalendar passt den Tag automatisch an
$cal1->add(IntlCalendar::FIELD_MONTH, 1);
echo 'Nach +1 Monat ab 31. Jan: '
. $cal1->get(IntlCalendar::FIELD_YEAR) . '-'
. ($cal1->get(IntlCalendar::FIELD_MONTH) + 1) . '-'
. $cal1->get(IntlCalendar::FIELD_DAY_OF_MONTH) . PHP_EOL;
// Zwei Kalender vergleichen
$cal2 = IntlCalendar::createInstance('UTC', 'en_US');
$cal2->setTime(mktime(0, 0, 0, 3, 1, 2025) * 1000);
if ($cal1->before($cal2)) {
echo 'cal1 liegt vor cal2';
} elseif ($cal1->after($cal2)) {
echo 'cal1 liegt nach cal2';
} else {
echo 'Beide Kalender zeigen denselben Zeitpunkt';
}Nicht-gregorianischen Kalender verwenden (Japanisch)
<?php
// Japanischen Kaiserkalender für Locale 'ja_JP@calendar=japanese' erzeugen
$cal = IntlCalendar::createInstance('Asia/Tokyo', 'ja_JP@calendar=japanese');
$cal->setTime(mktime(0, 0, 0, 5, 1, 2019) * 1000); // Beginn Reiwa-Ära
echo 'Ära (extended year): ' . $cal->get(IntlCalendar::FIELD_EXTENDED_YEAR) . PHP_EOL;
echo 'Jahr in Ära: ' . $cal->get(IntlCalendar::FIELD_YEAR) . PHP_EOL;
echo 'Monat (0-basiert): ' . $cal->get(IntlCalendar::FIELD_MONTH) . PHP_EOL;// Wichtig · Fallstricke
Monate sind 0-basiert: Wie in der ICU-API üblich beginnt Januar bei FIELD_MONTH = 0. Vergisst man das +1 bei der Ausgabe, entstehen schwer zu findende Off-by-one-Fehler.
Zeitstempel in Millisekunden: setTime() und getTime() arbeiten mit Unix-Millisekunden (nicht Sekunden). Beim Konvertieren aus PHP-Timestamps immer mit 1000 multiplizieren bzw. dividieren.
Zeitzone-Konflikte: Die Zeitzone des IntlCalendar-Objekts ist unabhängig von date_default_timezone_set() und DateTimeZone. Stelle sicher, dass beide konsistent sind, wenn du zwischen den APIs wechselst.
ICU-Datenbankversion: Das Verhalten (Zeitzonendaten, Ären, Locale-Regeln) hängt von der auf dem Server installierten ICU-Version ab. Unterschiedliche Server können leicht abweichende Ergebnisse liefern.