date_parse

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

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

説明

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() - 日付/時刻情報を取得する