date_timestamp_set()

Purpose

date_timestamp_set() is the procedural form of DateTime::setTimestamp(). It takes an existing DateTime object and moves it to the instant described by a Unix timestamp, which is a count of seconds since 1970-01-01 00:00:00 UTC. The two forms behave the same way, so pick whichever matches the style of your code.

A typical use is turning a stored integer, such as a value from a cache entry or an API payload, back into a date object that you can format or compare.

Signature

Parameters

• $object: the DateTime object to modify. It is changed in place. There is no default value.
• $timestamp: the Unix timestamp as an integer number of seconds. There is no default value. Negative values describe moments before 1970.

Return value and failure cases

The function returns the same DateTime object that you passed in, now holding the new instant. Because it is the same object and not a copy, the return value is handy for chaining, but you do not need to assign it.

Passing something that is not a DateTime throws a TypeError. That includes DateTimeImmutable, which does not match the DateTime parameter type. Passing a non-integer timestamp follows the usual PHP type rules, so a non-numeric string also raises a TypeError.

Example 1: set a basic timestamp

The object starts in the year 2000. After the call it represents exactly one day after the epoch.

<?php
$date = new DateTime('2000-01-01 00:00:00', new DateTimeZone('UTC'));
date_timestamp_set($date, 86400);
echo $date->format('Y-m-d H:i:s T'), "\n";

1970-01-02 00:00:00 UTC

Example 2: the object is changed and returned

The returned value is identical to the argument. The timestamp read back with getTimestamp() matches the value you set.

<?php
$date = new DateTime('2024-01-01 00:00:00', new DateTimeZone('UTC'));
$result = date_timestamp_set($date, 1700000000);
echo json_encode([
    'same' => $result === $date,
    'iso' => $date->format('Y-m-d\TH:i:sP'),
    'timestamp' => $date->getTimestamp(),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"same":true,"iso":"2023-11-14T22:13:20+00:00","timestamp":1700000000}

Example 3: the time zone is kept

A timestamp identifies one instant, but the wall-clock text depends on the object's time zone. The function does not change the zone, so the same instant is displayed in the object's own zone.

<?php
$date = new DateTime('2020-05-05 12:00:00', new DateTimeZone('Asia/Tokyo'));
date_timestamp_set($date, 1700000000);
echo $date->format('Y-m-d H:i:s P e'), "\n";

2023-11-15 07:13:20 +09:00 Asia/Tokyo

Example 4: immutable objects are rejected

The procedural function accepts only DateTime. For DateTimeImmutable, call the setTimestamp() method instead, which returns a new object and leaves the original untouched.

<?php
$immutable = new DateTimeImmutable('2024-01-01 00:00:00', new DateTimeZone('UTC'));
try {
    date_timestamp_set($immutable, 0);
} catch (TypeError $e) {
    echo get_class($e), "\n";
}

TypeError

Edge cases

• Mutation affects every reference. Objects are handles in PHP, so if two variables point to the same DateTime, both see the change. Use clone first if you need to keep the old value.
• Zero and negative values. 0 is the epoch itself, and negative integers are valid dates before 1970.
• Whole seconds only. The parameter is an integer, so you cannot supply fractional seconds through this function.
• Display depends on the zone. The timestamp is zone-independent, but the formatted output is not. Compare timestamps when you want to compare instants, and set the zone explicitly when you print.

Common mistakes

1. Expecting a new object. Code that treats the function as non-destructive loses the original date. Clone the object if you need both.
2. Passing a DateTimeImmutable. This throws a TypeError. Use the method form, and keep the returned object because the original does not change.
3. Passing milliseconds. JavaScript and some APIs use milliseconds. Passing such a value here would give a date far in the future. Divide by 1000 and convert to an integer first.
4. Assuming the zone becomes UTC. The timestamp is interpreted as an instant, but the object keeps its own zone, so formatted output may differ from what you expect.
5. Parsing a date string with it. The function expects an integer. To build a timestamp from text, create the object from the string, or use strtotime() in a context where its behaviour is predictable.

Related functions

• date_timestamp_get(): read the timestamp from a DateTime object.
• DateTime::setTimestamp(): the method form that this function aliases.
• date_timezone_set(): change the zone used for display.
• date_create(): create a DateTime object procedurally.
• date_date_set() and date_time_set(): set calendar or clock fields instead of a timestamp.

Recap

date_timestamp_set() changes a DateTime object in place to a given Unix timestamp and returns that same object. It keeps the object's time zone, rejects non-DateTime objects with a TypeError, and works in whole seconds. Clone first when you need the original, and use the method form for DateTimeImmutable.