date_timestamp_set()

The PHP date_timestamp_set() Function

date_timestamp_set() sets the date and time of a DateTime object from a Unix timestamp — the number of seconds elapsed since January 1, 1970, 00:00:00 UTC (the "Unix epoch"). It overwrites whatever date the object held before, fixing it to the exact instant the timestamp represents.

This page covers the function's syntax, a working example, how it interacts with timezones (the part most people get wrong), the object-oriented DateTime::setTimestamp() equivalent, common use cases, and how it relates to other PHP date functions.

Syntax

date_timestamp_set(DateTime $object, int $timestamp): DateTime

• $object — a DateTime instance to modify.
• $timestamp — a Unix timestamp (seconds since the epoch). Pass a negative number for dates before 1970.
• Returns — the same DateTime object (so calls can be chained), now updated.

Because it mutates and returns the object you pass in, date_timestamp_set() is the procedural twin of the method DateTime::setTimestamp() — both do the same thing.

A basic example

This sets a DateTime object to January 1, 2022, 00:00:00 UTC, whose Unix timestamp is 1640995200:

We create a DateTime object, hand it to date_timestamp_set() along with the timestamp, and then format() the result. The original date the constructor produced (the current moment) is discarded.

A Unix timestamp always points to a moment in UTC — it carries no timezone of its own. If you need the timestamp for a given calendar date, use mktime(), strtotime(), or (new DateTime('2022-01-01'))->getTimestamp().

Timestamps are absolute — the timezone affects display only

A common misconception is that date_timestamp_set() "converts" a date between timezones. It does not change which instant the object points to; it only sets that instant. What changes between timezones is how format() renders it.

The same timestamp displayed in two different timezones:

<?php
$timestamp = 1640995200; // 2022-01-01 00:00:00 UTC

$nyc = new DateTime('now', new DateTimeZone('America/New_York'));
date_timestamp_set($nyc, $timestamp);

echo $nyc->format('Y-m-d H:i:s P'); // 2021-12-31 19:00:00 -05:00

The instant is identical, but New York is five hours behind UTC in January, so the wall-clock reading is the evening of December 31. Calling $nyc->getTimestamp() still returns 1640995200. To actually change the displayed timezone, set it explicitly with date_timezone_set().

Object-oriented equivalent

If you prefer method chaining, DateTime::setTimestamp() is identical in effect:

<?php
date_default_timezone_set('UTC');

$date = (new DateTime())->setTimestamp(1640995200);

echo $date->format('Y-m-d H:i:s'); // 2022-01-01 00:00:00

Both styles mutate the object in place and return it, so pick whichever reads better in your codebase.

Common use cases

• Restoring a stored time. Databases and APIs often store times as integer Unix timestamps. date_timestamp_set() rebuilds a DateTime from that integer so you can format or do arithmetic with it via date_add() and date_diff().
• Normalizing user input. Convert user-entered dates to a timestamp with strtotime(), then seed a DateTime from that single canonical value.
• Resetting an existing object. When you already have a configured DateTime (with a chosen timezone or formatting workflow) and just want to point it at a new instant without rebuilding it.

Related functions

• date_timestamp_get() — the inverse: read a DateTime's Unix timestamp.
• date_date_set() and date_time_set() — set the date or time by component instead of a timestamp.
• date_default_timezone_set() — control the timezone used when no DateTimeZone is supplied.

Conclusion

date_timestamp_set() sets a DateTime object to the exact moment described by a Unix timestamp, overwriting its previous value and returning the same object. Remember that the timestamp is always UTC-based and the timezone only changes how the result is displayed — not which instant it represents. For the reverse operation, reach for date_timestamp_get().

Practice