指定した書式でフォーマットされた日付についての情報を取得する

# 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` というキーを持ちます。

`is_localtime` が存在する場合、 `zone_type` がタイムゾーンのタイプを示します。 タイプ `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` よりも少なくなる可能性があります。

### エラー / 例外

`datetime` に NULLバイトが含まれている場合は、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.0.21, 8.1.8, 8.2.0 | `datetime` に NULLバイトが含まれている場合は、 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] => 3600
        [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 "Warnings count: ", $parsed['warning_count'], "\n";
    foreach ($parsed['warnings'] as $position => $message) {
        echo "\tOn position {$position}: {$message}\n";
    }

上の例の出力は以下となります。

    Warnings count: 1
    	On position 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 "Errors count: ", $parsed['error_count'], "\n";
    foreach ($parsed['errors'] as $position => $message) {
        echo "\tOn position {$position}: {$message}\n";
    }

上の例の出力は以下となります。

    Errors count: 3
    	On position 15: A two digit hour could not be found
    	On position 19: Not enough data available to satisfy format

### 参考

- DateTimeImmutable::createFromFormat() - 時刻の文字列を指定されたフォーマットに従ってパースする
- checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します

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