date_timestamp_set()

La función PHP date_timestamp_set()

date_timestamp_set() establece la fecha y hora de un objeto DateTime a partir de una marca de tiempo Unix — el número de segundos transcurridos desde el 1 de enero de 1970, 00:00:00 UTC (el "epoch Unix"). Sobreescribe cualquier fecha que el objeto tuviera anteriormente, fijándolo al instante exacto que representa la marca de tiempo.

Esta página cubre la sintaxis de la función, un ejemplo funcional, cómo interactúa con las zonas horarias (la parte que más confunde), el equivalente orientado a objetos DateTime::setTimestamp(), casos de uso comunes y cómo se relaciona con otras funciones de fecha de PHP.

Sintaxis

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

• $object — una instancia de DateTime a modificar.
• $timestamp — una marca de tiempo Unix (segundos desde el epoch). Pasa un número negativo para fechas anteriores a 1970.
• Retorna — el mismo objeto DateTime (para que las llamadas puedan encadenarse), ya actualizado.

Dado que muta y devuelve el objeto que se le pasa, date_timestamp_set() es el equivalente procedimental del método DateTime::setTimestamp() — ambos hacen lo mismo.

Un ejemplo básico

Esto establece un objeto DateTime al 1 de enero de 2022, 00:00:00 UTC, cuya marca de tiempo Unix es 1640995200:

Creamos un objeto DateTime, lo pasamos a date_timestamp_set() junto con la marca de tiempo, y luego formateamos el resultado con format(). La fecha original que produjo el constructor (el momento actual) se descarta.

Una marca de tiempo Unix siempre apunta a un momento en UTC — no lleva zona horaria propia. Si necesitas la marca de tiempo para una fecha de calendario determinada, usa mktime(), strtotime() o (new DateTime('2022-01-01'))->getTimestamp().

Las marcas de tiempo son absolutas — la zona horaria solo afecta a la visualización

Un error común es pensar que date_timestamp_set() "convierte" una fecha entre zonas horarias. No cambia el instante al que apunta el objeto; solo establece ese instante. Lo que varía entre zonas horarias es cómo format() lo muestra.

La misma marca de tiempo mostrada en dos zonas horarias distintas:

<?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

El instante es idéntico, pero Nueva York está cinco horas por detrás de UTC en enero, por lo que la lectura del reloj corresponde a la tarde del 31 de diciembre. Llamar a $nyc->getTimestamp() sigue devolviendo 1640995200. Para cambiar realmente la zona horaria mostrada, establécela explícitamente con date_timezone_set().

Equivalente orientado a objetos

Si prefieres el encadenamiento de métodos, DateTime::setTimestamp() tiene el mismo efecto:

<?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

Ambos estilos mutan el objeto en su lugar y lo devuelven, así que elige el que sea más legible en tu código.

Casos de uso comunes

• Restaurar una hora almacenada. Las bases de datos y las API suelen almacenar las horas como marcas de tiempo Unix enteras. date_timestamp_set() reconstruye un DateTime a partir de ese entero para que puedas formatearlo o hacer operaciones aritméticas con date_add() y date_diff().
• Normalizar la entrada del usuario. Convierte las fechas introducidas por el usuario a una marca de tiempo con strtotime(), y luego inicializa un DateTime a partir de ese único valor canónico.
• Restablecer un objeto existente. Cuando ya tienes un DateTime configurado (con una zona horaria o flujo de formato elegido) y solo quieres apuntarlo a un nuevo instante sin reconstruirlo.

Funciones relacionadas

• date_timestamp_get() — la operación inversa: lee la marca de tiempo Unix de un DateTime.
• date_date_set() y date_time_set() — establecen la fecha o la hora por componente en lugar de usar una marca de tiempo.
• date_default_timezone_set() — controla la zona horaria utilizada cuando no se proporciona ningún DateTimeZone.

Conclusión

date_timestamp_set() establece un objeto DateTime al instante exacto descrito por una marca de tiempo Unix, sobreescribiendo su valor anterior y devolviendo el mismo objeto. Recuerda que la marca de tiempo siempre está basada en UTC y que la zona horaria solo cambia cómo se muestra el resultado, no qué instante representa. Para la operación inversa, usa date_timestamp_get().

Práctica