date_interval_format — Funktion · PHP-Referenz

Signatur

date_interval_format(DateInterval $interval, string $format): string

Beschreibung

date_interval_format() ist ein prozeduraler Alias für DateInterval::format(). Die Funktion nimmt ein DateInterval-Objekt und einen Formatstring entgegen und gibt die darin enthaltene Zeitspanne als lesbare Zeichenkette zurück.

Der Formatstring unterstützt spezielle Platzhalter, die jeweils mit einem Prozentzeichen (%) eingeleitet werden: %Y (Jahre, zweistellig), %y (Jahre ohne führende Null), %M (Monate, zweistellig), %m (Monate ohne führende Null), %D (Tage, zweistellig), %d (Tage ohne führende Null), %H (Stunden, zweistellig), %i (Minuten, zweistellig), %s (Sekunden, zweistellig), %a (Gesamtzahl der Tage), %R (Vorzeichen, + oder -) und %% (ein literales Prozentzeichen).

Typische Anwendungsfälle sind die menschenlesbare Darstellung von Zeitdifferenzen, z. B. das Alter einer Person, die verbleibende Zeit bis zu einem Ereignis oder die Dauer eines Vorgangs.

Da es sich um einen Alias handelt, ist der objektorientierte Stil mit $interval->format($format) semantisch identisch und wird in modernem Code bevorzugt.

Parameter

Name	Typ	Default	Beschreibung
$interval Pflicht	DateInterval		Das zu formatierende `DateInterval`-Objekt, z. B. erzeugt durch `DateInterval::createFromDateString()` oder `DateTime::diff()`.
$format Pflicht	string		Formatstring mit `%`-Platzhaltern. Gültige Platzhalter sind u. a. `%Y`, `%m`, `%d`, `%H`, `%i`, `%s`, `%a`, `%R` und `%%`.

Rückgabewert

Typ

string

Beschreibung

Gibt die formatierte Zeitspanne als Zeichenkette zurück. Im Gegensatz zu date() gibt es hier keinen false-Rückgabewert; die Funktion liefert immer einen String.

Beispiele

Differenz zwischen zwei Datumsangaben ausgeben

<?php
$start = new DateTime('1990-05-15');
$end   = new DateTime('2024-03-20');

$interval = $start->diff($end);

echo date_interval_format($interval, '%Y Jahre, %m Monate und %d Tage');
// Alternativ (OOP): echo $interval->format('%Y Jahre, %m Monate und %d Tage');

33 Jahre, 10 Monate und 05 Tage

Verbleibende Zeit bis zu einem Ereignis mit Vorzeichen

<?php
$jetzt     = new DateTimeImmutable();
$deadline  = new DateTimeImmutable('2025-12-31 23:59:59');

$interval = $jetzt->diff($deadline);

if ($interval->invert === 0) {
    echo 'Noch ' . date_interval_format($interval, '%a Tage, %H:%I:%S');
} else {
    echo 'Deadline überschritten!';
}

Noch 312 Tage, 08:45:10

Dauer aus einem Intervall-String erzeugen und formatieren

<?php
$interval = DateInterval::createFromDateString('2 years 3 months 10 days');

echo date_interval_format($interval, '%y Jahr(e), %m Monat(e), %d Tag(e)');

2 Jahr(e), 3 Monat(e), 10 Tag(e)

// Wichtig · Fallstricke

Achtung: Der Platzhalter %a liefert nur dann einen korrekten Wert (Gesamtanzahl der Tage), wenn das DateInterval-Objekt durch DateTime::diff() oder DateTimeImmutable::diff() erzeugt wurde. Bei manuell erstellten Intervallen (z. B. new DateInterval('P1Y') oder DateInterval::createFromDateString()) kann %a den Wert (unknown) zurückgeben.

Negative Intervalle (wenn das Enddatum vor dem Startdatum liegt) können über das Attribut $interval->invert erkannt werden; %R gibt entsprechend + oder - aus.

In modernem PHP-Code wird der objektorientierte Stil $interval->format() bevorzugt. date_interval_format() ist lediglich ein prozeduraler Alias und verhält sich identisch.

Siehe auch

DateInterval::format DateInterval DateTime::diff date_diff date_create date