date_timestamp_set()

A função PHP date_timestamp_set()

date_timestamp_set() define a data e a hora de um objeto DateTime a partir de um timestamp Unix — o número de segundos decorridos desde 1º de janeiro de 1970, 00:00:00 UTC (a "época Unix"). Ela substitui qualquer data que o objeto continha anteriormente, fixando-o no instante exato que o timestamp representa.

Esta página aborda a sintaxe da função, um exemplo prático, como ela interage com fusos horários (a parte em que a maioria das pessoas erra), o equivalente orientado a objetos DateTime::setTimestamp(), casos de uso comuns e como ela se relaciona com outras funções de data do PHP.

Sintaxe

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

• $object — uma instância de DateTime a ser modificada.
• $timestamp — um timestamp Unix (segundos desde a época). Passe um número negativo para datas anteriores a 1970.
• Retorna — o mesmo objeto DateTime (para que as chamadas possam ser encadeadas), agora atualizado.

Por ser uma função que modifica e retorna o objeto passado, date_timestamp_set() é o equivalente procedural do método DateTime::setTimestamp() — ambos fazem a mesma coisa.

Um exemplo básico

Este exemplo define um objeto DateTime para 1º de janeiro de 2022, 00:00:00 UTC, cujo timestamp Unix é 1640995200:

Criamos um objeto DateTime, passamos para date_timestamp_set() junto com o timestamp e, em seguida, formatamos o resultado com format(). A data original produzida pelo construtor (o momento atual) é descartada.

Um timestamp Unix sempre aponta para um momento em UTC — ele não carrega fuso horário próprio. Se você precisar do timestamp para uma determinada data no calendário, use mktime(), strtotime() ou (new DateTime('2022-01-01'))->getTimestamp().

Timestamps são absolutos — o fuso horário afeta apenas a exibição

Um equívoco comum é achar que date_timestamp_set() "converte" uma data entre fusos horários. A função não muda qual instante o objeto aponta; ela apenas define esse instante. O que muda entre fusos horários é como format() renderiza esse instante.

O mesmo timestamp exibido em dois fusos horários diferentes:

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

O instante é idêntico, mas Nova York está cinco horas atrás do UTC em janeiro, portanto o horário local exibido é a noite de 31 de dezembro. Chamar $nyc->getTimestamp() ainda retorna 1640995200. Para realmente alterar o fuso horário exibido, defina-o explicitamente com date_timezone_set().

Equivalente orientado a objetos

Se você preferir encadeamento de métodos, DateTime::setTimestamp() é idêntico em efeito:

<?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 os estilos modificam o objeto no lugar e o retornam, então escolha o que for mais legível na sua base de código.

Casos de uso comuns

• Restaurar um horário armazenado. Bancos de dados e APIs frequentemente armazenam horários como timestamps Unix inteiros. date_timestamp_set() reconstrói um DateTime a partir desse inteiro para que você possa formatá-lo ou fazer operações aritméticas com ele via date_add() e date_diff().
• Normalizar entrada do usuário. Converta datas inseridas pelo usuário em um timestamp com strtotime() e, em seguida, inicialize um DateTime a partir desse único valor canônico.
• Redefinir um objeto existente. Quando você já tem um DateTime configurado (com um fuso horário escolhido ou fluxo de formatação) e quer apenas apontá-lo para um novo instante sem recriá-lo.

Funções relacionadas

• date_timestamp_get() — o inverso: lê o timestamp Unix de um DateTime.
• date_date_set() e date_time_set() — definem a data ou a hora por componente em vez de um timestamp.
• date_default_timezone_set() — controla o fuso horário usado quando nenhum DateTimeZone é fornecido.

Conclusão

date_timestamp_set() define um objeto DateTime para o instante exato descrito por um timestamp Unix, substituindo seu valor anterior e retornando o mesmo objeto. Lembre-se de que o timestamp é sempre baseado em UTC e que o fuso horário altera apenas como o resultado é exibido — não qual instante ele representa. Para a operação inversa, use date_timestamp_get().

Prática