date_parse_from_format

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

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

説明

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] =>
    [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: Data missing

参考

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

Improve This Page

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 1 note

down

jp dot amarok at email dot cz ¶

1 month ago

It seems that the safest way to check for errors is not by checking the number of errors, but warnings instead. See the following example where "m" and "d" are swapped and thus not correct.

<?php
var_dump( date_parse_from_format('m.d.Y', '18.10.2024') );

OUTPUT:
array(12) {
  ["year"]=>
  int(2024)
  ["month"]=>
  int(18)
  ["day"]=>
  int(10)
  ["hour"]=>
  bool(false)
  ["minute"]=>
  bool(false)
  ["second"]=>
  bool(false)
  ["fraction"]=>
  bool(false)
  ["warning_count"]=>
  int(1)
  ["warnings"]=>
  array(1) {
    [10]=>
    string(27) "The parsed date was invalid"
  }
  ["error_count"]=>
  int(0)
  ["errors"]=>
  array(0) {
  }
  ["is_localtime"]=>
  bool(false)
}
?>

The function simply assigns 18 to the "month" field without errors!! So simply use an if-condition and check "warning_count" to detect possible errors.

＋add a note