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

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

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

基本的な使い方

setTimestampメソッドは、DateTimeオブジェクトのタイムスタンプを設定するメソッドです。このメソッドは、既存のDateTimeインスタンスが表す日時を、指定されたUnixタイムスタンプに基づいて変更するために使用されます。Unixタイムスタンプとは、1970年1月1日00:00:00 UTC（協定世界時）からの経過秒数を整数で表したもので、日付と時刻を数値として一意に識別する際に広く利用されています。

setTimestampメソッドは、必須の引数として一つの整数値（Unixタイムスタンプ）を受け取ります。この整数値をDateTimeオブジェクトに適用することで、そのオブジェクトの日付、時刻、およびタイムゾーンが指定されたタイムスタンプに対応する値に更新されます。例えば、データベースから取得した日付がUnixタイムスタンプ形式である場合、このメソッドを使用することで、そのタイムスタンプ値を既存のDateTimeオブジェクトに設定し、その後、日付の書式設定や計算といったDateTimeオブジェクトの豊富な機能を利用できるようになります。

メソッドが正常に実行された場合、変更が適用されたDateTimeオブジェクト自身が返されます。これにより、メソッドチェーンを用いて、タイムスタンプ設定後に続けて他のDateTime操作を行うことが可能です。このメソッドは、新しいDateTimeオブジェクトを作成することなく、既存のオブジェクトの内部状態を効率的に更新したい場合に特に有効です。

構文(syntax)


1<?php
2
3// DateTimeオブジェクトを生成します。
4$date = new DateTime();
5
6// オブジェクトの日時を設定したいUNIXタイムスタンプ（整数値）を用意します。
7// 例: 1672531200 は 2023-01-01 00:00:00 UTC を表します。
8$unixTimestamp = 1672531200;
9
10// setTimestamp()メソッドを呼び出し、引数にタイムスタンプを渡します。
11// これにより、$dateオブジェクトの日時が指定したタイムスタンプの値に更新されます。
12$date->setTimestamp($unixTimestamp);
13
14// 更新された日時を確認します。
15// 出力される日時は、スクリプトのデフォルトタイムゾーンに変換されます。
16echo $date->format('Y-m-d H:i:s');
17
18?>

引数(parameters)

int $timestamp

int $timestamp: Unixタイムスタンプを指定する整数

戻り値(return)

DateTime

このメソッドは、Unixタイムスタンプを指定してDateTimeオブジェクトの時刻を設定し、変更されたDateTimeオブジェクト自身を返します。

サンプルコード

PHP DateTime::setTimestampで時刻を設定する


1<?php
2
3/**
4 * DateTime::setTimestamp() メソッドの使用例を示します。
5 *
6 * このメソッドは、DateTime オブジェクトの内部タイムスタンプを
7 * 指定されたUNIXタイムスタンプ（1970年1月1日00:00:00 UTCからの秒数）に設定します。
8 */
9function exampleSetTimestamp(): void
10{
11    // 1. 新しい DateTime オブジェクトを作成します。
12    //    初期時刻は、スクリプト実行時の現在の時刻です。
13    $dateTime = new DateTime();
14    echo "初期時刻: " . $dateTime->format('Y-m-d H:i:s e') . PHP_EOL;
15
16    // 2. 設定したいUNIXタイムスタンプを準備します。
17    //    例: 2023年1月1日 12:00:00 UTC のUNIXタイムスタンプ (整数)
18    $targetUnixTimestamp = 1672574400; // 2023-01-01 12:00:00 UTC
19
20    echo "設定するUNIXタイムスタンプ: " . $targetUnixTimestamp . PHP_EOL;
21
22    // 3. setTimestamp() メソッドを使って、DateTime オブジェクトの時刻を設定します。
23    //    このメソッドは、設定された DateTime オブジェクト自身を返します。
24    $dateTime->setTimestamp($targetUnixTimestamp);
25
26    // 4. 設定後の時刻を表示して確認します。
27    //    DateTime オブジェクトのタイムゾーン設定に基づき、表示時刻が変換されます。
28    //    'e' はタイムゾーン識別子を表示します。
29    echo "setTimestamp() 適用後: " . $dateTime->format('Y-m-d H:i:s e') . PHP_EOL;
30
31    echo PHP_EOL;
32
33    // 補足: 現在のUNIXタイムスタンプを設定する例
34    // time() 関数は、現在のUNIXタイムスタンプを返します。
35    echo "現在のUNIXタイムスタンプ: " . time() . PHP_EOL;
36    $dateTime->setTimestamp(time());
37    echo "現在のUNIXタイムスタンプ設定後: " . $dateTime->format('Y-m-d H:i:s e') . PHP_EOL;
38}
39
40// 関数を実行します
41exampleSetTimestamp();

PHP 8のDateTimeクラスに属するsetTimestamp()メソッドは、日付と時刻を扱うDateTimeオブジェクトの時刻を、指定したUNIXタイムスタンプに基づいて設定するために使用されます。UNIXタイムスタンプとは、1970年1月1日00:00:00 UTC（協定世界時）からの経過秒数を整数で表したものです。

このメソッドの引数int $timestampには、設定したい日付と時刻に対応するUNIXタイムスタンプを整数で渡します。メソッドを実行すると、呼び出し元のDateTimeオブジェクトの内部時刻が、このUNIXタイムスタンプに正確に設定されます。

戻り値はDateTime型で、時刻が設定されたDateTimeオブジェクト自身が返されます。これにより、メソッドチェーンを使って続けて他の操作を行うことも可能です。サンプルコードでは、まずDateTimeオブジェクトを初期化し、特定のUNIXタイムスタンプ1672574400（2023年1月1日 12:00:00 UTC）を使って時刻を設定しています。現在のUNIXタイムスタンプであるtime()関数の結果を設定する例も示されており、これによりDateTimeオブジェクトの時刻を簡単に更新できることがわかります。このメソッドは、UNIXタイムスタンプを基準とした日付時刻の操作において非常に便利です。

setTimestamp() メソッドの引数はUNIXタイムスタンプであり、これは1970年1月1日00:00:00 UTCからの秒数を整数で指定します。このメソッドは、呼び出し元の DateTime オブジェクトの内部時刻を直接変更しますので、元の日時が上書きされる点にご注意ください。

設定されたUNIXタイムスタンプはUTC基準ですが、DateTime オブジェクトの現在のタイムゾーン設定に基づいて表示時刻が変換されます。そのため、期待するタイムゾーンで表示されているか format('Y-m-d H:i:s e') などで常に確認することが重要です。無効なタイムスタンプ（例えば極端に大きな値や負の値）を渡すと、PHP 8では ValueError が発生する可能性がありますので、入力値の妥当性を確認することをお勧めします。