PHP date_diff() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Date/Time

Definition

In PHP, date_diff() calculates the difference between two dates and returns it as a DateInterval object. The interval shows years, months, days, hours, minutes and seconds.

date_diff() is the procedural alias of DateTime::diff() (and DateTimeImmutable::diff()). It works with both DateTime and DateTimeImmutable. The returned DateInterval also has a days property with the total number of days, and an invert property that is 1 when the target date comes before the base date.

Syntax

Call date_diff() with the values you need. Start with this line.

PHP
$diff = date_diff($start, $end);
CallWhat it does
date_diff($a, $b)Returns a DateInterval from $a to $b.
date_diff($a, $b, true)Returns the same difference but always positive.
$a->diff($b)->daysThe object style (DateTime::diff) that does the same as date_diff(), here reading the total days.

date_diff() is an alias of DateTime::diff(). The y, m and d properties show a calendar style difference, such as 2 months and 5 days, while the days property shows the total number of days as one number. Do not add them together.

Library declarations
PHP
date_diff(DateTimeInterface $baseObject, DateTimeInterface $targetObject, bool $absolute = false): DateInterval

Parameters

ParameterDescription
baseObjectRequired. The starting date, as a DateTime or DateTimeImmutable object.
targetObjectRequired. The date to compare against, as a DateTime or DateTimeImmutable object.
absoluteOptional. If true, the interval is always positive and invert is 0. The default is false.

Return Value

Return ValueDescription
DateIntervalAn object with the properties y, m, d, h, i, s, f, invert and days. The invert property is 1 when the target is earlier than the base date, unless absolute is true.

PHP Examples

Example 1 — Difference Between Two Dates

Compare two fixed dates and read the months, days and total days from the returned DateInterval.

PHP
<?php
$a = date_create('2024-01-15');
$b = date_create('2024-03-20');

$diff = date_diff($a, $b);
echo "Months: ", $diff->m, PHP_EOL;
echo "Days: ", $diff->d, PHP_EOL;
echo "Total days: ", $diff->days, PHP_EOL;
echo $diff->format('%m months, %d days'), PHP_EOL;

How It Works

  1. date_diff() compares January 15 with March 20 and returns a DateInterval.
  2. The m and d properties give the calendar breakdown of 2 months and 5 days.
  3. The days property counts every day between the dates, which is 65 because 2024 is a leap year.
  4. format() writes the interval using placeholders such as %m and %d.

Example 2 — Negative Differences and the absolute Flag

If the target date is earlier than the base date, the invert property is 1. Pass true as the third argument to always get a positive interval.

PHP
<?php
$later = date_create('2024-03-20');
$earlier = date_create('2024-01-15');

$diff = date_diff($later, $earlier);
echo "Invert: ", $diff->invert, PHP_EOL;
echo "Days: ", $diff->days, PHP_EOL;

$abs = date_diff($later, $earlier, true);
echo "Absolute invert: ", $abs->invert, PHP_EOL;
echo "Signed: ", $diff->format('%R%a days'), PHP_EOL;

How It Works

  1. The base date is later than the target date, so the interval points backward.
  2. invert is 1, but the days value is still the positive number 65.
  3. With absolute set to true, PHP ignores the direction and invert becomes 0.
  4. The format letter %R prints a minus sign for inverted intervals, and %a prints total days.

Example 3 — Age and Time Differences

Use two DateTimeImmutable objects with a fixed 'today' to calculate an age. Times work too, down to the second.

PHP
<?php
$birth = new DateTimeImmutable('1990-06-15');
$today = new DateTimeImmutable('2024-01-15');

$age = date_diff($birth, $today);
echo "Age: ", $age->y, " years, ", $age->m, " months, ", $age->d, " days", PHP_EOL;

$start = date_create('2024-01-15 10:30:00');
$end = date_create('2024-01-15 16:45:30');
echo "Elapsed: ", date_diff($start, $end)->format('%H:%I:%S'), PHP_EOL;

How It Works

  1. date_diff() accepts DateTimeImmutable objects as well as DateTime objects.
  2. From June 15, 1990 to January 15, 2024 the difference is 33 years and 7 months.
  3. A fixed 'today' value keeps the example output the same every time.
  4. For times on the same day, %H:%I:%S prints the hours, minutes and seconds with leading zeros.

Frequently Asked Questions

It compares two dates and returns a DateInterval object that describes the difference in years, months, days, hours, minutes and seconds.
Yes. date_diff() is the procedural alias of DateTime::diff(). Both return a DateInterval, and the method also exists on DateTimeImmutable.
Read the days property of the returned DateInterval, for example date_diff($a, $b)->days. The d property only shows the leftover days after full months.
invert is 1 when the target date is earlier than the base date, and 0 otherwise. Pass true as the third argument to always get a positive difference.
Use date_diff() with the birth date and today's date, then read the y property of the result. Use a fixed date instead of today in tests so the result is predictable.

Next: date_format()

date_format() turns a DateTime or DateTimeImmutable object into a formatted string, such a.

date_format() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful