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

<?php

/**
 * 指定されたフォーマットに従って日付文字列を解析し、その構成要素を配列として返します。
 * これは、日付文字列が期待される形式であるかを確認したり、個々の要素を抽出したりする際に有用です。
 *
 * @param string $format 解析に使用する日付フォーマット文字列。例: 'Y-m-d H:i:s'
 * @param string $datetime_string 解析する日付と時刻の文字列。例: '2023-01-15 14:30:05'
 * @return void
 */
function parseDateStringWithFormat(string $format, string $datetime_string): void
{
    // date_parse_from_format関数を使用して、日付文字列を指定されたフォーマットで解析します。
    // 成功した場合は解析結果の配列を、失敗した場合はfalseを返します。
    $parsed_info = date_parse_from_format($format, $datetime_string);

    // 解析結果がfalseでなく、エラーや警告が検出されなかったかを確認します。
    if ($parsed_info !== false && $parsed_info['error_count'] === 0 && $parsed_info['warning_count'] === 0) {
        echo "日付文字列 '$datetime_string' の解析に成功しました (フォーマット: '$format')。\n";
        echo "抽出された日付情報:\n";
        echo "  年: " . ($parsed_info['year'] ?? 'N/A') . "\n";
        echo "  月: " . ($parsed_info['month'] ?? 'N/A') . "\n";
        echo "  日: " . ($parsed_info['day'] ?? 'N/A') . "\n";
        echo "  時: " . ($parsed_info['hour'] ?? 'N/A') . "\n";
        echo "  分: " . ($parsed_info['minute'] ?? 'N/A') . "\n";
        echo "  秒: " . ($parsed_info['second'] ?? 'N/A') . "\n";
        // その他、タイムゾーンや曜日などの情報も配列に含まれる場合があります。
    } else {
        echo "日付文字列 '$datetime_string' の解析に失敗しました (フォーマット: '$format')。\n";
        if ($parsed_info === false) {
            echo "  解析関数がfalseを返しました。入力フォーマットと文字列が完全に一致しない可能性があります。\n";
        } else {
            // 解析はできたが、エラーや警告があった場合
            if (!empty($parsed_info['errors'])) {
                echo "  検出されたエラー:\n";
                print_r($parsed_info['errors']);
            }
            if (!empty($parsed_info['warnings'])) {
                echo "  検出された警告:\n";
                print_r($parsed_info['warnings']);
            }
        }
    }
    echo "\n"; // 結果を見やすくするための改行
}

// --- サンプル使用例 ---

// 1. 正しいフォーマットで日付文字列を解析する例
$correct_format = 'Y-m-d H:i:s';
$correct_datetime = '2023-04-20 10:00:00';
parseDateStringWithFormat($correct_format, $correct_datetime);

// 2. フォーマットと一致しない日付文字列を解析する例
// この場合、解析は失敗し、エラー情報が出力されます。
$mismatched_format = 'Y/m/d H:i'; // 期待するフォーマット
$mismatched_datetime = '2023-04-20 10:00:00'; // 実際の文字列はY-m-d形式
parseDateStringWithFormat($mismatched_format, $mismatched_datetime);

// 3. 不完全な日付文字列を解析する例
// 日付の必須要素がないため、エラーとなる場合があります。
$incomplete_format = 'Y-m-d';
$incomplete_datetime = '2023-04-20';
parseDateStringWithFormat($incomplete_format, $incomplete_datetime);

?>

PHPのdate_parse_from_format関数は、特定の日付と時刻の文字列を、指定されたフォーマットに基づいて解析し、その詳細な構成要素を配列として取得するために利用されます。これにより、入力された日付データが期待する形式に沿っているかを確認したり、年、月、日、時、分、秒といった個々の情報を効率的に抽出したりすることが可能になります。

この関数は二つの引数を必要とします。一つ目の$formatは、解析対象となる日付文字列がどのような書式で記述されているかを示すためのテンプレート文字列です。例えば、「Y-m-d H:i:s」のように指定します。二つ目の$datetimeは、実際に解析を行いたい日付と時刻を表す文字列そのものです。

戻り値は、解析が成功した場合は日付の各要素（年、月、日、時、分、秒など）や、解析中に発生したエラー、警告情報を含む連想配列が返されます。もし、提供された日付文字列が指定されたフォーマットに全く合致しなかった場合や、致命的な問題があった場合はfalseが返されます。サンプルコードでは、この関数を用いて日付文字列を解析し、成功時にはその情報を表示し、フォーマットの不一致により解析が失敗した際には、エラーや警告の内容を出力する例が示されており、戻り値の確認方法が理解できます。

<?php

/**
 * Parses a date string using a specified format and converts it to a Unix timestamp.
 *
 * This function demonstrates the use of date_parse_from_format to extract date/time components,
 * and then converts these components into a Unix timestamp via a DateTime object.
 *
 * @param string $format   The format string for the date. For example, 'Y-m-d H:i:s'.
 * @param string $datetime The date and time string to parse. For example, '2023-10-27 15:30:00'.
 * @return int|false Returns a Unix timestamp (integer) on success, or false on failure.
 */
function parseDateToTimestamp(string $format, string $datetime): int|false
{
    // 1. Parse the date string using the specified format.
    // date_parse_from_format returns an associative array of date/time components
    // (e.g., year, month, day, hour, minute, second) or false if the format is invalid.
    $parsedDate = date_parse_from_format($format, $datetime);

    // 2. Check if parsing was successful and without errors or warnings.
    // 'error_count' and 'warning_count' indicate issues in parsing even if a result array is returned.
    if ($parsedDate === false || $parsedDate['error_count'] > 0 || $parsedDate['warning_count'] > 0) {
        // Return false if parsing failed or contained errors/warnings.
        return false;
    }

    // 3. Extract components from the parsed array, providing default values for missing parts.
    // If the format string doesn't include time (e.g., 'Y-m-d'), the time components will be null.
    // We default them to 0 for time and 1 for month/day, or 1970 for year to represent the Unix epoch start.
    $year   = $parsedDate['year'] ?? 1970;
    $month  = $parsedDate['month'] ?? 1;
    $day    = $parsedDate['day'] ?? 1;
    $hour   = $parsedDate['hour'] ?? 0;
    $minute = $parsedDate['minute'] ?? 0;
    $second = $parsedDate['second'] ?? 0;

    // 4. Create a DateTime object from the reconstructed date/time components.
    // This is a robust and modern way to handle dates and times in PHP, and to get a timestamp.
    // We format the components into an ISO 8601-like string ('YYYY-MM-DD HH:MM:SS'),
    // which the DateTime constructor understands well.
    try {
        $dateTimeString = sprintf(
            '%04d-%02d-%02d %02d:%02d:%02d',
            $year,
            $month,
            $day,
            $hour,
            $minute,
            $second
        );
        $dateTime = new DateTime($dateTimeString);

        // 5. Get the Unix timestamp (seconds since Unix Epoch) from the DateTime object.
        return $dateTime->getTimestamp();
    } catch (Exception $e) {
        // Catch any exception that might occur during DateTime object creation.
        // This can happen if the reconstructed date/time components are somehow invalid
        // (e.g., February 30th), though initial checks should largely prevent this.
        return false;
    }
}

このPHPのサンプルコードは、特定の日付書式を持つ文字列からUnixタイムスタンプを生成する手順を示しています。

date_parse_from_format関数は、第一引数$formatで指定された書式に基づいて、第二引数$datetimeで与えられた日付文字列を解析します。解析が成功すると、年、月、日、時、分、秒などの日付・時刻の各要素を含む連想配列を返しますが、書式が一致しないなどの理由で失敗した場合はfalseを返します。

コード内のparseDateToTimestamp関数では、まずこのdate_parse_from_formatを用いて日付文字列を解析します。解析結果がfalseであったり、エラーや警告が含まれていたりした場合には、関数はfalseを返して処理を中止します。 次に、解析によって得られた各日付・時刻の要素を取り出し、もし一部の要素が不足している場合は適切なデフォルト値（例えば年なら1970年、時なら0など）を補います。 これらの要素を組み合わせて日付時刻文字列を再構築し、PHPのモダンな日付時刻操作機能であるDateTimeオブジェクトを生成します。 最後に、このDateTimeオブジェクトのgetTimestamp()メソッドを呼び出すことで、Unixタイムスタンプ（1970年1月1日00:00:00 UTCからの経過秒数）を取得し、関数の戻り値として返しています。 この関数は、日付文字列の解析とタイムスタンプ変換が成功すれば整数型のUnixタイムスタンプを、失敗した場合はfalseを返します。