PHP date_create_from_format Funktion: Syntax und Beispiele

Die Funktion date_create_from_format() parst einen Datums-string nach Ihrem Format — nicht nach dem Format, das PHP errät — und gibt ein DateTime-object zurück. Verwenden Sie sie immer dann, wenn Sie ein Datum in einem festen, nicht standardmäßigen Layout erhalten (ein CSV-Export, eine Drittanbieter-API, ein Benutzerformular) und es zuverlässig einlesen müssen.

Diese Seite behandelt die Syntax, ausführbare Beispiele, den Zeitzonenparameter, die Erkennung von Parse-Fehlern und die Unterschiede zu strtotime() und date_parse_from_format().

Syntax

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

• $format — das Layout des Eingabe-strings, geschrieben mit denselben Formatzeichen wie die Funktion date(). Zum Beispiel entspricht "Y-m-d H:i:s" dem string "2023-03-02 17:30:45".
• $datetime — der zu parsende Datums-string. Sein Layout muss mit $format übereinstimmen.
• $timezone — (optional) eine DateTimeZone für das resultierende object. Wird dieser Parameter weggelassen, wird die aktuelle Standardzeitzone (gesetzt via date_default_timezone_set()) verwendet. Der Parameter wird ignoriert, wenn $format bereits ein Zeitzonenzeichen wie e, O, P oder T enthält.

Bei Erfolg gibt die Funktion ein DateTime-object zurück, oder false, wenn der string nicht dem Format entspricht.

date_create_from_format() ist der prozedurale Alias der statischen Methode DateTime::createFromFormat() — beide verhalten sich identisch.

Beispiele

Parsen eines Standard-Datums-strings

Die Funktion liest "2023-03-02 17:30:45" gemäß "Y-m-d H:i:s" und gibt ein DateTime-object zurück. Durch den Aufruf von format() darauf lässt sich das Datum in jedem beliebigen Layout neu rendern.

Neuformatieren eines nicht-standardmäßigen Datums

Hier verwendet die Eingabe einen Tag, einen dreistelligen Monatsnamen und eine vierstellige Jahreszahl (j-M-Y). Die Ausgabe erfolgt in ISO-Reihenfolge (Y-m-d) — Beweis dafür, dass Sie ein Datum, sobald es ein DateTime-object ist, beliebig anzeigen können.

Zurücksetzen der Uhrzeit mit !

Wenn Ihr Format keine Zeitfelder enthält, werden die fehlenden Teile standardmäßig auf die aktuelle Stunde, Minute und Sekunde gesetzt — was für einen reinen Datumswert selten erwünscht ist. Stellen Sie dem Format ! voran, um alle nicht angegebenen Felder auf die Unix-Epoche zurückzusetzen (00:00:00):

<?php

$date = date_create_from_format('!Y-m-d', '2023-03-02');
echo $date->format('Y-m-d H:i:s'); // Output: 2023-03-02 00:00:00

Angabe einer Zeitzone

<?php

$tz = new DateTimeZone('Europe/Paris');
$date = date_create_from_format('Y-m-d H:i:s', '2023-03-02 17:30:45', $tz);
echo $date->format('Y-m-d H:i:s P'); // Output: 2023-03-02 17:30:45 +01:00

Das dritte Argument verankert das geparste Datum in der Pariser Zeit, sodass das P-Token den Offset +01:00 ausgibt.

Umgang mit Parse-Fehlern

Wenn der string nicht dem Format entspricht, gibt die Funktion false zurück, anstatt eine Ausnahme zu werfen. Prüfen Sie dies immer und lesen Sie DateTime::getLastErrors() für die Details:

<?php

$date = date_create_from_format('Y-m-d', 'not-a-date');

if ($date === false) {
    $errors = DateTime::getLastErrors();
    echo "Parse failed: {$errors['error_count']} error(s)\n";
    // Output: Parse failed: 3 error(s)
}

Da false falsy ist, funktioniert auch ein einfaches if (!$date) — ein strikter === false-Check ist jedoch sicherer, wenn ein leerer Wert legitim etwas anderes bedeuten könnte.

Vergleich mit anderen Datumsfunktionen

Greifen Sie auf date_create_from_format() zurück, wenn das Layout festgelegt ist und Sie ein vollständiges DateTime-object zum Bearbeiten benötigen. Verwenden Sie strtotime() für lose, umgangssprachliche strings wie "next Friday" und date_parse_from_format(), wenn Sie nur die rohen Jahr/Monat/Tag-Zahlen benötigen, ohne ein object zu erstellen.

Fazit

date_create_from_format() wandelt einen string in einem beliebigen, bekannten Layout in ein DateTime-object um, das Sie mit der übrigen Datums-API von PHP formatieren, vergleichen und verschieben können. Denken Sie daran, das !-Präfix für reine Datumswerte zu verwenden, eine DateTimeZone zu übergeben, wenn die Quellzeitzone wichtig ist, und immer gegen den false-Rückgabewert abzusichern.

Übungen