date_diff()

A função date_diff() retorna a diferença entre dois objetos DateTime como um objeto DateInterval. É o alias procedural do método DateTime::diff() e é a forma padrão de responder perguntas como "quantos dias faltam para o prazo?" ou "qual é a idade deste usuário?" em PHP. Este guia explica sua sintaxe, o DateInterval que ela retorna, os marcadores de format() que você usará para exibir o resultado e as armadilhas mais comuns.

Sintaxe

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

• $baseObject — a data inicial (a data a partir da qual você mede de).
• $targetObject — a data final (a data até a qual você mede até).
• $absolute — quando true, o intervalo é sempre positivo e $interval->invert é 0. O padrão é false, o que preserva o sinal (negativo quando $targetObject é anterior a $baseObject).

Retorna um objeto DateInterval ou false em caso de falha.

Calculando a diferença entre duas datas

date_diff() recebe dois objetos DateTime e retorna um DateInterval descrevendo o intervalo entre eles.

Calculando Diferenças de Datas em PHP

Isso imprime +31 days. Criamos dois objetos DateTime para 1º de janeiro e 1º de fevereiro de 2022, passamos para date_diff() e formatamos o DateInterval resultante. O marcador %R imprime o sinal (+ ou -) e %a imprime o número total de dias entre as datas.

date_diff($a, $b) é exatamente equivalente a $a->diff($b) — use o que for mais legível no seu código:

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

Lendo o objeto DateInterval

O DateInterval retornado divide a diferença em componentes de calendário separados, cada um disponível como propriedade pública:

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

Isso imprime 2 years, 4 months, 5 days (857 total days). Note a diferença entre $diff->d (o componente de dias, 5) e $diff->days (a contagem total de dias, 857) — confundi-los é o bug mais comum com DateInterval.

Formatando o resultado

DateInterval::format() converte o intervalo em uma string usando marcadores prefixados com %. Os mais úteis:

<?php

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

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

Isso imprime 1 years, 3 months and 9 days.

Sinal e diferenças absolutas

Por padrão, o intervalo mantém seu sinal, portanto a ordem dos argumentos importa. Passe true como terceiro argumento para forçar um resultado absoluto (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

Um exemplo prático: calculando a idade

Um uso prático muito frequente é calcular a idade de uma pessoa em anos completos a partir da sua data de nascimento:

<?php

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

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

echo "Age: {$age} years";

Isso imprime Age: 31 years. Como date_diff() compreende o calendário, anos bissextos e meses com comprimentos variados são tratados automaticamente — você não precisa dividir segundos por 86400 manualmente.

Conclusão

date_diff() (e sua forma idêntica como método DateTime::diff()) é a maneira confiável e consciente do calendário para medir o intervalo entre duas datas em PHP. Leia os componentes separados (y, m, d) para saída legível por humanos, use days para contagem total de dias e lembre-se de que a ordem dos argumentos controla o sinal, a menos que você passe $absolute = true. Para criar as datas que você compara, veja date_create() e date_format(); para adicionar ou subtrair intervalos, veja date_add(), date_sub() e date_modify(). Para mais detalhes sobre os marcadores mostrados acima, veja 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];

Esperamos que este guia tenha sido útil na sua jornada de desenvolvimento PHP. Se tiver alguma dúvida ou comentário, fique à vontade para deixá-los abaixo.

Prática