Signatur
Beschreibung
date_diff() ist die prozedurale Entsprechung der Methode DateTime::diff() und berechnet den zeitlichen Abstand zwischen zwei Datums-/Zeitangaben. Das Ergebnis ist ein DateInterval-Objekt, das die Differenz in Jahren, Monaten, Tagen, Stunden, Minuten und Sekunden aufschlüsselt.
Die Funktion akzeptiert alle Objekte, die das Interface DateTimeInterface implementieren, also sowohl DateTime als auch DateTimeImmutable. Standardmäßig kann die Differenz negativ sein (wenn $baseObject nach $targetObject liegt). Mit dem Parameter $absolute = true wird stets ein positiver Wert zurückgegeben.
Das zurückgegebene DateInterval-Objekt enthält unter anderem die Eigenschaften y (Jahre), m (Monate), d (Tage), h (Stunden), i (Minuten) und s (Sekunden) sowie das Flag invert, das angibt, ob die Differenz negativ ist. Über DateInterval::format() lässt sich das Ergebnis komfortabel als Zeichenkette ausgeben.
Typische Einsatzgebiete sind die Berechnung von Altersangaben, verbleibenden Laufzeiten, Countdown-Anzeigen oder der Dauer zwischen zwei Ereignissen in Webanwendungen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $baseObject Pflicht | DateTimeInterface | Das Ausgangsdatum, von dem aus die Differenz berechnet wird. Kann ein DateTime- oder DateTimeImmutable-Objekt sein. |
|
| $targetObject Pflicht | DateTimeInterface | Das Zieldatum, bis zu dem die Differenz berechnet wird. Kann ein DateTime- oder DateTimeImmutable-Objekt sein. |
|
| $absolute | bool | false | Wenn true, wird der absolute (stets positive) Wert der Differenz zurückgegeben, unabhängig davon, welches Datum früher liegt. |
Rückgabewert
DateInterval-Objekt zurück, das die Differenz zwischen den beiden Datumsobjekten repräsentiert. Die Eigenschaft invert ist 1, wenn das Basisdatum nach dem Zieldatum liegt (negative Differenz), andernfalls 0.Beispiele
Altersberechnung einer Person
<?php
$geburtsdatum = new DateTimeImmutable('1990-06-15');
$heute = new DateTimeImmutable('today');
$diff = date_diff($geburtsdatum, $heute);
echo 'Alter: ' . $diff->y . ' Jahre, ' . $diff->m . ' Monate, ' . $diff->d . ' Tage';
// Beispiel-Ausgabe (je nach aktuellem Datum):
// Alter: 34 Jahre, 7 Monate, 12 TageVerbleibende Zeit bis zu einem Ereignis
<?php
$jetzt = new DateTimeImmutable('now');
$ereignis = new DateTimeImmutable('2025-12-31 00:00:00');
$diff = date_diff($jetzt, $ereignis, true); // absolut = true
echo 'Noch ' . $diff->format('%a Tage, %h Stunden und %i Minuten') . ' bis Silvester.';
// Beispiel-Ausgabe:
// Noch 243 Tage, 8 Stunden und 32 Minuten bis Silvester.Negative Differenz erkennen mit dem invert-Flag
<?php
$frueheres = new DateTime('2024-01-01');
$spaeteres = new DateTime('2023-01-01');
$diff = date_diff($frueheres, $spaeteres);
if ($diff->invert === 1) {
echo 'Das Zieldatum liegt in der Vergangenheit.';
} else {
echo 'Das Zieldatum liegt in der Zukunft.';
}
// Ausgabe:
// Das Zieldatum liegt in der Vergangenheit.// Wichtig · Fallstricke
Fallstrick bei Zeitzonen: Wenn die beiden DateTimeInterface-Objekte unterschiedliche Zeitzonen verwenden, kann das Ergebnis unerwartete Werte liefern. Es empfiehlt sich, beide Objekte in der gleichen Zeitzone zu erstellen oder zuvor zu normalisieren.
Nur Kalendereinheiten: Das DateInterval-Objekt zeigt die Differenz in aufgeschlüsselten Einheiten (Jahre, Monate, Tage …). Die Gesamtanzahl der Tage ist über die Eigenschaft days abrufbar, die bei Verwendung von date_diff() stets befüllt wird (im Gegensatz zu manuell erzeugten DateInterval-Objekten, bei denen days den Wert false haben kann).
Schaltjahre und Sommerzeit: Die Funktion berücksichtigt Schaltjahre korrekt. Bei Zeitumstellungen (Sommer-/Winterzeit) können jedoch Stunden-Differenzen geringfügig abweichen, da date_diff() Kalender-basiert (nicht sekunden-basiert) rechnet.