Signatur
Beschreibung
date_create_immutable() ist der prozedurale Alias für den Konstruktor new DateTimeImmutable(). Die Funktion parst den übergebenen Datums-/Zeitstring und liefert ein unveränderliches Datumsobjekt zurück. Im Gegensatz zu date_create() (bzw. DateTime) verändert jede Manipulation des Objekts nicht das Original, sondern gibt stets eine neue Instanz zurück.
Unveränderlichkeit ist der zentrale Vorteil von DateTimeImmutable: Wird das Objekt z. B. mit modify() oder add() verändert, bleibt das Original unberührt. Das verhindert unerwünschte Seiteneffekte, besonders wenn Datumsobjekte an mehrere Stellen weitergegeben werden.
Der Parameter $datetime akzeptiert alle Formate, die von PHPs unterstützten Datumsformaten erkannt werden, z. B. 'now', '2024-06-15', '+1 week' oder Unix-Timestamps wie '@1718400000'. Wird null oder 'now' übergeben, entspricht das dem aktuellen Zeitpunkt.
Schlägt das Parsen des Strings fehl, gibt die Funktion false zurück. Zur Fehleranalyse kann anschließend date_get_last_errors() aufgerufen werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $datetime | string | now | Ein Datums-/Zeitstring in einem von PHP erkannten Format (z. B. 'now', '2024-01-15 08:30:00', '+2 days'). Mit '@'-Präfix kann ein Unix-Timestamp angegeben werden. |
| $timezone | ?DateTimeZone | null | Ein DateTimeZone-Objekt, das die Zeitzone des erzeugten Datumsobjekts festlegt. Wird null übergeben, wird die per date_default_timezone_set() oder in der php.ini konfigurierte Standard-Zeitzone verwendet. Hat keine Wirkung, wenn $datetime einen Timezone-Offset enthält oder ein Unix-Timestamp mit @ ist. |
Rückgabewert
DateTimeImmutable-Objekt zurück. Kann der übergebene String nicht als Datum geparst werden, wird false zurückgegeben. Details zum Fehler sind über date_get_last_errors() abrufbar.Beispiele
Einfaches Erzeugen eines DateTimeImmutable-Objekts
<?php
$dt = date_create_immutable('2024-06-15 10:00:00');
if ($dt === false) {
echo 'Ungültiges Datum!';
} else {
echo $dt->format('d.m.Y H:i:s');
}Unveränderlichkeit demonstrieren
<?php
$original = date_create_immutable('2024-01-01');
$nextWeek = $original->modify('+7 days');
echo $original->format('Y-m-d') . PHP_EOL; // Original bleibt unverändert
echo $nextWeek->format('Y-m-d') . PHP_EOL; // Neue Instanz mit +7 TagenZeitzonen-Konvertierung mit DateTimeZone
<?php
$tz = new DateTimeZone('America/New_York');
$dt = date_create_immutable('now', $tz);
echo 'New York: ' . $dt->format('Y-m-d H:i:s T') . PHP_EOL;
$dtBerlin = $dt->setTimezone(new DateTimeZone('Europe/Berlin'));
echo 'Berlin: ' . $dtBerlin->format('Y-m-d H:i:s T');// Wichtig · Fallstricke
Fallstrick bei Unix-Timestamps: Wird $datetime als '@1718400000' (mit @-Präfix) angegeben, wird der $timezone-Parameter ignoriert. Die Zeitzone ist dann immer UTC. Um die gewünschte Zeitzone zu setzen, muss anschließend setTimezone() aufgerufen werden.
Empfehlung: Gegenüber date_create() sollte in neuem Code bevorzugt date_create_immutable() verwendet werden, da unveränderliche Objekte zu besser vorhersehbarem und fehlerarmen Code führen, insbesondere in komplexen Berechnungen oder beim Weitergeben von Datumsobjekten an Funktionen.
Für die objektorientierte Schreibweise ist new DateTimeImmutable() gleichwertig und oft bevorzugt, da sie Typhinweise und IDE-Unterstützung besser nutzt.