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

<?php

/**
 * date_date_set 関数の使用例を示す関数。
 * この関数はDateTimeオブジェクトの日付部分（年、月、日）を設定します。
 * 有効な日付と無効な日付の両方のケースを示し、戻り値の型 `DateTime|false` に対応します。
 */
function exampleDateDateSet(): void
{
    echo "--- 有効な日付の設定例 ---\n";
    // 1. 現在の日付と時刻でDateTimeオブジェクトを初期化
    $dateTimeSuccess = new DateTime();
    echo "初期の日付: " . $dateTimeSuccess->format('Y-m-d H:i:s') . "\n";

    // 2. date_date_set を使って日付部分を2025年1月1日に設定
    $yearSuccess = 2025;
    $monthSuccess = 1;
    $daySuccess = 1;
    // 成功するとDateTimeオブジェクト自体が返され、失敗するとfalseが返されます。
    $resultSuccess = date_date_set($dateTimeSuccess, $yearSuccess, $monthSuccess, $daySuccess);

    // 3. 設定が成功したか確認し、結果を出力
    if ($resultSuccess instanceof DateTime) {
        echo "日付設定後の日付: " . $dateTimeSuccess->format('Y-m-d H:i:s') . "\n";
        echo "（時刻部分は変更されていません）\n";
    } else {
        // 通常、有効な日付ではこのブロックには入りません
        echo "日付設定に失敗しました。\n";
        echo "DateTimeオブジェクトは変更されていません: " . $dateTimeSuccess->format('Y-m-d H:i:s') . "\n";
    }

    echo "\n--- 無効な日付の設定例 ---\n";
    // 1. 別のDateTimeオブジェクトを初期化
    $dateTimeFailure = new DateTime();
    echo "初期の日付: " . $dateTimeFailure->format('Y-m-d H:i:s') . "\n";

    // 2. date_date_set を使って無効な日付部分を設定 (例: 2月30日)
    $yearFailure = 2024; // 閏年でも2月30日は存在しません
    $monthFailure = 2;
    $dayFailure = 30;
    $resultFailure = date_date_set($dateTimeFailure, $yearFailure, $monthFailure, $dayFailure);

    // 3. 設定が成功したか確認し、結果を出力
    if ($resultFailure instanceof DateTime) {
        // 無効な日付を指定した場合、通常このブロックには入りません
        echo "日付設定後の日付: " . $dateTimeFailure->format('Y-m-d H:i:s') . "\n";
    } else {
        // 無効な日付のため、設定は失敗しfalseが返されます。
        // DateTimeオブジェクトは変更されずに元の値のままです。
        echo "無効な日付 (" . $yearFailure . "年" . $monthFailure . "月" . $dayFailure . "日) のため、日付設定に失敗しました。\n";
        echo "DateTimeオブジェクトは変更されていません: " . $dateTimeFailure->format('Y-m-d H:i:s') . "\n";
    }
}

// 関数の実行
exampleDateDateSet();

date_date_set関数は、PHPで日付と時刻を扱うDateTimeオブジェクトに対して、その日付部分（年、月、日）を設定するための関数です。第一引数には日付を設定したいDateTimeオブジェクトを渡し、第二引数に年、第三引数に月、第四引数に日を整数で指定します。

この関数が正常に処理されると、日付が更新されたDateTimeオブジェクト自身が返されます。この際、時刻部分は変更されず、日付部分のみが指定された値に更新されます。しかし、例えば「2月30日」のように存在しない無効な日付を指定した場合、この関数は失敗し、戻り値としてfalseを返します。設定が失敗した場合は、元のDateTimeオブジェクトは変更されずにそのままの状態を保ちます。

提供されたサンプルコードでは、まず有効な日付（2025年1月1日）を設定し、DateTimeオブジェクトが正しく更新される様子を示しています。次に、無効な日付（2月30日）を設定する例を通じて、関数がfalseを返し、元のDateTimeオブジェクトが変更されないという挙動を具体的に確認できます。これにより、この関数の使い方と安全なエラーハンドリングの方法を学ぶことができます。