Разбирает строку с датой по заданному формату

# date_parse_from_format

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

date_parse_from_format — Разбирает строку с датой по заданному формату

### Описание

function date_parse_from_format(string `$format`, string `$datetime`): array

Функция возвращает ассоциативный массив с подробной информацией о дате и времени.

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

`format`

  Описание параметра `format` приводится в документации к методу DateTimeImmutable::createFromFormat(). Для параметра функции действуют аналогичные правила.

`datetime`

  Строковое представление даты и времени.

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

Функция возвращает ассоциативный массив с подробной информацией о дате и времени.

Результирующий массив содержит следующие ключи: `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction` и `is_localtime`.

Элемент `zone_type` укажет тип часового пояса, если массив с результатами содержит элемент `is_localtime`. Для `1`-го типа представления часовых поясов — со смещением относительно времени UTC — добавляются поля `zone` и `is_dst`; для `2`-го типа представления — аббревиатура — добавляются поля `tz_abbr` и `is_dst`; для `3`-го тип — идентификатор часового пояса — добавляются поля `tz_abbr` и `tz_id`.

Массив включает поля `warning_count` и `warnings`. Первое указывает количество предупреждений. Ключи элементов массива `warnings` указывают позицию в аргументе `datetime`, на которой возникло предупреждение, а строковое значение содержит описание предупреждения.

Массив также содержит поля `error_count` и `errors`. Первое указывает количество ошибок. Ключи элементов массива `errors` указывают позицию в аргументе `datetime`, на которой возникла ошибка, а строковое значение содержит описание ошибки.

Внимание

Функция запишет в массивы `warnings` и `errors` меньшее количество элементов, чем указывают значения элементов `warning_count` и `error_count`, если предупреждения или ошибки возникнут на тех же позициях.

### Ошибки

Функция выбрасывает ошибку ValueError, если параметр `datetime` содержит нулевые байты.

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

Версия | Описание
--- | ---
8.0.21, 8.1.8, 8.2.0 | При передаче нулевых байтов в параметр `datetime` функция теперь выбрасывает ошибку ValueError; раньше функция молча игнорировала нулевые байты.
7.2.0 | Элемент `zone` в массиве результатов теперь содержит секунды вместо минут, а знак инвертируется, например: значение `-120` теперь выводится как `7200`.

### Примеры

Пример #1 Пример разбора строки с датой и временем по заданному формату функцией date_parse_from_format()

    <?php

    $date = "6.1.2009 13:00+01:00";
    print_r(date_parse_from_format("j.n.Y H:iP", $date));

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

    Array
    (
        [year] => 2009
        [month] => 1
        [day] => 6
        [hour] => 13
        [minute] => 0
        [second] => 0
        [fraction] => 0
        [warning_count] => 0
        [warnings] => Array
            (
            )

        [error_count] => 0
        [errors] => Array
            (
            )

        [is_localtime] => 1
        [zone_type] => 1
        [zone] => -60
        [is_dst] =>
    )

Пример #2 Пример предупреждения при разборе строки с датой функцией date_parse_from_format()

    <?php

    $date = "26 August 2022 22:30 pm";
    $parsed = date_parse_from_format("j F Y G:i a", $date);

    echo "Количество предупреждений: ", $parsed['warning_count'], "\n";
    foreach ($parsed['warnings'] as $position => $message) {
        echo "\tПозиция {$position}: {$message}\n";
    }

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

    Количество предупреждений: 1
        Позиция 23: The parsed time was invalid

Пример #3 Пример ошибок при разборе строки с датой функцией date_parse_from_format()

    <?php

    $date = "26 August 2022 CEST";
    $parsed = date_parse_from_format("j F Y H:i", $date);

    echo "Количество ошибок: ", $parsed['error_count'], "\n";
    foreach ($parsed['errors'] as $position => $message) {
        echo "\tПозиция {$position}: {$message}\n";
    }

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

    Количество ошибок: 3
        Позиция 15: A two digit hour could not be found
        Позиция 19: Not enough data available to satisfy format

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

- DateTimeImmutable::createFromFormat() - Разбирает строку времени по заданному формату
- checkdate() - Проверяет корректность даты по григорианскому календарю

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open