date_diff()

The date_diff() function returns the difference between two DateTime objects as a DateInterval object. It is the procedural alias of the DateTime::diff() method, and it's the standard way to answer questions like "how many days until the deadline?" or "how old is this user?" in PHP. This guide explains its syntax, the DateInterval it returns, the format() placeholders you'll use to display the result, and the gotchas that trip people up.

Syntax

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

• $baseObject — the starting date (the date you measure from).
• $targetObject — the ending date (the date you measure to).
• $absolute — when true, the interval is always positive and $interval->invert is 0. Defaults to false, which preserves the sign (negative when $targetObject is earlier than $baseObject).

It returns a DateInterval object, or false on failure.

Calculating the difference between two dates

date_diff() takes two DateTime objects and returns a DateInterval describing the gap between them.

Calculating Date Differences in PHP

This prints +31 days. We create two DateTime objects for January 1st and February 1st 2022, pass them to date_diff(), then format the resulting DateInterval. The %R placeholder prints the sign (+ or -) and %a prints the total number of days between the dates.

date_diff($a, $b) is exactly equivalent to $a->diff($b) — use whichever reads better in your code:

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

Reading the DateInterval object

The returned DateInterval breaks the difference into separate calendar components, each available as a public property:

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

This prints 2 years, 4 months, 5 days (857 total days). Note the difference between $diff->d (the day component, 5) and $diff->days (the total day count, 857) — mixing them up is the most common DateInterval bug.

Formatting the result

DateInterval::format() turns the interval into a string using %-prefixed placeholders. The most useful ones:

<?php

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

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

This prints 1 years, 3 months and 9 days.

Sign and absolute differences

By default the interval keeps its sign, so the order of the arguments matters. Pass true as the third argument to force an absolute (always-positive) result:

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

A practical example: calculating age

A frequent real-world use is computing a person's age in whole years from their birthday:

<?php

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

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

echo "Age: {$age} years";

This prints Age: 31 years. Because date_diff() understands the calendar, leap years and varying month lengths are handled automatically — you don't need to divide seconds by 86400 yourself.

Conclusion

date_diff() (and its identical method form DateTime::diff()) is the reliable, calendar-aware way to measure the gap between two dates in PHP. Read the broken-down components (y, m, d) for human-friendly output, use days for a total day count, and remember that the argument order controls the sign unless you pass $absolute = true. To build the dates you compare, see date_create() and date_format(); to add or subtract intervals, see date_add(), date_sub(), and date_modify(). For more on the placeholders shown above, see 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];

We hope you found this guide helpful in your PHP development journey. If you have any questions or comments, feel free to leave them below.

Practice