date_diff()

La función date_diff() devuelve la diferencia entre dos objetos DateTime como un objeto DateInterval. Es el alias procedimental del método DateTime::diff() y es la forma estándar de responder preguntas como "¿cuántos días faltan para la fecha límite?" o "¿qué edad tiene este usuario?" en PHP. Esta guía explica su sintaxis, el DateInterval que devuelve, los marcadores de format() que usarás para mostrar el resultado y los errores comunes que suelen ocurrir.

Sintaxis

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

• $baseObject — la fecha de inicio (la fecha desde la que se mide).
• $targetObject — la fecha de fin (la fecha hasta la que se mide).
• $absolute — cuando es true, el intervalo es siempre positivo e $interval->invert es 0. Por defecto es false, lo que conserva el signo (negativo cuando $targetObject es anterior a $baseObject).

Devuelve un objeto DateInterval, o false en caso de error.

Calcular la diferencia entre dos fechas

date_diff() recibe dos objetos DateTime y devuelve un DateInterval que describe la diferencia entre ellos.

Calcular diferencias de fechas en PHP

Esto imprime +31 days. Creamos dos objetos DateTime para el 1 de enero y el 1 de febrero de 2022, los pasamos a date_diff() y luego formateamos el DateInterval resultante. El marcador %R imprime el signo (+ o -) y %a imprime el número total de días entre las fechas.

date_diff($a, $b) es exactamente equivalente a $a->diff($b) — usa el que resulte más legible en tu código:

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

Leer el objeto DateInterval

El DateInterval devuelto desglosa la diferencia en componentes de calendario separados, cada uno disponible como una propiedad 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)";

Esto imprime 2 years, 4 months, 5 days (857 total days). Observa la diferencia entre $diff->d (el componente de días, 5) y $diff->days (el recuento total de días, 857) — confundirlos es el error más común con DateInterval.

Formatear el resultado

DateInterval::format() convierte el intervalo en una string usando marcadores con prefijo %. Los más útiles:

<?php

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

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

Esto imprime 1 years, 3 months and 9 days.

Signo y diferencias absolutas

Por defecto el intervalo conserva su signo, por lo que el orden de los argumentos importa. Pasa true como tercer argumento para forzar un resultado absoluto (siempre 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 ejemplo práctico: calcular la edad

Un uso frecuente en el mundo real es calcular la edad de una persona en años completos a partir de su fecha de nacimiento:

<?php

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

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

echo "Age: {$age} years";

Esto imprime Age: 31 years. Dado que date_diff() entiende el calendario, los años bisiestos y los distintos largos de mes se manejan automáticamente — no necesitas dividir segundos entre 86400 por tu cuenta.

Conclusión

date_diff() (y su forma de método idéntica DateTime::diff()) es la manera fiable y consciente del calendario para medir la diferencia entre dos fechas en PHP. Lee los componentes desglosados (y, m, d) para una salida legible por humanos, usa days para un recuento total de días y recuerda que el orden de los argumentos controla el signo a menos que pases $absolute = true. Para construir las fechas que comparas, consulta date_create() y date_format(); para sumar o restar intervalos, consulta date_add(), date_sub() y date_modify(). Para más información sobre los marcadores mostrados anteriormente, 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];

Esperamos que esta guía te haya resultado útil en tu desarrollo con PHP. Si tienes preguntas o comentarios, no dudes en dejarlos a continuación.

Práctica