Signatur
Beschreibung
date_create_immutable_from_format() ist die prozedurale Entsprechung von DateTimeImmutable::createFromFormat(). Sie analysiert eine Datums-/Zeitzeichenkette anhand eines angegebenen Formats und gibt bei Erfolg ein unveränderliches DateTimeImmutable-Objekt zurück. Im Gegensatz zu date_create_from_format(), das ein DateTime-Objekt liefert, ist das zurückgegebene Objekt hier unveränderlich (immutable), d. h. jede Modifikation erzeugt eine neue Instanz, anstatt das bestehende Objekt zu verändern.
Der Parameter $format verwendet dieselben Format-Zeichen wie date(). Dies ermöglicht eine präzise Kontrolle darüber, wie die Eingabezeichenkette interpretiert wird – besonders nützlich, wenn Datumswerte aus Formularen, Datenbanken oder externen APIs eingelesen werden, die ein festes, bekanntes Format verwenden.
Die Verwendung von DateTimeImmutable wird gegenüber DateTime in der Regel empfohlen, da sie unerwartete Seiteneffekte verhindert – insbesondere beim Weitergeben von Objekten an Funktionen oder beim Arbeiten mit mehreren abgeleiteten Zeitpunkten.
Falls das Parsing fehlschlägt, gibt die Funktion false zurück. Mit DateTimeImmutable::getLastErrors() können detaillierte Fehlermeldungen und Warnungen abgerufen werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $format Pflicht | string | Das Format, in dem $datetime übergeben wird. Verwendet dieselben Format-Zeichen wie date(), z. B. 'd.m.Y', 'Y-m-d H:i:s' oder 'U' für Unix-Timestamps. |
|
| $datetime Pflicht | string | Die Datums-/Zeitzeichenkette, die gemäß $format geparst werden soll, z. B. '25.12.2024' oder '2024-12-25 08:30:00'. |
|
| $timezone | ?DateTimeZone | null | Optionales DateTimeZone-Objekt, das die Zeitzone des erzeugten Datums festlegt. Wird null übergeben oder weggelassen, wird die aktuelle Standard-Zeitzone verwendet (gemäß date_default_timezone_get()). Enthält $datetime bereits Zeitzoneninformationen, wird dieser Parameter ignoriert. |
Rückgabewert
DateTimeImmutable-Objekt zurück, das den geparsten Zeitpunkt repräsentiert. Im Fehlerfall (ungültiges Format oder nicht parsbare Zeichenkette) wird false zurückgegeben.Beispiele
Datum aus deutschem Format einlesen
<?php
$datum = date_create_immutable_from_format('d.m.Y', '25.12.2024');
if ($datum === false) {
echo 'Ungültiges Datum!';
} else {
echo $datum->format('Y-m-d'); // ISO-Format ausgeben
}Datum mit Uhrzeit und Zeitzone parsen
<?php
$tz = new DateTimeZone('Europe/Berlin');
$datetime = date_create_immutable_from_format(
'Y-m-d H:i:s',
'2024-06-15 14:30:00',
$tz
);
if ($datetime !== false) {
echo $datetime->format('d.m.Y H:i T');
}Fehlerbehandlung bei ungültigem Format
<?php
$result = date_create_immutable_from_format('Y-m-d', '32.13.2024');
if ($result === false) {
$errors = DateTimeImmutable::getLastErrors();
echo 'Fehler: ' . implode(', ', $errors['errors']) . PHP_EOL;
echo 'Warnungen: ' . implode(', ', $errors['warnings']);
}Unveränderlichkeit von DateTimeImmutable demonstrieren
<?php
$original = date_create_immutable_from_format('Y-m-d', '2024-01-01');
$modified = $original->modify('+30 days');
echo $original->format('Y-m-d') . PHP_EOL; // unverändert
echo $modified->format('Y-m-d') . PHP_EOL; // neue Instanz// Wichtig · Fallstricke
Fehlende Zeitangaben: Wenn im Format keine Zeitkomponenten angegeben werden (z. B. nur 'Y-m-d'), werden die fehlenden Werte aus der aktuellen Zeit übernommen – nicht auf 00:00:00 gesetzt. Um Mitternacht zu erhalten, sollte das Format explizit um H:i:s erweitert oder setTime(0, 0, 0) auf dem Ergebnis aufgerufen werden.
Rückgabe prüfen: Der Rückgabewert sollte immer mit === false geprüft werden, nicht mit == false, da ein gültiges Datumsobjekt niemals falsy ist.
Zeitzone-Vorrang: Enthält die Datumszeichenkette bereits eine Zeitzone (z. B. '+02:00' oder 'UTC'), hat diese Vorrang vor dem $timezone-Parameter.
Alternative: Statt der prozeduralen Variante kann direkt DateTimeImmutable::createFromFormat() verwendet werden – beide sind funktional identisch.