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

setTimestampメソッドは、DateTimeImmutableオブジェクトの持つ日付と時刻を、指定されたUnixタイムスタンプに基づいて設定する新しいオブジェクトを生成するメソッドです。このメソッドはPHPのDateTimeImmutableクラスに属しており、プログラム内で日付と時刻をオブジェクト指向の方法で、かつ安全に扱うために利用されます。

引数として、Unixエポック（1970年1月1日 00:00:00 UTC）からの経過秒数を表す整数値、すなわちUnixタイムスタンプを受け取ります。このタイムスタンプの値に基づいて、DateTimeImmutableオブジェクトの内部的な日付と時刻が決定されます。

DateTimeImmutableクラスの重要な特性として、そのオブジェクトが「イミュータブル（変更不可能）」であることが挙げられます。そのため、setTimestampメソッドを呼び出しても、呼び出し元のDateTimeImmutableオブジェクト自体は変更されません。代わりに、指定されたタイムスタンプが適用された全く新しいDateTimeImmutableオブジェクトが生成されて返されます。この仕組みにより、元のオブジェクトが意図せず変更されることを防ぎ、予測可能で安全な日付操作を保証します。

成功した場合は、新しいDateTimeImmutableオブジェクトを返します。PHP 8では、無効なタイムスタンプが与えられた場合など、処理中にエラーが発生すると、DateInvalidExceptionやDateMalformedStringExceptionのような適切な例外がスローされますので、エラー処理の際はこれらの例外を考慮に入れる必要があります。特定のUnixタイムスタンプから正確な日付と時刻を持つDateTimeImmutableオブジェクトを生成したい場合に、このメソッドは非常に有用です。

Copy
1<?php
2$dateTimeImmutable = new DateTimeImmutable('2023-10-27 10:00:00');
3$unixTimestamp = 1678886400; // 2023-03-15 00:00:00 UTC を表すタイムスタンプ
4$newDateTimeImmutable = $dateTimeImmutable->setTimestamp($unixTimestamp);
5echo $newDateTimeImmutable->format('Y-m-d H:i:s');
6?>

int $timestamp

• int $timestamp: Unixタイムスタンプを表す整数

DateTimeImmutable|false

指定されたタイムスタンプを持つ新しい DateTimeImmutable オブジェクト、または失敗した場合は false を返します。