【PHP8.x】setTimeメソッドの使い方
setTimeメソッドの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
setTimeメソッドは、PHPのDateTimeクラスに属し、DateTimeオブジェクトの時刻部分を設定するメソッドです。このメソッドは、指定された時、分、秒、およびマイクロ秒の値に基づいて、既存のDateTimeオブジェクトの時刻を変更します。DateTimeオブジェクトが保持する日付部分は変更されず、元のDateTimeオブジェクトの日付は保持されるため、日付を維持しつつ時刻だけを更新したい場合に非常に便利です。
具体的には、setTimeメソッドは必須引数として、整数型の$hour（時、0～23の範囲）と$minute（分、0～59の範囲）を受け取ります。さらに、オプション引数として$second（秒、0～59の範囲）と$microsecond（マイクロ秒、0～999999の範囲）を指定できます。これらのオプション引数を省略した場合、$secondは0に、$microsecondも0に設定されます。
setTimeメソッドは、時刻が変更されたDateTimeオブジェクト自身を返します。このため、メソッドチェーンとして他のDateTimeメソッドと組み合わせて利用することも可能です。例えば、ある特定の日付のDateTimeオブジェクトがあり、その日付はそのままに時刻だけを午前9時30分0秒に設定したい場合などにこのメソッドを活用できます。日付と時刻を厳密に扱うシステムにおいて、時刻の操作を柔軟かつ効率的に行いたい場合に非常に役立つ機能です。
構文(syntax)
1<?php 2 3$dateTime = new DateTime('2023-10-26 12:00:00'); 4$dateTime->setTime(9, 30, 15); 5echo $dateTime->format('Y-m-d H:i:s'); 6 7?>
引数(parameters)
int $hour, int $minute, int $second = 0, int $microsecond = 0
- int $hour: 時を指定する整数 (0-23)
- int $minute: 分を指定する整数 (0-59)
- int $second = 0: 秒を指定する整数 (0-59)
- int $microsecond = 0: マイクロ秒を指定する整数 (0-999999)
戻り値(return)
DateTime
このメソッドは、DateTimeオブジェクト自身を返します。これにより、メソッドチェーン（メソッドを連続して呼び出すこと）が可能になります。
サンプルコード
PHP DateTime::setTimeで時刻を設定する
1<?php 2 3/** 4 * DateTime::setTime メソッドの使用例。 5 * この関数は、DateTime オブジェクトの時刻部分を設定します。 6 * 7 * キーワード「php settimeout」を「時刻を設定する」という文脈で捉え、 8 * 特定の時刻をDateTimeオブジェクトに設定する基本的な操作を示します。 9 * これは、例えばタイムアウトの基準時刻を定義する際などに、 10 * 特定の日付は変えずに時刻のみを設定したい場合に役立ちます。 11 */ 12function demonstrateDateTimeSetTime(): void 13{ 14 // 1. 現在の日時で新しいDateTimeオブジェクトを作成します。 15 // このオブジェクトの日付部分はそのまま維持されます。 16 $dateTime = new DateTime(); 17 echo "初期のDateTimeオブジェクト: " . $dateTime->format('Y-m-d H:i:s.u') . PHP_EOL; 18 19 // 2. setTimeメソッドを使用して、時刻部分を午前9時30分15秒に設定します。 20 // 引数: int $hour (時), int $minute (分), int $second (秒, デフォルトは0), int $microsecond (マイクロ秒, デフォルトは0) 21 // このメソッドは、変更されたDateTimeオブジェクト自身を返します。 22 $dateTime->setTime(9, 30, 15); 23 echo "時刻を9時30分15秒に設定後: " . $dateTime->format('Y-m-d H:i:s.u') . PHP_EOL; 24 25 // 3. マイクロ秒も指定して時刻を設定する例。 26 // 例えば、14時05分00秒500000マイクロ秒（0.5秒）に設定します。 27 $dateTime->setTime(14, 5, 0, 500000); 28 echo "時刻を14時05分00秒500000マイクロ秒に設定後: " . $dateTime->format('Y-m-d H:i:s.u') . PHP_EOL; 29 30 // setTimeメソッドはDateTimeオブジェクト自身を返すため、メソッドチェーンも可能です。 31 // 例: 特定の基準日を午前0時に設定する。 32 $baseTime = new DateTime('2023-01-01'); 33 echo "基準日のDateTimeオブジェクト (初期): " . $baseTime->format('Y-m-d H:i:s.u') . PHP_EOL; 34 35 $baseTime->setTime(0, 0, 0); // 基準日を午前0時に設定 36 echo "基準日を午前0時に設定後: " . $baseTime->format('Y-m-d H:i:s.u') . PHP_EOL; 37} 38 39// 上記の関数を実行し、DateTime::setTimeの動作を確認します。 40demonstrateDateTimeSetTime(); 41 42?>
PHPのDateTime::setTimeメソッドは、DateTimeオブジェクトの日付部分はそのままで、時刻部分のみを正確に設定するために利用されます。これは、例えば「php settimeout」のように、特定の日付は固定しつつ、タイムアウトの基準時刻やイベントの発生時刻などを柔軟に制御したい場合に非常に役立ちます。
このメソッドは、int $hour（時）、int $minute（分）を必須の引数として受け取ります。さらに、int $second（秒）とint $microsecond（マイクロ秒）も指定可能で、これらは省略した場合に0がデフォルト値として適用されます。戻り値としては、時刻が設定され変更されたDateTimeオブジェクト自身が返されます。このため、メソッドチェーンを用いて一連の時刻操作を行うことも可能です。
サンプルコードでは、最初に現在のDateTimeオブジェクトを作成し、その時刻をsetTime(9, 30, 15)で「9時30分15秒」に設定する例を示しています。続いて、setTime(14, 5, 0, 500000)のようにマイクロ秒まで指定して「14時05分00秒500000マイクロ秒（0.5秒）」に設定する高度な使い方も紹介しています。また、特定の日付を持つオブジェクトに対し、setTime(0, 0, 0)を使って時刻を「午前0時」に設定することで、その日の開始時刻を明確に定義するといった応用的な利用も可能です。このように、日付を変更せずに時刻だけを精密に調整したい場合に、このメソッドは不可欠です。
DateTime::setTimeは、既存のDateTimeオブジェクトの日付部分を変えずに、時刻部分（時、分、秒、マイクロ秒）のみを設定するメソッドです。引数には整数値を指定し、秒とマイクロ秒は省略すると0として扱われます。時刻の範囲外の値を指定すると、内部で日付が繰り上がったり繰り下がったりする場合がありますが、意図しない結果を避けるため、適切な範囲の値を渡すようにしましょう。このメソッドは変更されたDateTimeオブジェクト自身を返すため、メソッドチェーンを利用して続けて操作することも可能です。タイムゾーンは元のDateTimeオブジェクトのものが維持されます。