date_interval_format()

Introduction

DateInterval::format() transforme un intervalle de date — l'écart entre deux instants — en une chaîne lisible par l'humain. Vous décidez exactement ce qui est affiché (jours, heures, le signe, etc.) en passant une chaîne de format composée de balises %.

Cette page couvre la syntaxe, tous les codes de format, la différence cruciale entre %a et %d, le fonctionnement du remplissage et du signe, ainsi que plusieurs exemples exécutables.

Qu'est-ce qu'un DateInterval ?

Un DateInterval représente une durée (par exemple « 1 an, 3 mois, 12 jours »), et non une date précise. Vous l'obtenez presque toujours depuis DateTime::diff(), qui soustrait une date d'une autre :

<?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() est la méthode qui rend cet objet sous forme de chaîne. (Vous pouvez également construire des intervalles directement avec le constructeur DateInterval ou les appliquer à des dates avec DateTime::add() et DateTime::sub().)

Syntaxe

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

• $format — une chaîne contenant du texte littéral ainsi que des codes de format %.
• Retourne l'intervalle formaté sous forme de chaîne.

Tout caractère qui ne fait pas partie d'un code % est affiché littéralement, donc %d days produit quelque chose comme 12 days. Pour afficher un signe pourcentage littéral, utilisez %%.

%a vs %d — le piège le plus courant

Ces deux codes se ressemblent mais ont des significations différentes :

• %a est le nombre total de jours sur l'ensemble de l'intervalle.
• %d est le nombre de jours restants après déduction des années et des mois entiers.

<?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

Utilisez %a lorsque vous voulez un seul nombre indiquant « combien de jours d'écart », et %d lorsque vous affichez années/mois/jours ensemble.

Codes de format

Les codes en minuscules donnent la valeur brute ; les codes en majuscules sont complétés à au moins deux chiffres. Il n'existe pas de code intégré pour le total d'heures, de minutes ou de secondes — seul %a agrège.

<?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

Exemple 1 : Total de jours entre deux dates

Afficher un nombre de jours signé

Résultat :

+365 days

%R affiche le signe de l'intervalle et %a affiche le nombre total de jours. Comme $datetime2 est après $datetime1, le signe est +. Inversez les deux dates (ou utilisez diff() dans l'autre sens) et %R devient -.

Exemple 2 : Jours, heures et minutes

Combiner plusieurs unités en une seule chaîne

Résultat :

+365 days 00 hours 00 minutes

Les deux dates sont à minuit, donc les heures et les minutes sont à zéro. Notez qu'elles s'affichent quand même comme 00 car %h et %i complètent déjà les résultats à un seul chiffre qui sont zéro — mais pour les valeurs 1 à 9, les codes en minuscules ne sont pas complétés ; utilisez %H / %I si vous souhaitez toujours deux chiffres.

Dans quel cas utiliser cela ?

• Étiquettes « Membre depuis » / « Il y a X jours » — calculez la différence avec diff(), puis formatez %a days.
• Comptes à rebours — affichez %d days %h hours %i minutes avant une échéance.
• Rapports de durée — restituez un DateInterval stocké (par exemple la durée d'une tâche) pour une interface ou une facture.

Pour formater une date ou une heure réelle plutôt qu'un intervalle, utilisez DateTime::format() ou la fonction procédurale date() — elles partagent un ensemble de balises complètement différent de celui de DateInterval::format().

Conclusion

DateInterval::format() restitue l'écart entre deux dates à l'aide de codes préfixés par %. Retenez les deux règles essentielles : %a est le nombre de jours total tandis que %d représente les jours restants, et les codes en majuscules complètent avec des zéros contrairement aux minuscules. Pour en savoir plus sur la création de l'intervalle, consultez DateTime::diff().

Pratique