date_parse()

Einführung

Die Funktion date_parse() in PHP nimmt einen lesbaren Datumsstring und zerlegt ihn in seine einzelnen Bestandteile — Jahr, Monat, Tag, Stunde, Minute, Sekunde — und gibt sie als assoziatives array zurück. Entscheidend ist, dass sie außerdem alle Warnungen und Fehler meldet, die beim Interpretieren des Strings aufgetreten sind, was sie zu einem nützlichen Werkzeug zur Validierung von Datumseingaben macht, bevor man damit arbeitet.

Im Gegensatz zu strtotime(), das einen Datumsstring in einen einzelnen Unix-Zeitstempel umwandelt, hält date_parse() jeden Bestandteil separat und verwirft niemals die Diagnoseinformationen. Das ist der Hauptgrund, diese Funktion zu verwenden: wenn man nicht nur wissen möchte, welches Datum vorliegt, sondern auch, ob die Eingabe tatsächlich ein gültiges Datum ist.

Diese Seite behandelt die Syntax, die vollständige Struktur des zurückgegebenen arrays, das Auslesen von Warnungen und Fehlern sowie den Vergleich von date_parse() mit verwandten Funktionen.

Syntax

date_parse(string $datetime): array

Die Funktion gibt immer ein array zurück (sie gibt niemals false zurück); wenn die Analyse fehlschlägt, wird der Fehler im Schlüssel errors beschrieben, nicht durch den Rückgabewert signalisiert.

Parameter

$datetime — ein string, der das zu analysierende Datum/die Uhrzeit repräsentiert. Er akzeptiert dieselben flexiblen Formate, die PHPs interner Datums-Parser versteht, zum Beispiel:

• '2022-03-03 15:30:45' — vollständiges Datum und Uhrzeit im ISO-Stil
• 'July 4, 2023' — natürliche Sprache
• 'now', 'tomorrow', '+1 week' — relative Ausdrücke

Fehlt ein Bestandteil im string (z. B. wenn keine Uhrzeit angegeben ist), wird der entsprechende Schlüssel als leerer Wert zurückgegeben, anstatt weggelassen zu werden.

Rückgabewert

Die Funktion gibt ein assoziatives array mit folgenden Schlüsseln zurück:

• year, month, day — die Datumsbestandteile (Integer oder leer, wenn nicht vorhanden)
• hour, minute, second — die Uhrzeitbestandteile (Integer oder leer, wenn nicht vorhanden)
• fraction — der Bruchteil der Sekunden (ein Float, z. B. 0)
• warning_count — die Anzahl der beim Analysieren erzeugten Warnungen
• warnings — ein array von Warnungen, indiziert nach der Zeichenposition in der Eingabe
• error_count — die Anzahl der beim Analysieren erzeugten Fehler
• errors — ein array von Fehlern, indiziert nach der Zeichenposition in der Eingabe
• is_localtime — ob der string Zeitzoneninformationen enthielt

Wenn is_localtime true ist, beschreiben zusätzliche Schlüssel wie zone_type, zone und is_dst die Zeitzone.

Einfaches Beispiel

Analysieren wir einen vollständigen Datums- und Uhrzeitstring:

Ausgabe:

Array
(
    [year] => 2022
    [month] => 3
    [day] => 3
    [hour] => 15
    [minute] => 30
    [second] => 45
    [fraction] => 0
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] =>
)

Jeder Bestandteil ist nun einzeln verfügbar — zum Beispiel ist $date_arr['month'] gleich 3. Da sowohl error_count als auch warning_count den Wert 0 haben, wissen wir, dass der string ein sauberes, gültiges Datum war.

Unvollständiges Datum analysieren

date_parse() erfordert kein vollständiges Datum. Wenn man nur ein Datum ohne Uhrzeit übergibt, werden die Uhrzeitschlüssel leer zurückgegeben:

<?php

$result = date_parse('July 4, 2023');
echo "Year: {$result['year']}\n";
echo "Month: {$result['month']}\n";
echo "Day: {$result['day']}\n";
echo "Hour: '{$result['hour']}'\n"; // empty — no time was given

Ausgabe:

Year: 2023
Month: 7
Day: 4
Hour: ''

Das ist praktisch, wenn man Datumsangaben ohne Uhrzeit akzeptiert und die einzelnen Teile ohne eigenen Parser benötigt.

Ungültige Datumsangaben mit Warnungen erkennen

Hier zeigt date_parse() seine Stärke. Betrachten wir den 30. Februar — ein Datum, das nicht existiert. Der Parser gibt trotzdem Werte zurück, markiert das Problem jedoch in warnings:

<?php

$result = date_parse('2023-02-30');

if ($result['warning_count'] > 0) {
    foreach ($result['warnings'] as $position => $message) {
        echo "Warning at position $position: $message\n";
    }
}

Ausgabe:

Warning at position 11: The parsed date was invalid

Prüfen Sie stets error_count (der string konnte überhaupt nicht verstanden werden) und warning_count (der string wurde verstanden, beschreibt aber ein unmögliches Datum), bevor Sie den geparsten Bestandteilen vertrauen. Für eine strikte Ja/Nein-Kalenderprüfung eines bestimmten Jahr-Monat-Tag-Werts kombinieren Sie dies mit checkdate().

Wann date_parse() gegenüber verwandten Funktionen einsetzen

Wenn Sie ein Datum später ausgeben möchten, lesen Sie date() zum Formatieren der Bestandteile als string.

Fazit

Die Funktion date_parse() bietet eine unkomplizierte Möglichkeit, einen Datumsstring in seine einzelnen Bestandteile zu zerlegen und dabei auftretende Warnungen und Fehler zu melden. Diese doppelte Rolle — Extraktion und Validierung — macht sie besonders nützlich zum Prüfen von Benutzerdaten vor deren Verarbeitung. Kombinieren Sie sie mit checkdate() für eine strenge Validierung oder mit strtotime() und DateTime, wenn Sie Zeitstempel oder vollständige Datumsobiekte benötigen.

Übungen