【PHP8.x】DateTimeImmutable::setMicrosecond()メソッドの使い方

Copy
1<?php
2
3/**
4 * DateTimeImmutable::setMicrosecond() の使用例
5 *
6 * この関数は、DateTimeImmutable オブジェクトのマイクロ秒を設定し、
7 * その変更前後の時刻を表示します。
8 *
9 * @param int $microsecond 設定するマイクロ秒 (0から999999の範囲)
10 */
11function demonstrateSetMicrosecond(int $microsecond): void
12{
13    // 現在の日時でDateTimeImmutableオブジェクトを作成
14    $dateTime = new DateTimeImmutable();
15
16    echo "元のDateTimeImmutableオブジェクト:\n";
17    // オブジェクトの完全な日時（マイクロ秒を含む）を表示
18    echo "  " . $dateTime->format('Y-m-d H:i:s.u') . "\n\n";
19
20    // setMicrosecond() を使用してマイクロ秒を設定
21    // setMicrosecond() は新しいDateTimeImmutableオブジェクトを返すため、
22    // 変数を更新する必要がある
23    $newDateTime = $dateTime->setMicrosecond($microsecond);
24
25    echo "setMicrosecond({$microsecond}) 適用後のDateTimeImmutableオブジェクト:\n";
26    // 変更後のオブジェクトの完全な日時を表示
27    echo "  " . $newDateTime->format('Y-m-d H:i:s.u') . "\n";
28
29    // 元のオブジェクトが変更されていないことを確認（DateTimeImmutableの不変性）
30    // (この行はコメントアウトしても良いが、不変性を示すために残す)
31    // echo "\n元のオブジェクトは変更されていない: " . $dateTime->format('Y-m-d H:i:s.u') . "\n";
32}
33
34// サンプルコードを実行
35// 543210 マイクロ秒を設定する例
36demonstrateSetMicrosecond(543210);
37
38echo "\n---\n\n";
39
40// 別のマイクロ秒値を設定する例
41demonstrateSetMicrosecond(999);
42
43?>

PHP 8で提供されるDateTimeImmutable::setMicrosecondメソッドは、日時を扱うDateTimeImmutableオブジェクトのマイクロ秒部分を設定するために使用されます。このメソッドは、引数としてint $microsecondを受け取り、0から999999の範囲でマイクロ秒の値を指定できます。

このメソッドの重要な点は、DateTimeImmutableオブジェクトが不変であるという性質です。setMicrosecondを呼び出すと、元のDateTimeImmutableオブジェクトは変更されず、マイクロ秒が新しく設定された「別のDateTimeImmutableオブジェクト」が戻り値（static型）として返されます。そのため、変更後の日時を使用するには、戻り値を新しい変数に代入する必要があります。

サンプルコードでは、まず現在のマイクロ秒を含む日時を表示します。次に、setMicrosecond()メソッドを使って指定したマイクロ秒を適用し、その結果得られた新しいDateTimeImmutableオブジェクトの日時を表示しています。これにより、マイクロ秒が正確に設定され、元のオブジェクトとは異なる新しいオブジェクトが生成されたことを確認できます。このメソッドは、日時データの特定のマイクロ秒を精密に制御したい場合に有効です。

Copy
1<?php
2
3// DateTimeImmutable::setMicrosecond の使用例
4// このメソッドは、DateTimeImmutable オブジェクトのマイクロ秒部分を新しい値に設定します。
5// DateTimeImmutable は不変 (immutable) なオブジェクトであるため、
6// このメソッドは常に新しい DateTimeImmutable オブジェクトを返します。
7
8// 1. 初期時刻を持つ DateTimeImmutable オブジェクトを作成します。
9//    ここでは、秒の後にマイクロ秒（.123456）を含めて初期化します。
10$initialDateTime = new DateTimeImmutable('2023-01-15 12:30:45.123456');
11echo "初期時刻: " . $initialDateTime->format('Y-m-d H:i:s.u') . PHP_EOL; // .u はマイクロ秒を表示する書式です
12
13// 2. setMicrosecond メソッドを使ってマイクロ秒を変更します。
14//    新しいマイクロ秒の値 (例: 789012マイクロ秒) を指定します。
15//    このメソッドは変更された新しい DateTimeImmutable オブジェクトを返します。
16$newMicroseconds = 789012;
17$modifiedDateTime = $initialDateTime->setMicrosecond($newMicroseconds);
18
19// 3. 変更後の時刻を表示します。
20echo "変更後時刻: " . $modifiedDateTime->format('Y-m-d H:i:s.u') . PHP_EOL;
21
22// 4. 元のオブジェクトが変更されていないことを確認します。
23//    DateTimeImmutable の不変性により、元の $initialDateTime オブジェクトは変更されずにそのままです。
24echo "元のオブジェクト (不変): " . $initialDateTime->format('Y-m-d H:i:s.u') . PHP_EOL;
25
26?>

DateTimeImmutable::setMicrosecondメソッドは、日時オブジェクトのマイクロ秒部分を新しい値に設定するPHP 8の機能です。引数には、0から999999までの整数でマイクロ秒の値を指定します。このメソッドが所属するDateTimeImmutableクラスは「不変（immutable）」という特性を持っており、一度作成されたオブジェクトの内容は変更されません。そのため、setMicrosecondメソッドを呼び出すと、指定されたマイクロ秒が設定された「新しいDateTimeImmutableオブジェクト」が戻り値として返されます。元のオブジェクトは何も変わらずそのまま保持されますので、安心して操作できます。

サンプルコードでは、まず2023-01-15 12:30:45.123456というマイクロ秒を含む初期時刻を設定します。次に、setMicrosecond(789012)を呼び出して、マイクロ秒部分を789012に変更した新しい日時オブジェクトを作成し、その内容を表示します。最後に、元の日時オブジェクトが変更されていないことを確認することで、DateTimeImmutableの不変な挙動を明確に示しています。これにより、時刻の変更履歴を安全に管理したり、意図しない副作用を防いだりすることが可能になります。