date_create_from_format — Funktion · PHP-Referenz

Signatur

date_create_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false

Beschreibung

date_create_from_format() ist die prozedurale Entsprechung zu DateTime::createFromFormat(). Sie parst einen Datums- oder Zeitstring exakt nach dem angegebenen Formatmuster und gibt bei Erfolg ein DateTime-Objekt zurück. Im Gegensatz zu date_create() (bzw. new DateTime()) verlässt sich diese Funktion nicht auf die automatische Erkennung des Datumsformats, sondern erwartet eine exakte Übereinstimmung mit dem vorgegebenen Format.

Dies ist besonders nützlich, wenn Datumseingaben aus Formularen, Datenbanken oder externen APIs in einem bekannten, aber ungewöhnlichen Format vorliegen – z. B. d.m.Y für deutsches Datumsformat oder Y-m-d H:i:s für SQL-Zeitstempel. Damit werden Mehrdeutigkeiten beim Parsen zuverlässig vermieden.

Das Formatmuster verwendet dieselben Platzhalter wie die Funktion date(). Zusätzlich gibt es einige formatspezifische Sonderzeichen wie + (am Ende: erlaubt nachfolgende Zeichen) oder ! (setzt alle Felder auf Unix-Epoche-Basis). Nicht angegebene Zeitfelder werden standardmäßig auf den aktuellen Zeitpunkt gesetzt, sofern kein Reset-Zeichen verwendet wird.

Schlägt das Parsen fehl, gibt die Funktion false zurück. Zur Fehlerdiagnose können die Methoden DateTime::getLastErrors() bzw. die statische Variante genutzt werden, die Warnungen und Fehler im Detail auflistet.

Parameter

Name	Typ	Default	Beschreibung
$format Pflicht	string		Das Formatmuster, nach dem `$datetime` interpretiert wird. Verwendet dieselben Platzhalter wie `date()`, z. B. `d.m.Y`, `Y-m-d H:i:s` oder `U` für Unix-Timestamp.
$datetime Pflicht	string		Der zu parsende Datums- oder Zeitstring, der exakt dem angegebenen `$format` entsprechen muss, z. B. `"31.12.2024"` bei Format `"d.m.Y"`.
$timezone	?DateTimeZone	null	Optionale Zeitzone für das erstellte `DateTime`-Objekt. Wird `null` übergeben oder weggelassen, wird die aktuell konfigurierte Standard-Zeitzone verwendet. Enthält der `$datetime`-String selbst eine Zeitzonenangabe, wird dieser Parameter ignoriert.

Rückgabewert

Typ

DateTime|false

Beschreibung

Gibt bei Erfolg ein DateTime-Objekt zurück, das den geparsten Zeitpunkt repräsentiert. Schlägt das Parsen fehl (z. B. ungültiges Datum oder Format stimmt nicht überein), wird false zurückgegeben. Zur Fehleranalyse kann DateTime::getLastErrors() aufgerufen werden.

Beispiele

Deutsches Datumsformat parsen

<?php
// Datum im deutschen Format (TT.MM.JJJJ) in ein DateTime-Objekt umwandeln
$datum = date_create_from_format('d.m.Y', '24.12.2024');

if ($datum !== false) {
    echo $datum->format('Y-m-d') . PHP_EOL;       // ISO-Format
    echo $datum->format('l, d. F Y') . PHP_EOL;  // Vollständige Ausgabe
} else {
    echo 'Ungültiges Datum!';
}

2024-12-24 Tuesday, 24. December 2024

Datenbankzeitstempel mit Zeitzone verarbeiten

<?php
// SQL-Zeitstempel aus Datenbank mit expliziter Zeitzone parsen
$tz = new DateTimeZone('Europe/Berlin');
$dt = date_create_from_format('Y-m-d H:i:s', '2024-06-15 14:30:00', $tz);

if ($dt !== false) {
    echo 'Zeitstempel (UTC): ' . $dt->setTimezone(new DateTimeZone('UTC'))->format('Y-m-d H:i:s T') . PHP_EOL;
} else {
    // Detaillierte Fehlerinfos abrufen
    $fehler = DateTime::getLastErrors();
    print_r($fehler);
}

Zeitstempel (UTC): 2024-06-15 12:30:00 UTC

Fehlerbehandlung bei ungültigem Datum

<?php
// Ungültiges Datum erkennen und Fehler auswerten
$dt = date_create_from_format('d.m.Y', '31.02.2024');

if ($dt === false) {
    $fehler = DateTime::getLastErrors();
    echo 'Fehler beim Parsen:' . PHP_EOL;
    foreach ($fehler['errors'] as $pos => $meldung) {
        echo "  Position $pos: $meldung" . PHP_EOL;
    }
} else {
    // Achtung: PHP kann ungültige Daten ggf. "korrigieren" (Überlauf)
    echo $dt->format('Y-m-d');
}

Fehler beim Parsen: Position 0: The parsed date was invalid

// Wichtig · Fallstricke

Achtung bei unvollständigen Zeitangaben: Felder, die im Format nicht angegeben sind (z. B. Stunden, wenn nur das Datum geparst wird), werden mit Werten des aktuellen Zeitpunkts gefüllt. Um dieses Verhalten zu vermeiden und alle nicht angegebenen Felder auf Standardwerte (Epoche) zu setzen, kann das Format mit ! beginnen, z. B. '!d.m.Y'.

Validierung: PHP kann bei bestimmten ungültigen Daten (z. B. 30. Februar) trotzdem ein Objekt zurückgeben, indem es den Überlauf in den nächsten Monat verschiebt. Für strikte Validierung sollte DateTime::getLastErrors() auf warning_count und error_count geprüft werden.

Unveränderliche Variante: Für unveränderliche Datumsobjekte steht DateTimeImmutable::createFromFormat() bzw. date_create_immutable_from_format() zur Verfügung, die ein DateTimeImmutable-Objekt zurückgibt und in modernem Code bevorzugt werden sollte.

Siehe auch

DateTime::createFromFormat DateTimeImmutable::createFromFormat date_create date_create_immutable_from_format DateTime::getLastErrors date DateTimeZone