【PHP8.x】strptime関数の使い方

<?php

/**
 * strptime関数のモダンな代替として、指定されたフォーマットでタイムスタンプを解析します。
 *
 * strptime関数は環境依存の問題があるため、PHP 8ではDateTime::createFromFormatの使用が強く推奨されます。
 *
 * 注意点:
 *   - strptimeのフォーマット文字列（例: %Y-%m-%d）と、
 *     DateTime::createFromFormatのフォーマット文字列（例: Y-m-d）は異なります。
 *     この関数では、PHPのdate関数と同じ形式のフォーマット文字列を使用します。
 *   - 戻り値はDateTimeオブジェクトであり、strptimeの配列とは異なりますが、
 *     より柔軟な日付操作が可能です。
 *
 * @param string $timestamp 解析するタイムスタンプ文字列。
 * @param string $format タイムスタンプのフォーマット文字列（PHPのdate関数形式、例: "Y-m-d H:i:s"）。
 * @return DateTime|false 成功した場合はDateTimeオブジェクト、失敗した場合はfalseを返します。
 */
function parseTimestampWithModernFormat(string $timestamp, string $format): DateTime|false
{
    // DateTime::createFromFormatを使用して、指定されたフォーマットで文字列をDateTimeオブジェクトに変換します。
    // これは、日付/時刻の解析において、strptimeよりも柔軟で信頼性の高い方法です。
    $dateTime = DateTime::createFromFormat($format, $timestamp);

    // 解析に失敗した場合 (例: フォーマットが一致しない、無効な日付) はfalseを返します。
    if ($dateTime === false) {
        return false;
    }

    // createFromFormatは形式上は正しいが、内容が無効な日付（例: 2月30日）を
    // 受け入れた場合、DateTime::getLastErrors()で詳細を確認できます。
    // エラーや警告があれば、解析は「失敗」とみなします。
    $errors = DateTime::getLastErrors();
    if ($errors['error_count'] > 0 || $errors['warning_count'] > 0) {
        return false;
    }

    return $dateTime;
}

// --- サンプルコードの使用例 ---

// strptimeが通常扱うような日付文字列
$timestampString = "2023-10-26 15:30:00";

// DateTime::createFromFormat に対応するフォーマット文字列
// strptimeの `%Y-%m-%d %H:%M:%S` に相当します
$formatString = "Y-m-d H:i:s";

// 日付文字列の解析を実行
$parsedDateTime = parseTimestampWithModernFormat($timestampString, $formatString);

if ($parsedDateTime) {
    // 解析成功の場合、DateTimeオブジェクトから必要な情報を取得できます。
    echo "日付の解析に成功しました。\n";
    echo "年: " . $parsedDateTime->format('Y') . "\n";
    echo "月: " . $parsedDateTime->format('m') . "\n";
    echo "日: " . $parsedDateTime->format('d') . "\n";
    echo "時: " . $parsedDateTime->format('H') . "\n";
    echo "分: " . $parsedDateTime->format('i') . "\n";
    echo "秒: " . $parsedDateTime->format('s') . "\n";
    echo "UNIXタイムスタンプ: " . $parsedDateTime->getTimestamp() . "\n";
} else {
    echo "日付の解析に失敗しました。フォーマットや日付文字列を確認してください。\n";
}

echo "\n";

// 無効な日付文字列の例 (2月30日は存在しないため、解析は失敗します)
$invalidTimestampString = "2023-02-30 10:00:00";
$parsedInvalidDateTime = parseTimestampWithModernFormat($invalidTimestampString, $formatString);

if ($parsedInvalidDateTime) {
    echo "無効な日付の解析に成功しました (これは予期しない動作です)。\n";
} else {
    echo "無効な日付の解析に失敗しました (期待通りの動作です)。\n";
}

echo "\n";

// フォーマットが一致しない例 (指定フォーマットと文字列が異なるため、解析は失敗します)
$mismatchedTimestampString = "2023/10/26";
$mismatchedFormatString = "Y-m-d"; // タイムスタンプ文字列は'/'、フォーマットは'-'で不一致

$parsedMismatchedDateTime = parseTimestampWithModernFormat($mismatchedTimestampString, $mismatchedFormatString);

if ($parsedMismatchedDateTime) {
    echo "フォーマット不一致の解析に成功しました (これは予期しない動作です)。\n";
} else {
    echo "フォーマット不一致の解析に失敗しました (期待通りの動作です)。\n";
}

PHPのstrptime関数は日付文字列を解析して配列として情報を返す機能ですが、環境によって動作が異なる場合があるため、PHP 8ではより信頼性の高いDateTime::createFromFormatの使用が推奨されています。提示されたparseTimestampWithModernFormat関数は、このモダンな代替手法を用いて、指定されたフォーマットでタイムスタンプ文字列を安全に解析するためのものです。

この関数は、解析したい日付文字列を$timestamp引数に、その文字列の形式を$format引数に受け取ります。$formatはPHPのdate関数で使われる形式（例: "Y-m-d H:i:s"）で指定する必要があり、strptimeのフォーマット形式（例: "%Y-%m-%d"）とは異なる点に注意してください。

解析が成功すると、日付や時刻の操作に便利なDateTimeオブジェクトを返します。このオブジェクトからは、年、月、日、時、分、秒などの各要素を簡単に取得したり、UNIXタイムスタンプに変換したりできます。もし日付文字列が無効であったり、指定したフォーマットと文字列の形式が一致しなかったりした場合は、戻り値としてfalseが返されるため、エラーハンドリングも容易に行えます。この関数を利用することで、環境に依存しない堅牢な日付解析処理を実装できます。