(PHP 5 >= 5.2.0, PHP 7, PHP 8)
date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す
date_parse() は、
strtotime() や
DateTimeImmutable::__construct()
と同じルールに従って
datetime をパースします。
Unixタイムスタンプ (strtotime() の場合)
や DateTimeImmutable
(DateTimeImmutable::__construct() の場合)
を返す代わりに、指定した datetime
から検知できた情報を連想配列として返します。
あるグループの要素に関する情報が見つからなかった場合、
そうした情報は false に設定されたり、存在しない状態になります。
datetime に指定する文字列から、
同等のタイムスタンプや DateTimeImmutable
オブジェクトを構築する必要がある場合、
より多くのフィールドを false でない値に設定できます。
そうしたことが起こる場合については、
以下に示す例を参照ください。
パースした日付/時刻情報を含む配列を返します。
返される配列は、
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()