DateException — Klasse · PHP-Referenz

Signatur

class DateException extends RuntimeException

Beschreibung

DateException ist die gemeinsame Elternklasse aller Exceptions, die von der objektorientierten Datum/Uhrzeit-API (z. B. DateTimeImmutable, DateTime, DateTimeZone) geworfen werden, wenn eine Eingabe fehlerhaft oder nicht parsebar ist. Sie erweitert RuntimeException und bildet damit die Wurzel einer eigenen Exception-Hierarchie für Datumsprobleme.

Durch das Abfangen von DateException lassen sich alle datumsbezogenen Ausnahmen mit einem einzigen catch-Block behandeln, ohne auf spezifischere Unterklassen wie DateInvalidOperationException, DateInvalidTimezoneException oder DateMalformedStringException eingehen zu müssen.

Die Klasse selbst fügt keine eigenen Methoden oder Eigenschaften hinzu – sie dient primär als strukturelles Typisierungs-Werkzeug für selektives Exception-Handling. In älteren PHP-Versionen (vor 8.3) lieferten viele Datum/Uhrzeit-Funktionen bei Fehlern stattdessen false oder gaben Warnungen aus; seit 8.3 wird konsequent auf Exceptions umgestellt.

Wann immer Code Datumseingaben aus externen Quellen (Formulare, Datenbank, APIs) verarbeitet, empfiehlt sich ein try/catch-Block, der mindestens DateException abfängt, um robuste Fehlerbehandlung zu gewährleisten.

Beispiele

Ungültigen Datumsstring abfangen

<?php
use DateMalformedStringException;
use DateException;

try {
    $dt = new DateTimeImmutable('kein-gültiges-datum');
} catch (DateException $e) {
    echo 'Datum-Fehler: ' . $e->getMessage();
}

Datum-Fehler: Failed to parse time string (kein-gültiges-datum) at position 0 (k): The timezone could not be found in the database

Differenzierte Fehlerbehandlung mit Unterklassen

<?php
use DateInvalidTimezoneException;
use DateMalformedStringException;
use DateException;

function parseDatum(string $input, string $timezone): DateTimeImmutable {
    try {
        $tz = new DateTimeZone($timezone);
        return new DateTimeImmutable($input, $tz);
    } catch (DateInvalidTimezoneException $e) {
        // Spezifisch: ungültige Zeitzone
        throw new InvalidArgumentException('Unbekannte Zeitzone: ' . $timezone, 0, $e);
    } catch (DateMalformedStringException $e) {
        // Spezifisch: nicht parsbares Datum
        throw new InvalidArgumentException('Ungültiger Datumsstring: ' . $input, 0, $e);
    } catch (DateException $e) {
        // Alles andere aus der Datum/Uhrzeit-Familie
        throw new RuntimeException('Allgemeiner Datumsfehler', 0, $e);
    }
}

try {
    $dt = parseDatum('2024-13-45', 'Europe/Berlin');
} catch (InvalidArgumentException $e) {
    echo $e->getMessage() . PHP_EOL;
}

try {
    $dt = parseDatum('2024-06-15', 'Mars/Olympus');
} catch (InvalidArgumentException $e) {
    echo $e->getMessage() . PHP_EOL;
}

Ungültiger Datumsstring: 2024-13-45 Unbekannte Zeitzone: Mars/Olympus

// Wichtig · Fallstricke

Verfügbarkeit: DateException als formale Klasse existiert erst seit PHP 8.3. In früheren PHP-Versionen (8.0–8.2) gab die objektorientierte Datum-API bei Fehlern teilweise false zurück oder löste generische Exception-Objekte aus. Code, der PHP < 8.3 unterstützen muss, sollte weiterhin auf Rückgabewerte prüfen.

Hierarchie: Direkte Unterklassen sind u. a. DateInvalidOperationException, DateInvalidTimezoneException und DateMalformedStringException. Beim Abfangen von der spezifischsten zur allgemeinsten Klasse vorgehen, um gezieltes Fehler-Handling zu ermöglichen.

Eigene Erweiterung: Eigene Datums-Exceptions können DateException erweitern, um sich nahtlos in die bestehende Hierarchie einzufügen.

Siehe auch

DateMalformedStringException DateInvalidTimezoneException DateInvalidOperationException DateTimeImmutable DateTime DateTimeZone RuntimeException