Функция PHP date_create_from_format: синтаксис и примеры

Функция date_create_from_format() разбирает строку даты, записанную в вашем формате — а не только в тех форматах, которые PHP угадывает самостоятельно, — и возвращает объект DateTime. Используйте её, когда вы получаете дату в фиксированном, нестандартном виде (из CSV-экспорта, стороннего API, пользовательской формы) и вам нужно надёжно её прочитать.

На этой странице рассматриваются синтаксис, запускаемые примеры, параметр часового пояса, обнаружение ошибок разбора, а также отличия функции от strtotime() и date_parse_from_format().

Синтаксис

date_create_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false

• $format — шаблон входной строки, записанный с теми же символами форматирования, что и в функции date(). Например, "Y-m-d H:i:s" соответствует строке "2023-03-02 17:30:45".
• $datetime — строка даты для разбора. Её вид должен совпадать с $format.
• $timezone — (необязательно) объект DateTimeZone для результирующего объекта. Если не указан, используется текущий часовой пояс по умолчанию (заданный через date_default_timezone_set()). Параметр игнорируется, если $format уже содержит символ часового пояса — e, O, P или T.

При успехе функция возвращает объект DateTime, при несовпадении строки с форматом — false.

date_create_from_format() — процедурный псевдоним статического метода DateTime::createFromFormat(); они ведут себя одинаково.

Примеры

Разбор стандартной строки даты

Функция читает "2023-03-02 17:30:45" согласно шаблону "Y-m-d H:i:s" и возвращает объект DateTime. Вызов format() на нём позволяет отобразить дату в любом нужном вам формате.

Переформатирование нестандартной даты

Здесь входная строка содержит день, трёхбуквенное название месяца и четырёхзначный год (j-M-Y). Вывод отображается в порядке ISO (Y-m-d) — это подтверждает, что когда дата становится объектом DateTime, её можно отображать в любом формате.

Сброс времени с помощью !

Если ваш формат не содержит полей времени, недостающие части по умолчанию принимают текущие значения часа, минуты и секунды — что редко бывает нужным для значения, содержащего только дату. Добавьте ! в начало формата, чтобы сбросить все неуказанные поля до Unix-эпохи (00:00:00):

<?php

$date = date_create_from_format('!Y-m-d', '2023-03-02');
echo $date->format('Y-m-d H:i:s'); // Output: 2023-03-02 00:00:00

Указание часового пояса

<?php

$tz = new DateTimeZone('Europe/Paris');
$date = date_create_from_format('Y-m-d H:i:s', '2023-03-02 17:30:45', $tz);
echo $date->format('Y-m-d H:i:s P'); // Output: 2023-03-02 17:30:45 +01:00

Третий аргумент привязывает разобранную дату к парижскому времени, поэтому токен P выводит смещение +01:00.

Обработка ошибок разбора

Когда строка не совпадает с форматом, функция возвращает false, а не бросает исключение. Всегда проверяйте это и читайте DateTime::getLastErrors() для получения подробностей:

<?php

$date = date_create_from_format('Y-m-d', 'not-a-date');

if ($date === false) {
    $errors = DateTime::getLastErrors();
    echo "Parse failed: {$errors['error_count']} error(s)\n";
    // Output: Parse failed: 3 error(s)
}

Поскольку false является ложным значением, простая конструкция if (!$date) тоже работает, — однако строгая проверка === false надёжнее, если пустое значение может иметь смысл в другом контексте.

Сравнение с другими функциями работы с датами

Используйте date_create_from_format(), когда формат фиксирован и вам нужен полноценный объект DateTime для дальнейших операций. Применяйте strtotime() для свободных, «человекопонятных» строк вроде "next Friday", а date_parse_from_format() — когда вам нужны только числовые значения года, месяца и дня без создания объекта.

Заключение

date_create_from_format() преобразует строку в произвольном, но известном формате в объект DateTime, который можно форматировать, сравнивать и изменять с помощью остального PHP API для работы с датами. Не забывайте использовать префикс ! для значений, содержащих только дату, передавайте DateTimeZone, когда исходный часовой пояс важен, и всегда обрабатывайте возможный возврат false.

Практика