date_interval_format()

Einführung

DateInterval::format() wandelt ein Datumsintervall — die Lücke zwischen zwei Zeitpunkten — in einen menschenlesbaren string um. Durch die Übergabe eines Formatstrings aus %-Platzhaltern bestimmst du genau, was angezeigt wird (Tage, Stunden, das Vorzeichen usw.).

Diese Seite behandelt die Syntax, alle Formatcodes, den wichtigen Unterschied zwischen %a und %d, die Funktionsweise von Auffüllung und Vorzeichen sowie mehrere ausführbare Beispiele.

Was ist ein DateInterval?

Ein DateInterval repräsentiert eine Zeitspanne (zum Beispiel „1 Jahr, 3 Monate, 12 Tage"), kein konkretes Datum. Du erhältst ihn fast immer von DateTime::diff(), das ein Datum von einem anderen subtrahiert:

<?php

$start = new DateTime('2022-03-03 00:00:00');
$end   = new DateTime('2023-06-15 14:30:00');

$interval = $start->diff($end); // returns a DateInterval object
echo $interval->format('%y years, %m months, %d days');

1 years, 3 months, 12 days

format() ist die Methode, die dieses Objekt als string ausgibt. (Du kannst Intervalle auch direkt mit dem DateInterval-Konstruktor erstellen oder sie mit DateTime::add() und DateTime::sub() auf Daten anwenden.)

Syntax

public DateInterval::format(string $format): string

• $format — ein string mit beliebigem Literaltext und %-Formatcodes.
• Gibt zurück: das formatierte Intervall als string.

Jedes Zeichen, das nicht Teil eines %-Codes ist, wird wörtlich ausgegeben, sodass %d days beispielsweise 12 days ergibt. Um ein wörtliches Prozentzeichen auszugeben, verwende %%.

%a vs. %d — die häufigste Fehlerquelle

Diese beiden sehen ähnlich aus, bedeuten aber unterschiedliche Dinge:

• %a ist die Gesamtanzahl der Tage über das gesamte Intervall hinweg.
• %d sind die Tage, die übrig bleiben, nachdem ganze Jahre und Monate herausgerechnet wurden.

<?php

$start = new DateTime('2022-03-03');
$end   = new DateTime('2023-06-15');
$interval = $start->diff($end);

echo $interval->format('%a total days') . "\n";          // every day, counted flat
echo $interval->format('%y y, %m m, %d d') . "\n";        // broken into parts

469 total days
1 y, 3 m, 12 d

Verwende %a, wenn du eine einzelne Zahl „wie viele Tage liegen dazwischen" möchtest, und %d, wenn du Jahre/Monate/Tage zusammen anzeigst.

Formatcodes

Kleinschreibung liefert den rohen Wert; Großschreibung füllt auf mindestens zwei Stellen mit Nullen auf. Es gibt keinen eingebauten Code für Gesamtstunden, -minuten oder -sekunden — nur %a aggregiert.

<?php

$start = new DateTime('2022-03-03 00:00:00');
$end   = new DateTime('2023-06-15 14:30:05');
$interval = $start->diff($end);

echo $interval->format('Padded: %Y-%M-%D %H:%I:%S');

Padded: 01-03-12 14:30:05

Beispiel 1: Gesamtanzahl der Tage zwischen zwei Daten

Einen vorzeichenbehafteten Tagescount anzeigen

Ausgabe:

+365 days

%R gibt das Vorzeichen des Intervalls aus und %a die Gesamtanzahl der Tage. Da $datetime2 nach $datetime1 liegt, ist das Vorzeichen +. Tausche die beiden Daten (oder rufe diff() in der umgekehrten Reihenfolge auf) und %R wird zu -.

Beispiel 2: Tage, Stunden und Minuten

Mehrere Einheiten in einem string kombinieren

Ausgabe:

+365 days 00 hours 00 minutes

Beide Zeiten sind Mitternacht, daher sind Stunden und Minuten null. Beachte, dass sie dennoch als 00 ausgegeben werden, da %h und %i einstellige Nullwerte bereits auffüllen — bei Werten von 1 bis 9 werden Kleinbuchstaben-Codes jedoch nicht aufgefüllt; verwende %H / %I, wenn du immer zwei Stellen möchtest.

Wann würde ich das verwenden?

• „Mitglied seit" / „vor X Tagen"-Labels — berechne den Unterschied mit diff() und formatiere %a days.
• Countdowns — zeige %d days %h hours %i minutes bis zu einer Deadline.
• Dauerberichte — rendere ein gespeichertes DateInterval (z. B. eine Aufgabendauer) für eine UI oder Rechnung.

Um ein tatsächliches Datum oder eine Uhrzeit statt eines Intervalls zu formatieren, verwende DateTime::format() oder die prozedurale date()-Funktion — sie verwenden einen völlig anderen Platzhaltersatz als DateInterval::format().

Fazit

DateInterval::format() gibt den Abstand zwischen zwei Daten mithilfe von %-präfixierten Codes aus. Merke dir die zwei wichtigen Regeln: %a ist die Gesamtanzahl der Tage, während %d die verbleibenden Tage sind, und Großbuchstaben-Codes füllen mit Nullen auf, Kleinbuchstaben nicht. Für mehr Informationen zur Erstellung des Intervalls selbst, siehe DateTime::diff().

Übungen