date_interval_format()

Introdução

DateInterval::format() transforma um intervalo de data — a diferença entre dois momentos no tempo — em uma string legível por humanos. Você decide exatamente o que exibir (dias, horas, o sinal, etc.) passando uma string de formato construída com marcadores %.

Esta página abrange a sintaxe, todos os códigos de formato, a diferença importante entre %a e %d, como o preenchimento e o sinal funcionam, e vários exemplos executáveis.

O que é um DateInterval?

Um DateInterval representa um período de tempo (por exemplo, "1 ano, 3 meses, 12 dias"), não uma data específica. Quase sempre você o obtém de DateTime::diff(), que subtrai uma data de outra:

<?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() é o método que renderiza esse objeto como uma string. (Você também pode criar intervalos diretamente com o construtor DateInterval ou aplicá-los a datas com DateTime::add() e DateTime::sub().)

Sintaxe

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

• $format — uma string contendo texto literal mais códigos de formato %.
• Retorna o intervalo formatado como uma string.

Qualquer caractere que não faça parte de um código % é impresso literalmente, portanto %d days produz algo como 12 days. Para imprimir um sinal de porcentagem literal, use %%.

%a vs %d — o problema mais comum

Esses dois parecem similares, mas têm significados diferentes:

• %a é o número total de dias em todo o intervalo.
• %d são os dias restantes após descontar anos e meses inteiros.

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

Use %a quando quiser um único número de "quantos dias de diferença", e %d quando estiver exibindo anos/meses/dias juntos.

Códigos de formato

Os códigos em minúsculas fornecem o valor bruto; os códigos em maiúsculas são preenchidos com zero para pelo menos dois dígitos. Não há código embutido para total de horas, minutos ou segundos — apenas %a agrega.

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

Exemplo 1: Total de dias entre duas datas

Exibir uma contagem de dias com sinal

Saída:

+365 days

%R imprime o sinal do intervalo e %a imprime o número total de dias. Como $datetime2 é posterior a $datetime1, o sinal é +. Troque as duas datas (ou use diff() na direção contrária) e %R se torna -.

Exemplo 2: Dias, horas e minutos

Combinar várias unidades em uma string

Saída:

+365 days 00 hours 00 minutes

Os horários são ambos meia-noite, portanto as horas e os minutos são zero. Observe que eles ainda são impressos como 00 porque %h e %i já preenchem resultados de um dígito que são zero — mas para valores de 1 a 9 os códigos em minúsculas não são preenchidos; use %H / %I se quiser sempre dois dígitos.

Quando devo usar isso?

• Rótulos "Membro desde" / "X dias atrás" — calcule a diferença com diff(), depois formate %a days.
• Contagens regressivas — exiba %d days %h hours %i minutes até um prazo.
• Relatórios de duração — renderize um DateInterval armazenado (por exemplo, a duração de uma tarefa) para uma interface ou fatura.

Para formatar uma data ou hora real em vez de um intervalo, use DateTime::format() ou a função procedural date() — elas compartilham um conjunto de marcadores completamente diferente do DateInterval::format().

Conclusão

DateInterval::format() renderiza a diferença entre duas datas usando códigos prefixados com %. Lembre-se das duas regras principais: %a é a contagem total de dias enquanto %d são os dias restantes, e os códigos em maiúsculas preenchem com zero enquanto os em minúsculas não. Para mais informações sobre como obter o intervalo em primeiro lugar, consulte DateTime::diff().

Prática