PHP 8.4.3 Released!

DateTimeInterface::format

DateTimeImmutable::format

DateTime::format

date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::format -- DateTimeImmutable::format -- DateTime::format -- date_formatВозвращает дату, которую отформатировал по заданному формату

Описание

Объектно-ориентированный стиль

public DateTimeInterface::format(string $format): string
public DateTimeImmutable::format(string $format): string
public DateTime::format(string $format): string

Процедурный стиль

Метод возвращает строку с датой в формате, который указали при вызове метода.

Список параметров

object

Только для процедурного стиля: объект DateTime, который возвращает функция date_create().

format

Шаблон результирующей строки (string) с датой. Смотрите параметры форматирования ниже. Вместо шаблона также указывают предопределённые константы даты и времени, например, константа DATE_RSS содержит строку формата 'D, d M Y H:i:s'.

Символы, которые метод распознаёт в строке параметра format
Символ в строке format Описание Пример возвращаемого значения
День --- ---
d День месяца, 2 цифры с ведущим нулём От 01 до 31
D Текстовое представление дня недели, 3 символа От Mon до Sun
j День месяца без ведущего нуля От 1 до 31
l (строчная 'L') Полное наименование дня недели От Sunday до Saturday
N Числовое представление дня недели по стандарту ISO 8601 От 1 для понедельника до 7 для воскресенья
S Английское наращение — суффикс для порядкового числительного, которое означает день месяца, 2 буквы Значения st, nd, rd или th. Опция хорошо работает с параметром формата j
w Порядковый номер дня недели От 0 для воскресенья до 6 для субботы
z Порядковый номер дня в году начиная с 0 От 0 до 365
Неделя --- ---
W Порядковый номер недели года по стандарту ISO 8601; недели начинаются с понедельника Например: 42 — 42-я неделя года
Месяц --- ---
F Полное название месяца, например January или March От January до December
m Порядковый номер месяца с ведущим нулём От 01 до 12
M Сокращённое название месяца, 3 символа От Jan до Dec
n Порядковый номер месяца без ведущего нуля От 1 до 12
t Количество дней в заданном месяце От 28 до 31
Год --- ---
L Признак високосного года 1, если год високосный, иначе 0
o Номер года с учётом нумерации недель стандартом ISO 8601. Параметр возвращает то же значение, что и параметр Y, за исключением случаев, когда номер недели по стандарту ISO, как возвращает параметр W, принадлежит предыдущему или следующему году, тогда возвращается год, которому принадлежит такая неделя Примеры: 1999 или 2003
X Расширенное полное числовое представление года, не менее 4 цифр, с знаком - перед значением года, если год относится к периоду до нашей эры, и знаком + перед значением года, если год относится к нашей эре Примеры: -0055, +0787, +1999, +10191
x Расширенное полное числовое представление, если требуется, или стандартное полное числовое представление по аналогии с параметром Y, если возможно. Не менее четырёх цифр. Параметр добавит знак - перед значением года, если год относится к периоду до нашей эры. Перед значениями года после (и включая) 10000 параметр добавит знак + Примеры: -0055, 0787, 1999, +10191
Y Полное числовое представление года, не менее 4 цифр, со знаком - перед значениями лет до нашей эры Примеры: -0055, 0787, 1999, 2003, 10191
y Номер года, 2 цифры Примеры: 99, 03
Время --- ---
a Ante meridiem (лат. «до полудня») или Post meridiem (лат. «после полудня») в нижнем регистре am или pm
A Ante meridiem (лат. «до полудня») или Post meridiem (лат. «после полудня») в верхнем регистре AM или PM
B Время в формате интернет-времени — альтернативной системы отсчета времени суток, которую предложила швейцарская компания — производитель часов Swatch От 000 до 999
g Часы в 12-часовом формате без ведущего нуля От 1 до 12
G Часы в 24-часовом формате без ведущего нуля От 0 до 23
h Часы в 12-часовом формате с ведущим нулём От 01 до 12
H Часы в 24-часовом формате с ведущим нулём От 00 до 23
i Минуты с ведущим нулём От 00 до 59
s Секунды с ведущим нулём От 00 до 59
u Микросекунды. Обратите внимание, что функция date() генерирует для поля микросекунд значение 000000, поскольку принимает метку времени как целочисленное (int) значение в секундах, тогда как метод DateTimeInterface::format() поддерживает микросекунды, если объект DateTimeInterface создали с микросекундами Например: 654321
v Миллисекунды. Примечание к параметру u касается и этого параметра Пример: 654
Часовой пояс --- ---
e Идентификатор часового пояса Примеры: UTC, GMT, Atlantic/Azores
I (заглавная i) Признак летнего времени 1, если дата соответствует летнему времени, иначе 0
O Разница со временем по Гринвичу без двоеточия между часами и минутами Например: +0200
P Разница со временем по Гринвичу с двоеточием между часами и минутами Например: +02:00
p То же, что и параметр P, но вместо +00:00 возвращает Z. Параметр доступен с PHP 8.0.0 Например: Z или +02:00
T Аббревиатура часового пояса, если известна; иначе смещение по Гринвичу Примеры: EST, MDT, +05
Z Смещение часового пояса в секундах. Смещение для часовых поясов к западу от времени UTC — отрицательное, а для часовых поясов к востоку от времени UTC — положительное От -43200 до 50400
Полная дата/время --- ---
c Дата в формате стандарта ISO 8601 2004-02-12T15:19:21+00:00
r Дата в формате стандартов » RFC 222 и » RFC 5322 Например: Thu, 21 Dec 2000 16:01:07 +0200
U Количество секунд, которые прошли с начала Unix-эпохи — с 1 января 1970 00:00:00 GMT Смотрите также time()

Метод выводит нераспознанные в строке формата символы без изменений. Параметр Z возвращает 0 при каждом вызове функции gmdate().

Замечание:

Поскольку эта функция принимает только целочисленные (int) метки времени, форматирующий символ u будет полезен только при работе с функцией date_format() и пользовательскими метками времени, которые создали функцией date_create().

Возвращаемые значения

В случае успешного выполнения метод возвращает строку с отформатированной датой.

Список изменений

Версия Описание
8.2.0 Добавили символы форматирования X и x.
8.0.0 Добавили символ форматирования p.

Примеры

Пример #1 Пример использования метода DateTimeInterface::format()

Объектно-ориентированный стиль

<?php

$date
= new DateTimeImmutable('2000-01-01');
echo
$date->format('Y-m-d H:i:s');

?>

Процедурный стиль

<?php

$date
= date_create('2000-01-01');
echo
date_format($date, 'Y-m-d H:i:s');

?>

Результат выполнения приведённого примера:

2000-01-01 00:00:00

Пример #2 Больше примеров

<?php

// Установка часового пояса по умолчанию
date_default_timezone_set('UTC');

// Время «сейчас»
$date = new DateTimeImmutable();

// Выведет что-то наподобие: Wednesday
echo $date->format('l'), "\n";

// Выведет что-то наподобие: Wednesday 19th of October 2022 08:40:48 AM
echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

/* Передача констант в параметр format */
// Выведет что-то наподобие: Wed, 19 Oct 2022 08:40:48 +0000
echo $date->format(DateTimeInterface::RFC2822), "\n";

?>

Разворачивание символа в строке формата, который распознал метод, останавливают путём экранирования символа форматирования обратным слешем. Иногда требуется заэкранировать сам обратный слеш, если символ с обратным слешем образует управляющую последовательность.

Пример #3 Пример экранирования символов при форматировании

<?php

$date
= new DateTimeImmutable();

// Выведет что-то наподобие: Wednesday the 19th
echo $date->format('l \t\h\e jS');

?>

Чтобы отформатировать даты на других языках, вместо метода DateTimeInterface::format() вызывают метод IntlDateFormatter::format().

Примечания

Метод не учитывает настройки локали и выводит данные на английском языке.

Смотрите также

  • date() - Форматирует метку времени эпохи Unix
Добавить

Примечания пользователей 1 note

up
0
jurchiks101 at gmail dot com
9 days ago
If you want to get the week of year + year of said week, you need to use `format('o-W'), otherwise you can stumble into a non-obvious gotcha (unless you RTFM and memorised it, that is).
Using `Y` instead of `o` can result in incorrect year values in the case of the first or last week of the year (depending on if January 4th falls into said week or not), such as the first week of 2025 between 2024-12-30 and 2025-01-05 - `(new DateTime('2024-12-30'))->format('o-W')` will return the correct value of `2025-01` (as per ISO-8601 definition of week of year), while `format('Y-W')` will return `2024-01`.
Because of this, I would personally recommend avoiding using week of year anywhere unless absolutely necessary, as it is easy to make this mistake and never realise it.
To Top