PHP date_interval_format() Function

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

Definition

In PHP, date_interval_format() turns a DateInterval object into a readable string using format codes such as %d for days and %h for hours.

It is the procedural name for DateInterval::format(). It is often used with date_diff() to show how much time is between two dates.

Syntax

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

PHP
$text = date_interval_format($interval, "%m months, %d days");
CallWhat it does
date_interval_format($interval, "%m months, %d days")Returns text like 2 months, 14 days.
date_interval_format($interval, "%a")Returns the total number of days (only for intervals from date_diff()).
date_interval_format($interval, "%H:%I:%S")Returns the time part with leading zeros, such as 02:05:09.

Lowercase codes (%d, %h, %i, %s) print plain numbers, while uppercase codes (%D, %H, %I, %S) add a leading zero. Use %% to print a percent sign. %a only works when the interval came from date_diff(); otherwise it prints (unknown).

Library declarations
PHP
date_interval_format(DateInterval $object, string $format): string

Parameters

ParameterDescription
objectRequired. The DateInterval object to format.
formatRequired. A string with format codes like %y, %m, %d, %h, %i, %s, %a, and %R.

Return Value

Return ValueDescription
stringThe formatted interval text.

PHP Examples

Example 1 — Format the Difference Between Two Dates

Use date_diff() to build an interval, then format it in different ways.

PHP
<?php
$start = date_create("2024-01-01");
$end = date_create("2024-03-15");
$interval = date_diff($start, $end);

echo date_interval_format($interval, "%m months, %d days"), PHP_EOL;
echo date_interval_format($interval, "Total days: %a"), PHP_EOL;
echo date_interval_format($interval, "%R%a days"), PHP_EOL;

How It Works

  1. date_diff() compares January 1 and March 15 of 2024 and returns a DateInterval.
  2. %m and %d give the month part and the day part: 2 months and 14 days.
  3. %a gives the total number of days, which is 74 because 2024 is a leap year.
  4. %R prints the sign, so a forward difference shows a plus sign.

Example 2 — Negative Intervals and Unknown Days

The sign changes when you reverse the dates, and %a is unknown for intervals you create by hand.

PHP
<?php
$a = date_create("2024-01-01");
$b = date_create("2024-01-11");

$forward = date_diff($a, $b);
$backward = date_diff($b, $a);
echo date_interval_format($forward, "%R%a days"), PHP_EOL;
echo date_interval_format($backward, "%R%a days"), PHP_EOL;

$manual = new DateInterval("P5D");
echo date_interval_format($manual, "%a"), PHP_EOL;

How It Works

  1. date_diff($a, $b) goes forward in time, so %R prints +.
  2. date_diff($b, $a) goes backward, so %R prints -.
  3. new DateInterval("P5D") was not made by date_diff(), so PHP does not know the total days.
  4. In that case %a prints the text (unknown).

Example 3 — Show Elapsed Time

Format hours, minutes, and seconds with and without leading zeros.

PHP
<?php
$start = date_create("2024-01-01 08:00:00");
$end = date_create("2024-01-01 10:05:09");
$interval = date_diff($start, $end);

echo date_interval_format($interval, "%H:%I:%S"), PHP_EOL;
echo date_interval_format($interval, "%h hours and %i minutes"), PHP_EOL;

How It Works

  1. The two times are on the same day, so the interval is 2 hours, 5 minutes, and 9 seconds.
  2. Uppercase %H, %I, and %S always use two digits, so you get 02:05:09.
  3. Lowercase %h and %i print the plain numbers 2 and 5.
  4. Choose uppercase for clocks and lowercase for sentences.

Frequently Asked Questions

It converts a DateInterval into a string using format codes. For example, "%d days" becomes "14 days" when the interval has 14 days.
%a is the total number of days between two dates. It only works for intervals returned by date_diff(). For other intervals it prints (unknown).
%d prints the number as is, like 5. %D pads it with a leading zero to at least two digits, like 05. The same pattern applies to %H, %I, %S, and %M.
In interval formats, %m is months and %i is minutes. This is different from date(), where i is minutes and n or m are months, so double-check your codes.
Yes. The procedural function is an alias of the format() method on DateInterval, and both return the same text.

Next: date_isodate_set()

date_isodate_set() changes a DateTime object to a date given as an ISO 8601 year, week num.

date_isodate_set() 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