date_diff()

La fonction date_diff() retourne la différence entre deux objets DateTime sous la forme d'un objet DateInterval. C'est l'alias procédural de la méthode DateTime::diff(), et c'est la manière standard de répondre à des questions telles que « combien de jours avant la date limite ? » ou « quel est l'âge de cet utilisateur ? » en PHP. Ce guide explique sa syntaxe, le DateInterval qu'elle retourne, les espaces réservés de format() utilisés pour afficher le résultat, et les pièges courants à éviter.

Syntaxe

date_diff(DateTime $baseObject, DateTime $targetObject, bool $absolute = false): DateInterval

• $baseObject — la date de départ (la date à partir de laquelle vous mesurez).
• $targetObject — la date d'arrivée (la date jusqu'à laquelle vous mesurez).
• $absolute — lorsque true, l'intervalle est toujours positif et $interval->invert vaut 0. La valeur par défaut est false, ce qui préserve le signe (négatif lorsque $targetObject est antérieur à $baseObject).

Elle retourne un objet DateInterval, ou false en cas d'échec.

Calculer la différence entre deux dates

date_diff() prend deux objets DateTime et retourne un DateInterval décrivant l'écart entre eux.

Calculer des différences de dates en PHP

Ceci affiche +31 days. Nous créons deux objets DateTime pour le 1er janvier et le 1er février 2022, nous les passons à date_diff(), puis nous formatons le DateInterval résultant. L'espace réservé %R affiche le signe (+ ou -) et %a affiche le nombre total de jours entre les dates.

date_diff($a, $b) est exactement équivalent à $a->diff($b) — utilisez celui qui se lit le mieux dans votre code :

$interval = $first_date->diff($second_date);

Lire l'objet DateInterval

Le DateInterval retourné décompose la différence en composantes calendaires distinctes, chacune accessible en tant que propriété publique :

<?php

$start = new DateTime('2020-03-15');
$end   = new DateTime('2022-07-20');

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

echo "{$diff->y} years, {$diff->m} months, {$diff->d} days";
echo " ({$diff->days} total days)";

Ceci affiche 2 years, 4 months, 5 days (857 total days). Notez la différence entre $diff->d (la composante jour, 5) et $diff->days (le total des jours, 857) — les confondre est le bug le plus courant avec DateInterval.

Formater le résultat

DateInterval::format() convertit l'intervalle en chaîne de caractères à l'aide d'espaces réservés préfixés par %. Les plus utiles :

<?php

$diff = (new DateTime('2022-01-01'))->diff(new DateTime('2023-04-10'));

echo $diff->format('%y years, %m months and %d days');

Ceci affiche 1 years, 3 months and 9 days.

Signe et différences absolues

Par défaut, l'intervalle conserve son signe, donc l'ordre des arguments est important. Passez true comme troisième argument pour forcer un résultat absolu (toujours positif) :

<?php

$later   = new DateTime('2022-02-01');
$earlier = new DateTime('2022-01-01');

// Target is earlier than base → negative interval
echo $later->diff($earlier)->format('%R%a days'), "\n"; // -31 days

// Force an absolute difference
echo date_diff($later, $earlier, true)->format('%R%a days'); // +31 days

Un exemple pratique : calculer un âge

Un usage fréquent dans le monde réel consiste à calculer l'âge d'une personne en années complètes à partir de sa date de naissance :

<?php

$birthday = new DateTime('1995-06-21');
$today    = new DateTime('2026-06-21');

$age = $birthday->diff($today)->y;

echo "Age: {$age} years";

Ceci affiche Age: 31 years. Parce que date_diff() comprend le calendrier, les années bissextiles et les durées variables des mois sont gérées automatiquement — vous n'avez pas besoin de diviser des secondes par 86400 vous-même.

Conclusion

date_diff() (et sa forme méthode identique DateTime::diff()) est la manière fiable et consciente du calendrier de mesurer l'écart entre deux dates en PHP. Lisez les composantes décomposées (y, m, d) pour un affichage convivial, utilisez days pour un comptage total de jours, et souvenez-vous que l'ordre des arguments contrôle le signe sauf si vous passez $absolute = true. Pour construire les dates à comparer, consultez date_create() et date_format() ; pour ajouter ou soustraire des intervalles, consultez date_add(), date_sub() et date_modify(). Pour plus d'informations sur les espaces réservés présentés ci-dessus, consultez date_interval_format().

graph TD;
A[date_diff two DateTime objects] --> B[Returns a DateInterval];
B --> C[Read components: y, m, d, h, i, s];
B --> D[Read total days: days];
B --> E[Format with %y %m %d %a %R];

Nous espérons que ce guide vous a été utile dans votre parcours de développement PHP. Si vous avez des questions ou des commentaires, n'hésitez pas à les laisser ci-dessous.

Pratique