Signatur
Beschreibung
DateTimeInterface wurde eingeführt, um in Typ-Deklarationen (Parameter, Rückgabewerte, Eigenschaften) sowohl DateTime- als auch DateTimeImmutable-Objekte akzeptieren zu können. Damit lassen sich flexible APIs schreiben, die mit beiden Datum-Klassen umgehen können, ohne auf eine bestimmte Implementierung festgelegt zu sein.
Es ist nicht möglich, dieses Interface in eigenem Code zu implementieren. Es ist ausschließlich für die Verwendung in Typ-Deklarationen gedacht. Eigene Datum-Klassen sollten stattdessen entweder DateTime oder DateTimeImmutable erweitern.
Das Interface definiert eine Reihe von Methoden, die beide Klassen gemeinsam haben: format(), getTimestamp(), getTimezone(), getOffset(), diff() sowie die magische Methode __wakeup() und ab PHP 8.0 auch __serialize() und __unserialize(). Durch die Verwendung von DateTimeInterface als Typ kann Code geschrieben werden, der immutabel-sicher oder mutabel arbeitet – je nachdem, welches Objekt übergeben wird.
In der Praxis empfiehlt es sich, in allen öffentlichen APIs DateTimeInterface als Parametertyp zu verwenden und intern DateTimeImmutable zu bevorzugen, um unerwünschte Seiteneffekte durch versehentliche Mutation zu vermeiden.
Beispiele
DateTimeInterface als Parametertyp in einer Funktion
<?php
function formatiereDatum(DateTimeInterface $datum, string $format = 'd.m.Y H:i'): string {
return $datum->format($format);
}
// Funktioniert mit DateTime ...
$mutableDate = new DateTime('2024-06-15 14:30:00');
echo formatiereDatum($mutableDate) . PHP_EOL;
// ... und mit DateTimeImmutable
$immutableDate = new DateTimeImmutable('2024-06-15 14:30:00');
echo formatiereDatum($immutableDate) . PHP_EOL;DateTimeInterface in einer Klassen-Eigenschaft (PHP 8.0+)
<?php
class Termin {
public function __construct(
private string $titel,
private DateTimeInterface $startzeit,
private DateTimeInterface $endzeit
) {}
public function getDauer(): string {
$diff = $this->startzeit->diff($this->endzeit);
return sprintf('%d Stunden, %d Minuten', $diff->h, $diff->i);
}
public function __toString(): string {
return sprintf(
'%s: %s bis %s',
$this->titel,
$this->startzeit->format('d.m.Y H:i'),
$this->endzeit->format('H:i')
);
}
}
$termin = new Termin(
'Team-Meeting',
new DateTimeImmutable('2024-06-15 09:00'),
new DateTimeImmutable('2024-06-15 10:30')
);
echo $termin . PHP_EOL;
echo 'Dauer: ' . $termin->getDauer() . PHP_EOL;Differenz zweier Datumsobjekte über das Interface
<?php
function tageZwischen(DateTimeInterface $von, DateTimeInterface $bis): int {
return (int) $von->diff($bis)->days;
}
$start = new DateTimeImmutable('2024-01-01');
$ende = new DateTime('2024-12-31');
echo 'Tage in 2024: ' . tageZwischen($start, $ende) . PHP_EOL;// Wichtig · Fallstricke
Nicht implementierbar: Eigene Klassen dürfen DateTimeInterface nicht direkt implementieren (implements DateTimeInterface). PHP wirft hierbei einen fatalen Fehler. Stattdessen sollte DateTime oder DateTimeImmutable erweitert werden.
Immutabilität bevorzugen: Da DateTimeInterface sowohl mutable (DateTime) als auch immutable (DateTimeImmutable) Objekte akzeptiert, sollte innerhalb einer Funktion, die DateTimeInterface empfängt, das Objekt niemals modifiziert werden (z. B. durch modify() auf einem DateTime-Objekt), da dies für den Aufrufer unerwartete Seiteneffekte erzeugen kann.
Konstanten: Das Interface definiert die Konstanten DateTimeInterface::ATOM, DateTimeInterface::ISO8601, DateTimeInterface::RFC2822 u. a. für gängige Datumsformate, die direkt genutzt werden können.