date_timestamp_get()

Introdução

Funções de data e hora são uma parte fundamental das linguagens de programação. Em PHP, os desenvolvedores frequentemente precisam recuperar a data e hora atuais ou realizar operações sobre datas e horas. A função date_timestamp_get() é uma dessas funções, utilizada para extrair o timestamp Unix de um objeto DateTime. Neste artigo, exploraremos a função date_timestamp_get() em detalhes e entenderemos como ela funciona.

Entendendo o date_timestamp_get()

A função date_timestamp_get() é uma função interna do PHP que extrai o timestamp Unix de um objeto DateTime. Um timestamp Unix é um único número que representa um momento no tempo: a contagem de segundos decorridos desde 1º de janeiro de 1970, 00:00:00 UTC (o "Unix epoch").

Um timestamp é sempre um número baseado em UTC. O fuso horário do objeto DateTime de entrada é usado para calcular o valor, mas o timestamp em si não armazena fuso horário — dois objetos DateTime que descrevem o mesmo instante em fusos horários diferentes retornam o mesmo timestamp.

Sintaxe

date_timestamp_get(DateTimeInterface $object): int

• $object — uma instância de DateTime ou DateTimeImmutable (qualquer coisa que implemente DateTimeInterface). Passar null ou um não-objeto gera um TypeError no PHP 8+.
• Valor de retorno — um int, o timestamp Unix em segundos. (Microssegundos fracionários são descartados; use $date->format('U.u') se precisar deles.)

O objeto DateTime pode ser criado com a função date_create() ou o construtor da classe DateTime. date_timestamp_get($date) é o alias procedural da chamada de método $date->getTimestamp().

Exemplo básico

Criamos um objeto DateTime a partir de uma string de data, passamos para date_timestamp_get() e imprimimos o timestamp Unix retornado. Para código moderno orientado a objetos, a forma equivalente (e geralmente preferida) é $date->getTimestamp().

O fuso horário afeta o resultado

Como um timestamp é um instante UTC absoluto, a mesma string de horário local produz um timestamp diferente dependendo do fuso horário do objeto:

<?php
$utc = new DateTime('2023-03-03 10:30:00', new DateTimeZone('UTC'));
$tokyo = new DateTime('2023-03-03 10:30:00', new DateTimeZone('Asia/Tokyo'));

echo date_timestamp_get($utc);   // 1677839400
echo "\n";
echo date_timestamp_get($tokyo); // 1677807000 (32400s = 9h earlier in UTC)

10:30 em Tóquio acontece 9 horas antes de 10:30 em UTC, então seu timestamp é 32400 segundos menor. Veja date_default_timezone_set() para controlar o fuso horário padrão.

Usando o timestamp em cálculos

O real valor de um timestamp é aritmético — uma vez que uma data é um inteiro simples, você pode subtrair, comparar e convertê-la livremente:

<?php
$start = date_timestamp_get(date_create('2023-03-03 10:30:00'));
$end   = date_timestamp_get(date_create('2023-03-03 12:00:00'));

$diffSeconds = $end - $start;
echo $diffSeconds / 60 . " minutes elapsed"; // 90 minutes elapsed

Para converter um timestamp de volta em uma string formatada, passe-o para date(), ou construa um novo objeto com setTimestamp(). Para diferenças mais ricas entre datas (anos, meses, dias), prefira date_diff().

Casos de uso comuns e armadilhas

• Armazenar datas em um banco de dados como inteiro mantém as consultas de ordenação e intervalo rápidas e independentes de fuso horário.
• Comparar dois momentos é uma simples comparação de inteiros quando ambos são timestamps.
• Armadilha — float vs int: o tipo de retorno é int. Se você precisar de precisão em microssegundos (definida via construtor ou date_create() com segundo fracionário), getTimestamp() o trunca; use format('U.u') em vez disso.
• Armadilha — datas anteriores a 1970 produzem timestamps negativos, o que é válido, mas surpreende código que assume um número positivo.
• Operação inversa: para definir o horário de um objeto a partir de um timestamp, use date_timestamp_set().

Conclusão

date_timestamp_get() oferece aos desenvolvedores PHP uma maneira simples e precisa de reduzir um objeto DateTime a um único timestamp Unix UTC — ideal para armazenamento, comparação e aritmética. Para código orientado a objetos do dia a dia, use $date->getTimestamp(); os dois são intercambiáveis.

Prática