Дата и время в PHP: работа с DateTime и часовыми поясами

Для даты и времени в PHP используйте DateTime и DateTimeImmutable. Они помогают создать момент из строки, вывести его через format(), изменить дату, посчитать разницу и показать результат в часовом поясе пользователя. В статье собраны рабочие примеры для PHP 8.3: разбор собственных форматов, DatePeriod, хранение в UTC и русские названия месяцев.

Класс DateTime хранит дату, время и часовой пояс одного момента. Выберите DateTimeImmutable, если объект проходит через несколько функций: методы вернут новые объекты и не изменят исходное значение.

Создание объекта

Конструктор DateTime принимает строку с датой или относительным выражением. Второй аргумент задает объект DateTimeZone, если момент нужно создать в определенной зоне.

$now = new DateTime();
$day = new DateTime('2013-03-24');
$future = new DateTime('+2 days');
$tomorrow = new DateTime('tomorrow');

Пустой конструктор берет текущие дату и время.

Строки 2013-03-24, tomorrow и +2 days PHP разбирает по правилам форматов даты и относительных выражений. Полный список распознаваемых строк приведен в документации PHP по форматам даты и времени.

Передавайте в конструктор данные из доверенного источника: произвольная строка может описать другой момент.

При нераспознанной строке конструктор выбрасывает исключение. В PHP 8.3 такую ошибку описывает DateMalformedStringException.

try {
    $date = new DateTime('not-a-date');
} catch (DateMalformedStringException $error) {
    echo $error->getMessage();
}

Собственный шаблон задайте статическим методом createFromFormat(). Сначала укажите формат, затем строку с датой.

$date = DateTime::createFromFormat('j-M-Y', '24-Mar-2013');

if ($date === false) {
    var_dump(DateTime::getLastErrors());
}

Метод createFromFormat() возвращает false при ошибке. Метод getLastErrors() показывает предупреждения и ошибки разбора; при отсутствии ошибок PHP может вернуть false.

Вывод в нужном формате

Метод format() превращает объект даты в строку. Передайте ему строку кодов и получите нужный порядок года, месяца, времени или часового пояса.

КодЧто выводитПример
YГод из четырех цифр2024
yГод из двух цифр24
mМесяц с ведущим нулем03
nМесяц без ведущего нуля3
dДень с ведущим нулем09
jДень без ведущего нуля9
HЧасы от 00 до 2308
iМинуты05
sСекунды07
DКороткое английское имя дняMon
lПолное английское имя дняMonday
NНомер дня недели от 1 до 71
UUnix-метка в секундах1710000000
eИдентификатор часового поясаEurope/Moscow
PСмещение UTC с двоеточием+03:00
cДата в ISO 86012024-03-09T08:05:07+03:00
$date = new DateTime('2024-03-09 08:05:07', new DateTimeZone('Europe/Moscow'));

echo $date->format('d.m.Y');
echo $date->format('Y-m-d H:i:s');
echo $date->format(DATE_ATOM);

Формат d.m.Y подходит для привычной записи даты. Формат Y-m-d H:i:s удобен для SQL-значения. Константа DATE_ATOM выводит дату в ISO 8601 с часовым смещением.

Коды D и l дают английские названия дней. Метод format() не переводит месяцы и дни на русский язык.

$formatter = new IntlDateFormatter(
    'ru_RU',
    IntlDateFormatter::LONG,
    IntlDateFormatter::NONE,
    'Europe/Moscow'
);

$date = new DateTime('2024-03-09', new DateTimeZone('Europe/Moscow'));
echo $formatter->format($date);
// 9 марта 2024 г.

IntlDateFormatter входит в расширение intl.

Подключите это расширение, если приложению нужны локализованные названия месяцев и дней.

Изменение даты

Методы DateTime меняют исходный объект. Выберите операцию по части даты или по нужному относительному сдвигу.

МетодЧто делаетПример
setDate()Задает год, месяц и день$date->setDate(2024, 12, 30);
setTime()Задает часы, минуты и секунды$date->setTime(12, 3, 20);
modify()Сдвигает момент относительной строкой$date->modify('+1 week');
setTimestamp()Задает момент по Unix-метке$date->setTimestamp(1364798550);
add()Добавляет DateInterval$date->add(new DateInterval('P1M'));
sub()Вычитает DateInterval$date->sub(new DateInterval('P2D'));
$date = new DateTime('2024-01-15 10:00:00');
$date->setDate(2024, 12, 30);
$date->setTime(12, 3, 20);
$date->modify('+1 week');
$date->add(new DateInterval('P2D'));
$date->sub(new DateInterval('PT3H'));

PHP нормализует значения за пределами обычного диапазона. Например, setDate(2013, 12, 35) дает дату 2014-01-04. Такое поведение удобно для вычислений, но может скрыть ошибку во входных данных.

Сдвиг +1 month от 31 января способен привести к марту. В високосном 2024 году следующий результат – 2024-03-02, потому что февраль не содержит 31 день.

$date = new DateTimeImmutable('2024-01-31');
$next = $date->modify('+1 month');
$lastDay = $date->modify('last day of next month');

echo $next->format('Y-m-d');
// 2024-03-02

echo $lastDay->format('Y-m-d');
// 2024-02-29

Берите выражение last day of next month, когда бизнес-правило требует последний день следующего месяца. Смысл такого сдвига отличается от прибавления календарного месяца.

Метод getTimestamp() возвращает Unix-метку – число секунд с начала Unix-эпохи. Метод setTimestamp() задает объекту момент по такой метке.

Ни один метод не меняет формат вывода.

Сравнение и разница

Объекты DateTime сравниваются операторами PHP. Перед сравнением задайте часовой пояс, иначе одинаковые календарные часы могут обозначать разные моменты.

$sheldon = new DateTime('1980-05-20');
$neo = new DateTime('1962-03-11');

if ($sheldon > $neo) {
    echo 'День рождения Шелдона позже дня рождения Нео';
}

Метод diff() строит объект DateInterval между двумя датами. Его метод format() выводит годы, месяцы, дни и время по заданному шаблону.

$diff = $neo->diff($sheldon);
echo $diff->format('Разница: %Y лет, %m месяцев и %d дней');

В DateInterval доступны свойства y, m, d, h, i и s. Свойство days хранит общее число дней, если интервал создан методом diff(). Свойство invert показывает направление интервала.

$interval = new DateInterval('P2Y');
$anniversary = new DateTime('2024-03-24');
$anniversary->add($interval);
echo $anniversary->format('Y-m-d');
// 2026-03-24

Формат конструктора DateInterval описан на странице DateInterval::__construct(). Строка P2Y означает период в 2 года, а PT3H – интервал в 3 часа.

Часовые пояса

Часовой пояс определяет смещение относительно UTC и правила перехода на летнее время. Используйте идентификаторы базы tz, например Europe/Moscow или America/New_York, вместо ручного смещения.

$timezone = new DateTimeZone('America/New_York');
$date = new DateTime('2024-07-01 12:00:00', $timezone);

echo $date->format('Y-m-d H:i:s');
echo $date->format('e P');

Метод setTimezone() меняет представление того же момента в другой зоне.

Он не прибавляет часы вручную. База tz учитывает переходы между стандартным и летним временем, поэтому значение вроде -05:00 не заменяет идентификатор зоны.

$utc = new DateTime('2024-01-15 12:00:00', new DateTimeZone('UTC'));
$local = clone $utc;
$local->setTimezone(new DateTimeZone('America/New_York'));

echo $local->format('Y-m-d H:i:s e P');

Если зона не передана конструктору, PHP использует настройку date.timezone. Задайте ее явно в php.ini или передайте DateTimeZone каждому объекту, чтобы окружения давали одинаковый результат.

Список идентификаторов доступен в документации PHP по часовым поясам.

Периоды

Класс DatePeriod перебирает даты с заданным шагом.

Для периода нужны начальная дата, DateInterval и дата окончания либо число повторений.

$sheldon = new DateTimeImmutable('1980-05-20');
$interval = new DateInterval('P1Y');
$period = new DatePeriod(
    $sheldon,
    $interval,
    new DateTimeImmutable('2025-01-01')
);

foreach ($period as $date) {
    echo $date->format('Y-m-d - D'), "\n";
}

Цикл печатает даты с шагом в один год.

$period = new DatePeriod(
    $sheldon,
    $interval,
    new DateTimeImmutable(),
    DatePeriod::EXCLUDE_START_DATE
);

Флаг EXCLUDE_START_DATE пропускает начальную дату.

Дни рождения Нео с 1963 года по 1980 год дают 18 элементов до даты рождения Шелдона.

$neo = new DateTimeImmutable('1962-03-11');
$sheldon = new DateTimeImmutable('1980-05-20');
$birthdays = new DatePeriod(
    $neo,
    new DateInterval('P1Y'),
    $sheldon,
    DatePeriod::EXCLUDE_START_DATE
);

echo iterator_count($birthdays);
// 18

DateTimeImmutable

DateTime меняет исходный объект после add(), sub(), modify() и setTimezone(). DateTimeImmutable возвращает новый объект после каждой такой операции, поэтому вычисления сохраняют исходную дату.

$start = new DateTimeImmutable('2024-01-31');
$changed = $start->modify('last day of next month');
$future = $changed->add(new DateInterval('P7D'));

echo $start->format('Y-m-d');
// 2024-01-31

echo $future->format('Y-m-d');
// 2024-03-07

Метод setTimezone() у DateTimeImmutable тоже возвращает новый объект. Переменная $start сохраняет прежний момент и прежнее представление.

$utc = new DateTimeImmutable('2024-03-24 12:00:00', new DateTimeZone('UTC'));
$userDate = $utc->setTimezone(new DateTimeZone('Europe/Moscow'));

echo $utc->format('Y-m-d H:i:s e');
echo $userDate->format('Y-m-d H:i:s e');

Используйте DateTimeImmutable по умолчанию, когда даты проходят через несколько функций. DateTime оставляйте коду, которому нужна намеренная мутация одного объекта.

У DateTime нет метода __toString(). Если нужен неявный вывод объекта, создайте наследника и явно задайте этот метод.

class MyDate extends DateTimeImmutable
{
    public function __toString(): string
    {
        return $this->format('Y-m-d H:i:s');
    }
}

$date = new MyDate('2024-03-24 12:30:00');
echo $date;

Хранение в БД

Храните момент в UTC, а часовой пояс пользователя применяйте при выводе.

Такой порядок отделяет значение события от настроек конкретного пользователя.

$userTz = new DateTimeZone('America/New_York');
$event = new DateTimeImmutable('2024-03-24 15:30:00', $userTz);
$dbValue = $event
    ->setTimezone(new DateTimeZone('UTC'))
    ->format('Y-m-d H:i:s');

echo $dbValue;
// 2024-03-24 19:30:00

Перед записью в базу приведите объект к UTC и формату SQL. Передайте строку $dbValue в параметр SQL-запроса, а не вставляйте ее конкатенацией.

// Пример строки, полученной из поля created_at в БД.
$row = ['created_at' => '2024-03-24 19:30:00'];
$userTz = new DateTimeZone('Europe/Moscow');

$utc = new DateTimeImmutable($row['created_at'], new DateTimeZone('UTC'));
$userDate = $utc->setTimezone($userTz);

echo $userDate->format('d.m.Y H:i');
// 24.03.2024 22:30

Строка $row['created_at'] приходит из базы.

Сначала объявите, что она относится к UTC, затем переведите объект в зону пользователя и вызовите format().

// Пример строки paid_at, полученной из БД.
$row = ['paid_at' => '2024-03-24 19:30:00'];
$lastPayment = new DateTimeImmutable(
    $row['paid_at'],
    new DateTimeZone('UTC')
);
$nextPayment = $lastPayment->add(new DateInterval('P1M'));
$now = new DateTimeImmutable('2024-04-24 19:30:00', new DateTimeZone('UTC'));

if ($now >= $nextPayment) {
    echo 'Срок подписки истек';
}

Для подписки сохраните дату последней оплаты в UTC. Добавьте период тарифа и сравните результат с текущим моментом в той же зоне.

Изменения в версиях PHP

Современный API даты включает DateTimeInterface и статические методы создания объектов из совместимых дат. Не смешивайте методы разных классов: DateTime::createFromImmutable() превращает DateTimeImmutable в DateTime, а createFromInterface() доступен у DateTime и DateTimeImmutable в PHP 8.0.

В PHP 8.2 у DatePeriod появилась константа INCLUDE_END_DATE. В PHP 8.3 появились DateError, DateException и DateMalformedStringException. Эти классы помогают точнее различать ошибки работы с датами.

Алгоритм работы с датами

Четыре правила помогают избежать рассинхрона и ошибок разбора.

  1. Создайте DateTimeImmutable с явным DateTimeZone.
  2. Разберите входную строку через конструктор или createFromFormat() и обработайте ошибку.
  3. Храните момент в UTC, а перед выводом переведите его в зону пользователя.
  4. Выведите результат через format() и выберите коды под задачу.

Для сдвигов по календарю отдельно проверьте конец месяца. Для повторяющихся дат применяйте DatePeriod с DateInterval. Такой порядок сохраняет исходный объект, делает часовой пояс видимым и не прячет ошибку разбора.

Комментарии

Оставьте свой комментарий
Пока никто не оставил комментариев