date_create()

Введение

Функция date_create() в PHP — это процедурный способ создания объекта DateTime, который является объектно-ориентированным строительным блоком для работы с датами и временем в PHP. В этой статье рассматриваются её синтаксис и параметры, показано, как считывать данные из объекта DateTime, объясняется поведение при ошибке разбора и приводятся связанные функции.

date_create() — это просто псевдоним для new DateTime(). Обе формы взаимозаменяемы, поэтому используйте ту, которая лучше читается в вашем коде. Одна из причин предпочесть date_create() состоит в том, что, в отличие от конструктора, она возвращает false вместо выброса исключения при неверной строке — что можно обработать без блока try/catch.

Функция date_create()

Функция date_create() — это встроенная функция PHP, создающая новый объект DateTime. Она принимает необязательный параметр, задающий дату и время в формате, распознаваемом функцией strtotime(). Если параметр не передан, функция возвращает объект DateTime, представляющий текущие дату и время.

Синтаксис

Синтаксис функции date_create() выглядит следующим образом:

Синтаксис функции date_create() в PHP

date_create(string $datetime = "now", ?DateTimeZone $timezone = null): DateTime|false

Первый параметр, $time, задаёт дату и время для создания объекта DateTime. Он необязателен и имеет значение по умолчанию "now". Второй параметр, $timezone, задаёт часовой пояс. Он также необязателен и по умолчанию равен NULL.

Параметры

Рассмотрим параметры функции date_create() подробнее:

• $datetime (необязательный): задаёт дату и время для создания объекта DateTime. Может быть любой строкой в формате, распознаваемом функцией strtotime() — абсолютная дата вроде "2022-12-31", относительная фраза вроде "next monday" или "+1 week", или UNIX-метка времени с префиксом @ (например "@1672531199"). Значение по умолчанию "now" возвращает текущие дату и время.
• $timezone (необязательный): объект DateTimeZone, задающий часовой пояс. Если не указан (или null), используется часовой пояс по умолчанию для скрипта. Примечание: этот параметр игнорируется, когда $datetime является UNIX-меткой времени (@...) или уже содержит смещение часового пояса, например "2022-12-31 23:59:59+02:00".

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

При успехе date_create() возвращает объект DateTime. При ошибке — например, если $datetime не удаётся разобрать — она возвращает false вместо выброса исключения. Это делает результат безопасным для проверки простым условием:

<?php

$date = date_create('not a real date');

if ($date === false) {
    echo 'Could not parse the date.';
} else {
    echo $date->format('Y-m-d');
}
// Output: Could not parse the date.

Примеры

Вот несколько примеров использования функции date_create():

Пример использования функции date_create() в PHP

Использование относительных строк дат

Поскольку date_create() принимает всё, что понимает strtotime(), можно строить даты относительно «сейчас» без какой-либо арифметики:

<?php

$today = date_create();
echo $today->format('l') . "\n";          // e.g. Output: Thursday

$nextWeek = date_create('+1 week');
echo $nextWeek->format('Y-m-d') . "\n";   // 7 days from today

$firstOfMonth = date_create('first day of this month');
echo $firstOfMonth->format('Y-m-d');       // e.g. 2023-03-01

Работа с результатом

Получив объект DateTime, вы, как правило, форматируете его для вывода или сравниваете с другой датой:

<?php

$start = date_create('2022-01-01');
$end   = date_create('2022-12-31');

// Format the object as a string
echo $end->format('F j, Y') . "\n";   // Output: December 31, 2022

// Compare two DateTime objects directly
echo ($end > $start ? 'end is later' : 'start is later');
// Output: end is later

Используйте date_format() (или метод ->format(), показанный выше) для вывода объекта и date_diff() для измерения интервала между двумя объектами DateTime.

Связанные функции

• date_create_from_format() — создаёт объект DateTime из строки с произвольным заданным форматом вместо эвристик strtotime().
• date_format() — преобразует объект DateTime в форматированную строку.
• date_add() — добавляет DateInterval к объекту DateTime.
• strtotime() — парсер, лежащий в основе аргумента $datetime; возвращает UNIX-метку времени вместо объекта.

Заключение

Функция date_create() — процедурная точка входа для работы с объектами DateTime в PHP. Она принимает как абсолютные, так и относительные строки дат, при необходимости принимает часовой пояс и возвращает false при ошибке, позволяя проверять входные данные без обработки исключений. Получив объект DateTime, форматируйте его с помощью ->format() и сравнивайте или вычитайте объекты напрямую. Для разбора нестандартных данных используйте date_create_from_format(); для отображения результатов — date_format().

Практика