date_interval_format()

Introducción

DateInterval::format() convierte un intervalo de fecha — la brecha entre dos momentos en el tiempo — en una cadena legible por humanos. Decides exactamente qué mostrar (días, horas, el signo, etc.) pasando una cadena de formato construida con marcadores de posición %.

Esta página cubre la sintaxis, cada código de formato, la diferencia clave entre %a y %d, cómo funcionan el relleno y el signo, y varios ejemplos ejecutables.

¿Qué es un DateInterval?

Un DateInterval representa un lapso de tiempo (por ejemplo, "1 año, 3 meses, 12 días"), no una fecha específica. Casi siempre se obtiene a partir de DateTime::diff(), que resta una fecha de otra:

<?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() es el método que convierte ese objeto en una cadena. (También puedes construir intervalos directamente con el constructor de DateInterval o aplicarlos a fechas con DateTime::add() y DateTime::sub().)

Sintaxis

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

• $format — una cadena que contiene texto literal más códigos de formato %.
• Devuelve el intervalo formateado como una cadena.

Cualquier carácter que no forme parte de un código % se imprime literalmente, por lo que %d days produce algo como 12 days. Para imprimir un signo de porcentaje literal, usa %%.

%a vs %d — el error más común

Estos dos parecen similares pero significan cosas diferentes:

• %a es el número total de días en todo el intervalo.
• %d son los días restantes después de descontar años y meses completos.

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

Usa %a cuando quieras un único número de "cuántos días de diferencia hay", y %d cuando muestres años/meses/días juntos.

Códigos de formato

Los códigos en minúscula dan el valor sin procesar; los códigos en mayúscula se rellenan con ceros hasta al menos dos dígitos. No existe un código incorporado para el total de horas, minutos o segundos — solo %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

Ejemplo 1: Total de días entre dos fechas

Mostrar un conteo de días con signo

Salida:

+365 days

%R imprime el signo del intervalo y %a imprime el número total de días. Como $datetime2 está después de $datetime1, el signo es +. Intercambia las dos fechas (o usa diff() en sentido contrario) y %R se convierte en -.

Ejemplo 2: Días, horas y minutos

Combinar varias unidades en una sola cadena

Salida:

+365 days 00 hours 00 minutes

Ambas horas son medianoche, por lo que las horas y los minutos son cero. Ten en cuenta que aun así se imprimen como 00 porque %h e %i ya rellenan con ceros los resultados de un solo dígito que son cero — pero para valores del 1 al 9 los códigos en minúscula no se rellenan; usa %H / %I si siempre quieres dos dígitos.

¿Cuándo usaría esto?

• Etiquetas "Miembro desde" / "Hace X días" — calcula la diferencia con diff(), luego formatea %a days.
• Cuentas regresivas — muestra %d days %h hours %i minutes hasta una fecha límite.
• Informes de duración — muestra un DateInterval almacenado (por ejemplo, la duración de una tarea) en una interfaz de usuario o factura.

Para formatear una fecha u hora real en lugar de un intervalo, usa DateTime::format() o la función procedimental date() — comparten un conjunto de marcadores de posición completamente diferente al de DateInterval::format().

Conclusión

DateInterval::format() muestra la brecha entre dos fechas usando códigos con prefijo %. Recuerda las dos reglas clave: %a es el conteo total de días mientras que %d son los días restantes, y los códigos en mayúscula rellenan con ceros mientras que los de minúscula no. Para más información sobre cómo obtener el intervalo, consulta DateTime::diff().

Práctica