date_parse()

Введение

Функция date_parse() в PHP принимает удобочитаемую строку даты и разбивает её на отдельные компоненты — год, месяц, день, час, минуту, секунду — возвращая их в виде ассоциативного array. При этом она также сообщает обо всех предупреждениях и ошибках, обнаруженных при разборе строки, что делает её полезным инструментом для валидации даты перед дальнейшей обработкой.

В отличие от strtotime(), которая сворачивает строку даты в единственную временную метку Unix, date_parse() сохраняет каждый компонент отдельно и никогда не теряет диагностическую информацию. Это главная причина её использования: когда вам нужно знать не только что представляет собой дата, но и является ли входная строка действительно корректной датой.

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

Синтаксис

date_parse(string $datetime): array

Функция всегда возвращает array (она никогда не возвращает false); при неудачном разборе сбой описывается в ключе errors, а не сигнализируется возвращаемым значением.

Параметры

$datetime — string, представляющий разбираемую дату/время. Принимаются те же гибкие форматы, что понимает внутренний парсер дат PHP, например:

• '2022-03-03 15:30:45' — полная дата и время в стиле ISO
• 'July 4, 2023' — естественный язык
• 'now', 'tomorrow', '+1 week' — относительные выражения

Если какой-либо компонент отсутствует в строке (например, не указано время), соответствующий ключ возвращается с пустым значением, а не опускается.

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

Функция возвращает ассоциативный array со следующими ключами:

• year, month, day — компоненты даты (целые числа или пустые, если отсутствуют)
• hour, minute, second — компоненты времени (целые числа или пустые, если отсутствуют)
• fraction — дробная часть секунд (число с плавающей точкой, например 0)
• warning_count — количество предупреждений, возникших при разборе
• warnings — array предупреждений с ключами по позиции символа во входной строке
• error_count — количество ошибок, возникших при разборе
• errors — array ошибок с ключами по позиции символа во входной строке
• is_localtime — содержит ли строка информацию о часовом поясе

Когда is_localtime равно true, дополнительные ключи, такие как zone_type, zone и is_dst, описывают часовой пояс.

Базовый пример

Разберём полную строку даты и времени:

Вывод:

Array
(
    [year] => 2022
    [month] => 3
    [day] => 3
    [hour] => 15
    [minute] => 30
    [second] => 45
    [fraction] => 0
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] =>
)

Каждый компонент теперь доступен отдельно — например, $date_arr['month'] равно 3. Поскольку error_count и warning_count оба равны 0, мы знаем, что строка являлась корректной датой без ошибок.

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

date_parse() не требует полной даты. Если передать только дату без времени, ключи времени вернутся пустыми:

<?php

$result = date_parse('July 4, 2023');
echo "Year: {$result['year']}\n";
echo "Month: {$result['month']}\n";
echo "Day: {$result['day']}\n";
echo "Hour: '{$result['hour']}'\n"; // empty — no time was given

Вывод:

Year: 2023
Month: 7
Day: 4
Hour: ''

Это удобно, когда вы принимаете даты без времени и хотите получить отдельные компоненты, не создавая собственный парсер.

Обнаружение некорректных дат с помощью предупреждений

Именно здесь date_parse() проявляет себя лучше всего. Рассмотрим 30 февраля — дату, которой не существует. Парсер всё равно вернёт значения, но отметит проблему в warnings:

<?php

$result = date_parse('2023-02-30');

if ($result['warning_count'] > 0) {
    foreach ($result['warnings'] as $position => $message) {
        echo "Warning at position $position: $message\n";
    }
}

Вывод:

Warning at position 11: The parsed date was invalid

Всегда проверяйте error_count (строка вообще не была распознана) и warning_count (строка была распознана, но описывает невозможную дату), прежде чем доверять разобранным компонентам. Для строгой проверки корректности конкретной даты по году, месяцу и дню используйте вместе с этим функцию checkdate().

Когда использовать date_parse() вместо связанных функций

Если впоследствии вам потребуется отформатировать дату, см. date() для преобразования компонентов в строку.

Заключение

Функция date_parse() предоставляет простой способ разбить строку даты на отдельные компоненты, сообщая при этом обо всех предупреждениях и ошибках. Эта двойная роль — извлечение и валидация — делает её особенно полезной для проверки дат, введённых пользователем, перед их обработкой. Используйте её вместе с checkdate() для строгой валидации или с strtotime() и DateTime, когда нужны временные метки или полноценные объекты дат.

Практика