指定した日付/時刻の詳細な情報を連想配列で返す

# date_parse

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

date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す

### 説明

function date_parse(string `$datetime`): array

date_parse() は、 strtotime() や DateTimeImmutable::__construct() と同じルールに従って `datetime` をパースします。 Unixタイムスタンプ (strtotime() の場合) や DateTimeImmutable (DateTimeImmutable::__construct() の場合) を返す代わりに、指定した `datetime` から検知できた情報を連想配列として返します。

あるグループの要素に関する情報が見つからなかった場合、 そうした情報は `false` に設定されたり、存在しない状態になります。 `datetime` に指定する文字列から、 同等のタイムスタンプや DateTimeImmutable オブジェクトを構築する必要がある場合、 より多くのフィールドを `false` でない値に設定できます。 そうしたことが起こる場合については、 以下に示す例を参照ください。

### パラメータ

`datetime`

  DateTimeImmutable::__construct() が理解できる書式の日付/時刻。

### 戻り値

パースした日付/時刻情報を含む配列を返します。

返される配列は、 `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` が追加されます。

`+3 days` のような、 相対時刻の文字列が `datetime` に存在する場合、返される配列には、`relative` をキーとしたネストされた配列が含まれます。 この配列には、`year`, `month`, `day`, `hour`, `minute`, `second` が含まれ、 渡される文字列に応じて、必要があれば `weekday`, `weekdays` も含まれます。

`warning_count` と `warnings` が配列に含まれます。 最初のフィールドは、警告が何個発生したかを示します。 `warnings` 配列は、 警告を説明する文字列と一緒に、指定された `datetime` のどの場所で警告が発生したかの位置を示します。

`error_count`, `errors` フィールドも配列に含まれます。 最初のフィールドは、エラーが何個発生したかを示します。 `errors` 配列は、 警告を説明する文字列と一緒に、指定された `datetime` のどの場所でエラーが発生したかの位置を示します。

警告

`warnings` と `errors` に含まれる配列の要素数は、 同じ箇所でエラーや警告が発生した場合、 `warning_count` や `error_count` よりも少なくなる可能性があります。

### エラー / 例外

日付/時刻フォーマットにエラーがある場合は、 'errors' 要素にエラーメッセージが格納されます。

### 変更履歴

バージョン | 説明
--- | ---
7.2.0 | 返される配列の `zone` 要素が、 分ではなく秒を表すようになり、 符号が逆になりました。 たとえば、 `-120` は `7200` を表すようになります。

### 例

例1 `datetime` に包括的な情報を指定した date_parse() の例

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5"));

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

    array(12) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

指定された `datetime` にタイムゾーン情報が含まれた場合にのみ、 タイムゾーンの要素が現れるようになります。 この場合、`zone_type` 要素が常に存在し、 値によっては少し多くの要素が含まれます。

例2 タイムゾーンの省略形を与えた場合の date_parse() の例

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

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

    array(16) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(2)
      ["zone"]=>
      int(0)
      ["is_dst"]=>
      bool(true)
      ["tz_abbr"]=>
      string(3) "BST"
    }

例3 タイムゾーン情報を与えた date_parse() の例

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

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

    array(14) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(3)
      ["tz_id"]=>
      string(13) "Europe/London"
    }

さらに最低限の文字列を `datetime` に与えてパースさせた場合、 情報量はさらに少なくなります。以下の例では、 全ての時刻に関する情報が `false` になります。

例4 最低限の文字列だけを与えた date_parse() の例

    <?php
    var_dump(date_parse("June 2nd, 2022"));

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

    array(12) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      bool(false)
      ["minute"]=>
      bool(false)
      ["second"]=>
      bool(false)
      ["fraction"]=>
      bool(false)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

相対的な書式 は 絶対的な書式のパース結果に影響を及ぼさず、別途 "relative" 要素にまとめられます。

例5 "relative" フォーマットを使った date_parse() の例

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

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

    array(13) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(6) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(7)
        ["hour"]=>
        int(1)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
      }
    }

`Thursday` のように、 語句によっては、文字列の時刻の部分に `0` を設定するものがあります。 `Thursday` を DateTimeImmutable::__construct() に与えた場合、hour, minute, second は `0` に設定されます。 以下の例では、year の要素は `false` に設定されます。

例6 date_parse() の副作用

    <?php
    var_dump(date_parse("Thursday, June 2nd"));

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

    array(13) {
      ["year"]=>
      bool(false)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(0)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(7) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["weekday"]=>
        int(4)
      }
    }

### 参考

- 指定されたフォーマットに従って `datetime` をパースする DateTimeImmutable::parseFromFormat()
- checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
- getdate() - 日付/時刻情報を取得する

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