date_interval_format()

Введение

DateInterval::format() превращает интервал между двумя моментами времени в читаемую строку. Вы сами определяете, что отображать (дни, часы, знак и т. д.), передавая строку формата с плейсхолдерами %.

На этой странице рассматривается синтаксис, все коды формата, принципиальное различие между %a и %d, дополнение нулями и знак, а также несколько запускаемых примеров.

Что такое DateInterval?

DateInterval представляет промежуток времени (например, «1 год, 3 месяца, 12 дней»), а не конкретную дату. Чаще всего его получают из DateTime::diff(), которая вычитает одну дату из другой:

<?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() — это метод, который рендерит объект в виде строки. (Также можно создать интервалы напрямую через конструктор DateInterval или применять их к датам с помощью DateTime::add() и DateTime::sub().)

Синтаксис

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

• $format — строка, содержащая произвольный текст и коды формата %.
• Возвращает отформатированный интервал в виде строки.

Любой символ, не являющийся частью кода %, выводится буквально, поэтому %d days даёт что-то вроде 12 days. Чтобы вывести буквальный знак процента, используйте %%.

%a vs %d — самая частая ошибка

Они выглядят похоже, но означают разное:

• %a — это суммарное количество дней за весь интервал.
• %d — это дни, оставшиеся после учёта целых лет и месяцев.

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

Используйте %a, когда нужно получить одно число «сколько дней между датами», и %d — когда отображаете годы, месяцы и дни вместе.

Коды формата

Строчные коды возвращают значение без дополнения; прописные дополняются нулями до минимум двух цифр. Встроенного кода для суммарных часов, минут или секунд нет — только %a агрегирует.

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

Пример 1: Суммарное количество дней между двумя датами

Вывод количества дней со знаком

Вывод:

+365 days

%R выводит знак интервала, а %a — суммарное количество дней. Поскольку $datetime2 стоит после $datetime1, знак равен +. Поменяйте даты местами (или вызовите diff() в обратном порядке) — и %R станет -.

Пример 2: Дни, часы и минуты

Несколько единиц в одной строке

Вывод:

+365 days 00 hours 00 minutes

Обе даты приходятся на полночь, поэтому часы и минуты равны нулю. Обратите внимание: они всё равно выводятся как 00, потому что %h и %i уже дополняют нулевые однозначные значения — однако для значений 1–9 строчные коды не дополняются нулём; используйте %H / %I, если всегда нужны две цифры.

Когда это применять?

• Метки «Участник с ... / X дней назад» — вычисляйте разницу через diff(), затем форматируйте %a days.
• Обратный отсчёт — показывайте %d days %h hours %i minutes до дедлайна.
• Отчёты о продолжительности — отображайте сохранённый DateInterval (например, длительность задачи) в UI или счёте.

Чтобы форматировать конкретную дату или время вместо интервала, используйте DateTime::format() или процедурную функцию date() — у них совершенно другой набор плейсхолдеров, отличный от DateInterval::format().

Заключение

DateInterval::format() отображает промежуток между двумя датами с помощью кодов с префиксом %. Запомните два ключевых правила: %a — это суммарное количество дней, а %d — только остаток дней; прописные коды дополняются нулями, строчные — нет. Подробнее о том, как получить интервал, см. в DateTime::diff().

Практика