date_diff()

La funzione date_diff() restituisce la differenza tra due oggetti DateTime sotto forma di oggetto DateInterval. È l'alias procedurale del metodo DateTime::diff() ed è il modo standard per rispondere a domande come "quanti giorni mancano alla scadenza?" o "quanti anni ha questo utente?" in PHP. Questa guida ne illustra la sintassi, il DateInterval restituito, i segnaposto di format() da usare per visualizzare il risultato e le insidie più comuni.

Sintassi

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

• $baseObject — la data di partenza (la data da cui si misura).
• $targetObject — la data di arrivo (la data fino a cui si misura).
• $absolute — quando è true, l'intervallo è sempre positivo e $interval->invert è 0. Il valore predefinito è false, che conserva il segno (negativo quando $targetObject è precedente a $baseObject).

Restituisce un oggetto DateInterval, oppure false in caso di errore.

Calcolare la differenza tra due date

date_diff() accetta due oggetti DateTime e restituisce un DateInterval che descrive il gap tra di essi.

Calcolo delle differenze di date in PHP

Questo stampa +31 days. Creiamo due oggetti DateTime per il 1° gennaio e il 1° febbraio 2022, li passiamo a date_diff(), quindi formattiamo il DateInterval risultante. Il segnaposto %R stampa il segno (+ o -) e %a stampa il numero totale di giorni tra le date.

date_diff($a, $b) è esattamente equivalente a $a->diff($b) — usa quello che si legge meglio nel tuo codice:

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

Leggere l'oggetto DateInterval

Il DateInterval restituito suddivide la differenza in singoli componenti del calendario, ciascuno disponibile come proprietà pubblica:

<?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)";

Questo stampa 2 years, 4 months, 5 days (857 total days). Nota la differenza tra $diff->d (il componente giorno, 5) e $diff->days (il conteggio totale dei giorni, 857) — confonderli è il bug più comune con DateInterval.

Formattare il risultato

DateInterval::format() trasforma l'intervallo in una stringa usando segnaposto preceduti da %. I più utili sono:

<?php

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

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

Questo stampa 1 years, 3 months and 9 days.

Segno e differenze assolute

Per impostazione predefinita l'intervallo mantiene il suo segno, quindi l'ordine degli argomenti è importante. Passa true come terzo argomento per ottenere sempre un risultato assoluto (sempre positivo):

<?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 esempio pratico: calcolare l'età

Un caso d'uso frequente nella realtà è calcolare l'età di una persona in anni interi a partire dalla sua data di nascita:

<?php

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

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

echo "Age: {$age} years";

Questo stampa Age: 31 years. Poiché date_diff() comprende il calendario, gli anni bisestili e la lunghezza variabile dei mesi vengono gestiti automaticamente — non è necessario dividere i secondi per 86400 manualmente.

Conclusione

date_diff() (e la sua forma identica come metodo DateTime::diff()) è il modo affidabile e consapevole del calendario per misurare il gap tra due date in PHP. Leggi i componenti suddivisi (y, m, d) per un output leggibile, usa days per il conteggio totale dei giorni e ricorda che l'ordine degli argomenti controlla il segno a meno che non si passi $absolute = true. Per costruire le date da confrontare, consulta date_create() e date_format(); per aggiungere o sottrarre intervalli, consulta date_add(), date_sub() e date_modify(). Per ulteriori dettagli sui segnaposto mostrati sopra, consulta 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];

Speriamo che questa guida ti sia stata utile nel tuo percorso di sviluppo PHP. Se hai domande o commenti, sentiti libero di lasciarli qui sotto.

Pratica