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

<?php

// DateTimeオブジェクトを生成し、初期の日時を設定します。
// これは、現在の日時ではなく、特定の基準日として使用します。
$date = new DateTime('2023-10-26 15:30:00');

echo "元のDateTimeオブジェクト: " . $date->format('Y-m-d H:i:s') . "\n";

// date_modify関数を使って、DateTimeオブジェクトの日時を変更します。
// 第一引数には変更したいDateTimeオブジェクト、
// 第二引数には変更内容を示す文字列（modifier）を指定します。

// 例1: 5日後を追加する
// modifierとして '+5 days' を指定します。
// date_modifyは、成功すると変更されたDateTimeオブジェクトを返し、
// 失敗すると false を返します。
if (date_modify($date, '+5 days') !== false) {
    echo "5日後: " . $date->format('Y-m-d H:i:s') . "\n";
} else {
    echo "日付の変更に失敗しました。\n";
}

// 例2: そこから2時間前
// modifierとして '-2 hours' を指定します。
// `$date`オブジェクトは前回の操作で既に変更されています。
if (date_modify($date, '-2 hours') !== false) {
    echo "そこから2時間前: " . $date->format('Y-m-d H:i:s') . "\n";
} else {
    echo "日付の変更に失敗しました。\n";
}

// 例3: 次の月曜日に変更
// modifierとして 'next monday' を指定します。
if (date_modify($date, 'next monday') !== false) {
    echo "次の月曜日に変更: " . $date->format('Y-m-d H:i:s') . "\n";
} else {
    echo "日付の変更に失敗しました。\n";
}

// 注意: date_modify関数は、引数として渡されたDateTimeオブジェクト自体を直接変更します。
// そのため、毎回同じ `$date` 変数の内容が更新されていきます。

?>

PHPのdate_modify関数は、既存のDateTimeオブジェクトの日時を簡潔に変更するために用いられます。システムエンジニアを目指す上で、日付や時刻の操作は基本的なスキルとなるため、この関数の使い方を理解することは重要です。

この関数は、第一引数に変更したいDateTimeオブジェクトを、第二引数に変更内容を示す文字列（modifier）を受け取ります。modifier文字列は非常に柔軟で、「+5 days」のように具体的な時間の増減を指定できるほか、「next monday」のように相対的な日時への変更も可能です。

date_modify関数が成功すると、変更されたDateTimeオブジェクトが返されます。しかし、最も重要な点は、この関数が引数として渡されたDateTimeオブジェクト自体を直接変更するという挙動です。そのため、サンプルコードのように、一度$dateオブジェクトを生成した後、date_modifyを呼び出すたびに$date変数の内容が順次更新されていくことを確認できます。例えば、最初に設定された2023-10-26 15:30:00が+5 daysで変更され、さらにその変更された日時から-2 hoursやnext mondayといった操作が適用されていきます。

もし日時の変更処理が失敗した場合は、戻り値としてfalseが返されます。そのため、サンプルコードのようにif (date_modify(...) !== false)という条件式を用いて、変更が正常に行われたかを確認することが推奨されます。これにより、予期せぬ日付の変更を防ぎ、堅牢なコードを記述することができます。date_modify関数は、日時の計算や調整をシンプルかつ効率的に行うための強力なツールです。

<?php

/**
 * 指定されたDateTimeオブジェクトをその月の最終日に変更し、変更されたオブジェクトを返します。
 *
 * date_modify関数は、渡されたDateTimeオブジェクト自体を変更します。
 * そのため、引数に渡された$dateオブジェクトもこの関数内で変更されます。
 * この関数は、変更後のDateTimeオブジェクトを返しますが、これは引数に渡されたものと同じインスタンスです。
 *
 * @param DateTime $date 変更したい日付のDateTimeオブジェクト。このオブジェクト自体が変更されます。
 * @return DateTime|false 変更されたDateTimeオブジェクト（成功時）、または処理に失敗した場合はfalse。
 */
function modifyDateToLastDayOfMonth(DateTime $date): DateTime|false
{
    // date_modify関数を使用して、DateTimeオブジェクトをその月の最終日に変更します。
    // "last day of this month"というmodifierは、現在のDateTimeオブジェクトの月を基準に
    // その月の最終日を設定します。
    return date_modify($date, 'last day of this month');
}

// --- 使用例 ---

// 1. 閏年の2月の日付で試す
// 2024年2月15日のDateTimeオブジェクトを作成
$dateFebruary = new DateTime('2024-02-15');
echo "元のDateTimeオブジェクト (2月): " . $dateFebruary->format('Y-m-d') . "\n";

// modifyDateToLastDayOfMonth関数を呼び出して、日付をその月の最終日に変更
$modifiedDateFebruary = modifyDateToLastDayOfMonth($dateFebruary);

if ($modifiedDateFebruary instanceof DateTime) {
    echo "変更後のDateTimeオブジェクト (2月の最終日): " . $modifiedDateFebruary->format('Y-m-d') . "\n";
    // 注意: $dateFebruary 変数自体も変更されています。
    echo "元の変数 (\$dateFebruary) の現在の値: " . $dateFebruary->format('Y-m-d') . "\n";
} else {
    echo "日付の変更に失敗しました。\n";
}

echo "\n"; // 出力を見やすくするための区切り

// 2. 31日まである月の日付で試す
// 2023年1月20日のDateTimeオブジェクトを作成
$dateJanuary = new DateTime('2023-01-20');
echo "元のDateTimeオブジェクト (1月): " . $dateJanuary->format('Y-m-d') . "\n";

// modifyDateToLastDayOfMonth関数を呼び出して、日付をその月の最終日に変更
$modifiedDateJanuary = modifyDateToLastDayOfMonth($dateJanuary);

if ($modifiedDateJanuary instanceof DateTime) {
    echo "変更後のDateTimeオブジェクト (1月の最終日): " . $modifiedDateJanuary->format('Y-m-d') . "\n";
    // 注意: $dateJanuary 変数自体も変更されています。
    echo "元の変数 (\$dateJanuary) の現在の値: " . $dateJanuary->format('Y-m-d') . "\n";
} else {
    echo "日付の変更に失敗しました。\n";
}

?>

PHPのdate_modify関数は、既存のDateTimeオブジェクトの日付や時刻を、指定されたルールに基づいて変更するために利用されます。第一引数には変更したいDateTimeオブジェクトを渡し、第二引数には日付変更の指示を示す文字列（モディファイア）を指定します。特に重要な点は、この関数が引数として渡されたDateTimeオブジェクト自体を直接変更することです。そのため、関数呼び出し後には元の変数の値も変更されています。戻り値は、変更が成功した場合は変更後のDateTimeオブジェクトを、失敗した場合はfalseを返します。成功時に返されるオブジェクトは、引数に渡されたものと全く同じインスタンスです。

サンプルコードでは、date_modify関数を使い「last day of this month」（現在の月の最終日）というモディファイアで、指定された日付をその月の最終日に変更するmodifyDateToLastDayOfMonth関数を定義しています。例えば、2024年2月15日のDateTimeオブジェクトをこの関数に渡すと、date_modifyによってそのオブジェクトは2024年2月29日（閏年の最終日）に変更されます。関数実行後、元の変数$dateFebruaryも変更後の値を持つことが確認でき、日付計算を直感的に行えることを示しています。