【PHP8.x】addメソッドの使い方

addメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年10月19日

基本的な使い方

addメソッドは、DateTimeImmutableオブジェクトが表す日時に、指定された期間を加算する処理を実行するメソッドです。このメソッドは、引数として受け取ったDateIntervalオブジェクトで定義された期間、例えば「10日後」や「3ヶ月後」などを元の日時に加えます。DateTimeImmutableクラスの重要な特徴は「不変性（immutable）」であり、addメソッドを呼び出しても元のオブジェクトの状態は一切変更されません。その代わり、加算処理を行った結果として、新しい日時を表す全く新しいDateTimeImmutableオブジェクトを返します。したがって、計算結果を利用するためには、この返り値を変数に代入して扱う必要があります。この動作は、元のオブジェクト自体を変更するDateTimeクラスのaddメソッドとは対照的です。元のデータを変更しないため、意図しない副作用を防ぎ、安全に日時の計算を行うことができるという利点があります。

構文(syntax)


1<?php
2
3// 基準となる不変の日付オブジェクトを生成します。
4$originalDate = new DateTimeImmutable('2025-01-20');
5
6// 追加したい期間（例: 1ヶ月と10日）をDateIntervalオブジェクトで生成します。
7$interval = new DateInterval('P1M10D');
8
9// add()メソッドは、期間が追加された「新しい」DateTimeImmutableオブジェクトを返します。
10// 元の$originalDateオブジェクトは一切変更されません。
11$newDate = $originalDate->add($interval);
12
13// 結果を出力して比較します。
14echo '元のオブジェクト: ' . $originalDate->format('Y-m-d'); // 出力: 2025-01-20
15echo "\n";
16echo '新しいオブジェクト: ' . $newDate->format('Y-m-d');   // 出力: 2025-03-02
17

引数(parameters)

DateInterval $interval

DateInterval $interval: 追加する期間を指定するDateIntervalオブジェクト

戻り値(return)

DateTimeImmutable

指定された日時から指定された期間を加算した新しい DateTimeImmutable オブジェクトを返します。元のオブジェクトは変更されません。

サンプルコード

PHP DateTimeImmutable::addで日時を加算する


1<?php
2
3/**
4 * DateTimeImmutable::add メソッドを使用して、日付と時刻の変更不可なオブジェクトに
5 * 期間を加算する方法を示すサンプル関数です。
6 * システムエンジニアを目指す初心者の方にも理解しやすいように、具体的な日時操作を例にしています。
7 *
8 * @return void
9 */
10function demonstrateDateTimeImmutableAdd(): void
11{
12    // 現在の日時を取得し、DateTimeImmutable オブジェクトを生成します。
13    // DateTimeImmutable は一度作成されると内容が変更されません。
14    // 日時を変更するメソッドを呼び出すと、新しい DateTimeImmutable オブジェクトが返されます。
15    $currentDateTime = new DateTimeImmutable();
16    echo "現在の日時: " . $currentDateTime->format('Y-m-d H:i:s') . "\n";
17
18    // 1週間、2日、3時間を表す期間オブジェクト (DateInterval) を生成します。
19    // 'P' は期間 (Period) を意味し、'W' は週、'D' は日、'H' は時間を表します。
20    $intervalToAdd = new DateInterval('P1W2DT3H');
21
22    // 現在の日時に上記の期間を加算し、新しい日時オブジェクトを取得します。
23    // add() メソッドは元の $currentDateTime を変更せず、加算後の新しい DateTimeImmutable オブジェクトを返します。
24    $futureDateTime = $currentDateTime->add($intervalToAdd);
25    echo "1週間と2日と3時間加算後の日時: " . $futureDateTime->format('Y-m-d H:i:s') . "\n";
26
27    // 別の期間（例えば、1ヶ月と15分）を加算する例です。
28    $anotherInterval = new DateInterval('P1MT15M'); // P:Period, 1M:1 Month, T:Time, 15M:15 Minutes
29    $futureDateTimeWithAnotherInterval = $currentDateTime->add($anotherInterval);
30    echo "1ヶ月と15分加算後の日時: " . $futureDateTimeWithAnotherInterval->format('Y-m-d H:i:s') . "\n";
31}
32
33// 関数を実行して、日時加算の動作を確認します。
34demonstrateDateTimeImmutableAdd();
35

このコードは、PHP 8で提供されるDateTimeImmutableクラスのaddメソッドを使用して、日付と時刻のオブジェクトに期間を加算する方法を具体的に示しています。

DateTimeImmutableは、一度作成されるとその内容が変更されない「不変」な日時オブジェクトです。そのため、日時を変更する操作を行っても元のオブジェクトは変わらず、新しい日時オブジェクトが生成されて返されます。

addメソッドは、引数としてDateIntervalオブジェクトを受け取ります。このDateIntervalは、例えば「1週間と2日と3時間」や「1ヶ月と15分」といった特定の期間を表現するためのものです。サンプルコードでは、P1W2DT3H（1週間2日3時間）やP1MT15M（1ヶ月15分）のように記述して期間を指定しています。

addメソッドが実行されると、呼び出し元のDateTimeImmutableオブジェクトに指定された期間が加算されますが、元のオブジェクトは変更されません。戻り値として、期間が加算された新しいDateTimeImmutableオブジェクトが返されます。この特性により、元の日時情報を保ちつつ、未来や過去の日時を安全に計算できます。コードでは現在の日時に期間を加算し、その結果をformat()メソッドで整形して表示することで、加算された日時を確認しています。

DateTimeImmutable::addメソッドは、元のオブジェクトを変更しない「不変性」を持ちます。そのため、期間を加算すると「新しい」DateTimeImmutableオブジェクトが返されるため、必ず戻り値を変数に代入して利用してください。加算期間はDateIntervalオブジェクト（例: P1W2DT3H）で指定しますが、その書式が不正確だと意図しない結果となるため、指定方法をよく確認し、正しく記述することが重要です。

DateTimeImmutable::add で日付を加算する


1<?php
2
3/**
4 * DateTimeImmutable::add メソッドの使用例。
5 *
6 * このメソッドは、指定された期間 (DateInterval) を現在の日付/時刻に追加し、
7 * 新しい DateTimeImmutable オブジェクトを返します。
8 * 元の DateTimeImmutable オブジェクトは変更されません。
9 */
10
11// 現在の日付と時刻を表すDateTimeImmutableオブジェクトを作成します。
12// DateTimeImmutableは一度作成されると、その値は変更されない「不変」なオブジェクトです。
13$currentDateTime = new DateTimeImmutable();
14echo "現在の不変な日付時刻: " . $currentDateTime->format('Y-m-d H:i:s') . PHP_EOL;
15
16// 10日間を加算するためのDateIntervalオブジェクトを作成します。
17// 'P10D' は「期間 (Period) の10日間 (10 Days)」を意味します。
18$intervalTenDays = new DateInterval('P10D');
19
20// addメソッドを使用して、現在のDateTimeImmutableオブジェクトに10日間を追加します。
21// 新しいDateTimeImmutableオブジェクトが返されるため、変数に格納します。
22$futureDateTimeAfterTenDays = $currentDateTime->add($intervalTenDays);
23echo "10日後の日付時刻:    " . $futureDateTimeAfterTenDays->format('Y-m-d H:i:s') . PHP_EOL;
24
25// 2ヶ月と5時間を加算するためのDateIntervalオブジェクトも作成できます。
26// 'P2M5H' は「期間 (Period) の2ヶ月 (2 Months) と5時間 (5 Hours)」を意味します。
27$intervalTwoMonthsFiveHours = new DateInterval('P2M5H');
28
29// addメソッドを使用して、現在のDateTimeImmutableオブジェクトに2ヶ月と5時間を追加します。
30$futureDateTimeAfterTwoMonthsFiveHours = $currentDateTime->add($intervalTwoMonthsFiveHours);
31echo "2ヶ月5時間後の日付時刻: " . $futureDateTimeAfterTwoMonthsFiveHours->format('Y-m-d H:i:s') . PHP_EOL;
32
33// 元のDateTimeImmutableオブジェクトが変更されていないことを確認します。
34echo "元の不変な日付時刻 (変更なし): " . $currentDateTime->format('Y-m-d H:i:s') . PHP_EOL;
35
36?>

PHPのDateTimeImmutable::addメソッドは、DateTimeImmutableオブジェクトに指定した期間を追加するためのメソッドです。DateTimeImmutableは、一度作成されるとその値が変わらない「不変」なオブジェクトであるため、このメソッドを呼び出しても元のオブジェクトは変更されません。代わりに、加算後の新しいDateTimeImmutableオブジェクトが戻り値として返されます。

このメソッドは、DateInterval型の引数を受け取ります。DateIntervalは、「P10D」（期間の10日間）や「P2M5H」（期間の2ヶ月5時間）のように、日付や時刻に加算したい期間を表現するためのオブジェクトです。

サンプルコードでは、まず現在の時刻を示すDateTimeImmutableオブジェクトを作成しています。次に、「10日間」や「2ヶ月5時間」といった期間を表すDateIntervalオブジェクトをそれぞれ作成し、addメソッドで現在の時刻に加算しています。その結果として得られる未来の新しい日付時刻を表示するとともに、元のDateTimeImmutableオブジェクトが変更されずにそのまま保持されていることも確認しています。これにより、日付時刻計算の安全性と予測可能性が高まります。

PHPのDateTimeImmutable::addメソッドでは、元のDateTimeImmutableオブジェクトは変更されず、加算結果を持つ新しいDateTimeImmutableオブジェクトが返されます。そのため、メソッドの戻り値を必ず変数に代入して使用してください。代入を忘れると、日付時刻が加算されていないかのように見えてしまう点に注意が必要です。また、引数に指定するDateIntervalオブジェクトの書式は、Pで始まる期間指定のルール（例: P10Dで10日間、P2M5Hで2ヶ月5時間）を正確に理解し、正しく記述することが重要です。この不変性は、予期せぬ日付の変更を防ぎ、より堅牢なコードを記述するために役立ちます。