Datum-Parsing in PHP

Datumswerte kommen oft als einfache Strings an — aus einem Formulareingabefeld, einer CSV-Datei oder einer API-Antwort — und PHP kann ohne zusätzliche Angaben nicht wissen, wie diese Strings aufgebaut sind. Die Funktion date_parse_from_format() ermöglicht es, einen Datumsstring anhand eines expliziten Formats zu parsen und das Ergebnis zu prüfen, einschließlich etwaiger Fehler und Warnungen. Diese Seite erklärt, wie die Funktion arbeitet, wie ihr Rückgabewert zu lesen ist, wie Eingaben validiert werden und wann ein anderes Werkzeug wie DateTime oder strtotime() besser geeignet ist.

Was Datum-Parsing bedeutet

Datum-Parsing ist der Vorgang, einen String wie "2023-03-03" in strukturierte Daten umzuwandeln — Jahr, Monat, Tag und so weiter —, mit denen das Programm weiterarbeiten kann. Die Schwierigkeit liegt in der Mehrdeutigkeit: 03/04/2023 kann je nach Konvention der 4. März oder der 3. April sein, und 2023-13-45 sieht wie ein Datum aus, ist aber keines.

date_parse_from_format() beseitigt diese Mehrdeutigkeit, indem das genaue Format von Anfang an angegeben werden muss. Die Funktion liest den String strikt nach diesem Format und teilt mit, was gefunden wurde, sodass entschieden werden kann, ob die Eingabe gültig war.

Die Funktion date_parse_from_format()

date_parse_from_format() parst einen Datumsstring anhand eines bestimmten Formats und gibt ein assoziatives array zurück, das das geparste Datum beschreibt: Jahr, Monat, Tag, Stunde, Minute, Sekunde sowie Warnungen und Fehler, die beim Lesen des Strings aufgetreten sind.

Syntax

date_parse_from_format(string $format, string $datetime): array

• $format — ein Formatstring mit denselben Platzhaltern wie date(), zum Beispiel Y-m-d für 2023-03-03 oder d/m/Y für 03/03/2023.
• $datetime — der zu parsende Datumsstring.

Die Funktion gibt immer ein array zurück; sie wirft nie eine Ausnahme. Um zu wissen, ob das Parsing erfolgreich war, müssen die Schlüssel error_count und warning_count geprüft werden.

Ein einfaches Beispiel

Die Ausgabe dieses Codes lautet:

Array
(
    [year] => 2023
    [month] => 3
    [day] => 3
    [hour] => 10
    [minute] => 30
    [second] => 0
    [fraction] => 
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] => 
    [zone_type] => 1
    [zone] => -14400
    [is_dst] => 
)

Die Funktion hat "2023-03-03 10:30:00" anhand des Formats Y-m-d H:i:s geparst und jede Komponente befüllt. Einzelne Werte können direkt aus dem array gelesen werden, zum Beispiel $date_array['year'] oder $date_array['month']. Wenn eine Komponente im Formatstring fehlt, wird ihr Wert als false zurückgegeben (von print_r als leerer Wert dargestellt).

Benutzerdefinierte Formate parsen

Die Formatplatzhalter sind dieselben wie bei date(), sodass jedes Format, das erzeugt werden kann, auch geparst werden kann. Das folgende Beispiel liest ein europäisches Datum im Format Tag/Monat/Jahr:

<?php

$result = date_parse_from_format("d/m/Y", "03/03/2023");

echo "Day:   {$result['day']}\n";
echo "Month: {$result['month']}\n";
echo "Year:  {$result['year']}\n";

Dies gibt aus:

Day:   3
Month: 3
Year:  2023

Da im Format nur d, m und Y vorkommen, werden die Schlüssel hour, minute und second als false zurückgegeben.

Das Ergebnis validieren: Fehler und Warnungen

date_parse_from_format() wirft nie eine Ausnahme — selbst bei fehlerhafter Eingabe gibt die Funktion ein array zurück. Zwei Schlüssel zeigen an, ob die Eingabe verwendbar war:

• error_count zählt Zeichen, die überhaupt nicht zum Format gepasst haben.
• warning_count zählt Werte, die zum Format gepasst haben, aber keinen Sinn ergeben, wie Monat 13 oder Tag 45.

Ein String, der nicht zum Format passt, erzeugt Fehler:

<?php

// Expecting Y-m-d but the input is d/m/Y
$result = date_parse_from_format("Y-m-d", "03/03/2023");

echo "Errors:   {$result['error_count']}\n";
print_r($result['errors']);

Errors:   5
Array
(
    [2] => Unexpected data found.
    [5] => Unexpected data found.
    [8] => Trailing data
)

Ein String, der zum Format passt, aber kein echtes Datum darstellt, erzeugt stattdessen eine Warnung:

<?php

$result = date_parse_from_format("Y-m-d", "2023-13-45");

echo "Warnings: {$result['warning_count']}\n";
print_r($result['warnings']);

Warnings: 1
Array
(
    [10] => The parsed date was invalid
)

Beide Zähler sollten immer geprüft werden, bevor den geparsten Werten vertraut wird:

if ($result['error_count'] === 0 && $result['warning_count'] === 0) {
    // safe to use $result['year'], $result['month'], etc.
}

Wann eine andere Funktion besser geeignet ist

date_parse_from_format() ist am besten geeignet, wenn ein detaillierter, formatbewusster Bericht benötigt wird — insbesondere zur Validierung von Eingaben. Wenn nur ein nutzbarer Datumswert benötigt wird, sind andere Werkzeuge praktischer:

• DateTime::createFromFormat($format, $string) gibt ein einsatzbereites DateTime-Objekt zurück, das formatiert oder für Berechnungen verwendet werden kann. Siehe PHP date and time.
• strtotime() erkennt das Format automatisch und gibt einen Unix-Zeitstempel zurück — praktisch für gängige, eindeutige Strings, aber riskanter bei länderspezifischen Formaten.
• date_parse() funktioniert wie diese Funktion, jedoch ohne Formatstring; die Funktion versucht, das Datum selbst zu interpretieren.

Fazit

date_parse_from_format() parst einen Datumsstring anhand eines expliziten Formats und gibt ein detailliertes assoziatives array zurück, was sie ideal zur Validierung von benutzerseitig eingegebenen Daten macht. Es ist zu beachten, dass die Funktion nie wirft — error_count und warning_count müssen geprüft werden, bevor das Ergebnis verwendet wird. Wenn ein DateTime-Objekt oder ein Zeitstempel benötigt wird, sollte stattdessen DateTime::createFromFormat() oder strtotime() verwendet werden.

Übungen