date_format()

date_format()

Введение

Даты и время встречаются повсюду в реальных приложениях: временны́е метки в блогах, даты заказов в интернет-магазинах, записи в логах, события в календарях. PHP хранит эти моменты внутри в формате, который не читается человеком, поэтому вам нужен способ превратить объект даты в строку — "2023-03-03", "Friday, March 3rd" или "03/03/2023 1:00 PM". Именно это делает date_format().

В этой главе рассматривается, что такое date_format(), её синтаксис, наиболее полезные символы формата, а также подводные камни, связанные с часовыми поясами и неизменяемостью.

Что такое функция date_format()?

Функция date_format() форматирует объект DateTime в строку согласно указанному шаблону. Это процедурный псевдоним объектно-ориентированного метода DateTime::format() — оба варианта дают одинаковый результат, поэтому используйте тот стиль, который подходит для вашего кода:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

// These two lines are equivalent
echo date_format($date, 'Y-m-d');   // procedural
echo $date->format('Y-m-d');        // object-oriented

Синтаксис

date_format(DateTimeInterface $object, string $format): string

• $object — экземпляр DateTime (или DateTimeImmutable). Это дата, которую вы хотите отобразить.
• $format — строка, составленная из символов формата (например, Y, m, d). Любой символ, не являющийся символом формата, выводится буквально.
• Возвращаемое значение — отформатированная дата в виде строки.

Как использовать функцию date_format()

Сначала создайте объект даты с помощью класса DateTime, который встроен в PHP:

<?php

$date = new DateTime('2023-03-03');

Это создаёт дату, установленную на 3 марта 2023 года, в полночь. По умолчанию DateTime использует настроенный на сервере часовой пояс — это означает, что один и тот же код может давать разный результат на разных машинах. Для получения предсказуемых результатов всегда задавайте часовой пояс явно:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

Теперь форматируйте как угодно:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'Y-m-d');
// Output: 2023-03-03

В современных PHP-приложениях предпочтительнее использовать DateTimeImmutable вместо DateTime. Методы вроде modify() изменяют DateTime на месте, что является частым источником ошибок при передаче объекта в разные части кода; DateTimeImmutable возвращает новый объект и работает с date_format() точно так же:

<?php

$date = new DateTimeImmutable('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'd/m/Y');
// Output: 03/03/2023

Распространённые форматы дат

Существует множество способов форматирования дат с помощью функции date_format(). Вот некоторые из наиболее распространённых форматов:

• Y-m-d: Дата в формате YYYY-MM-DD.
• d/m/Y: Дата в формате DD/MM/YYYY.
• m/d/Y: Дата в формате MM/DD/YYYY.
• H:i:s: Время в 24-часовом формате (например, 13:00:00).
• h:i:s a: Время в 12-часовом формате (например, 01:00:00 am).

Символы формата

Помимо перечисленных выше распространённых форматов, вы можете составить собственный шаблон из отдельных символов формата. Вот наиболее часто используемые из них:

• Y: Год в четырёх цифрах (например, 2023).
• y: Год в двух цифрах (например, 23).
• m: Месяц в виде двузначного числа (например, 03).
• M: Сокращённое название месяца (например, Mar).
• F: Полное название месяца (например, March).
• d: День месяца в виде двузначного числа (например, 03).
• D: Сокращённое название дня (например, Fri).
• l: Полное название дня (например, Friday).
• j: День месяца без ведущих нулей (например, 3).
• S: Английский порядковый суффикс для дня месяца (например, st, nd, rd, th).
• H: Час в 24-часовом формате (например, 13).
• h: Час в 12-часовом формате (например, 01).
• i: Минуты в виде двузначного числа (например, 05).
• s: Секунды в виде двузначного числа (например, 30).
• a: am или pm.

Полный список всех поддерживаемых символов см. в главах PHP date and time и date() — date_format() использует те же символы.

Вот пример пользовательского формата даты:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'l, F jS Y, h:i:s a');
// Output: Friday, March 3rd 2023, 12:00:00 am

Чтобы вывести символ формата буквально, не интерпретируя его, экранируйте его обратным слешем:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, '\T\o\d\a\y \i\s l');
// Output: Today is Friday

date_format() vs date()

Обе функции форматируют даты, но принимают разные входные данные:

• date() работает с Unix-временной меткой (целым числом) и по умолчанию использует текущий момент. Используйте её для быстрого форматирования без привязки к часовому поясу: date('Y-m-d').
• date_format() работает с объектом DateTime, который содержит собственный часовой пояс и поддерживает арифметику (добавление дней, вычисление разниц) перед форматированием. Используйте её, когда нужно манипулировать датой.

Если у вас есть строка вроде "3 March 2023", сначала создайте объект DateTime — date_create_from_format() и strtotime() являются обычными точками входа.

Заключение

Функция date_format() в PHP предоставляет простой способ форматировать объект DateTime в читаемую строку. Понимание доступных символов формата и лучших практик — явная установка часового пояса и предпочтение DateTimeImmutable — позволит обеспечить точный и предсказуемый вывод дат в любой среде, где работает ваш код.

Practice