Timestamps Epoch Explicados: Como o Tempo Unix Funciona (e Por Que Quebra)

Um timestamp epoch — também chamado de tempo Unix ou tempo POSIX — é o número de segundos que decorreram desde 1 de janeiro de 1970 00:00:00 UTC, excluindo segundos bissextos. É um número inteiro simples que representa um momento preciso no tempo, independente de fusos horários e sistemas de calendário. Esta simplicidade torna-o a forma padrão de os computadores trocarem informações de tempo, mas também tem limitações e armadilhas conhecidas que todo desenvolvedor deve compreender.

Como o Tempo Unix Funciona

O tempo Unix conta a partir da epoch. Um dia equivale a 86.400 segundos (24 × 60 × 60). O timestamp aumenta exatamente um por segundo, independentemente do fuso horário, horário de verão ou anos bissextos.

Timestamp 0        → 1970-01-01 00:00:00 UTC
Timestamp 86400    → 1970-01-02 00:00:00 UTC
Timestamp 1000000  → 1970-01-12 13:46:40 UTC
Timestamp 1782000000 → 2026-06-17 00:00:00 UTC

// JavaScript — obter timestamp Unix atual
const nowInSeconds = Math.floor(Date.now() / 1000);
console.log(nowInSeconds);

// Converter timestamp para data
const date = new Date(nowInSeconds * 1000);
console.log(date.toISOString());

// PHP — obter timestamp Unix atual
echo time();             // segundos desde a epoch
echo microtime(true);    // segundos com precisão de microssegundos

// Converter timestamp para data
echo date('Y-m-d H:i:s', 1782000000);

Segundos vs Milissegundos: Uma Fonte Comum de Erros

Um dos erros mais frequentes relacionados a timestamps é confundir segundos com milissegundos. O Date.now() do JavaScript retorna milissegundos, enquanto o time() do PHP retorna segundos. Muitas bases de dados armazenam timestamps em segundos, e muitas APIs usam milissegundos.

// ❌ Errado — tratando milissegundos como segundos
const timestamp = 1782000000; // isto está em segundos
const wrongDate = new Date(timestamp); // interpreta como milissegundos
console.log(wrongDate.toISOString()); // 1970-01-21 — completamente errado

// ✅ Correto — multiplicar por 1000
const correctDate = new Date(timestamp * 1000);
console.log(correctDate.toISOString()); // 2026-06-17

import time
from datetime import datetime

# ❌ Errado — esquecer de dividir milissegundos
millis = 1782000000000
wrong = datetime.fromtimestamp(millis)  # ValueError: year out of range

# ✅ Correto
correct = datetime.fromtimestamp(millis / 1000)
print(correct)  # 2026-06-17 00:00:00

O Problema do Ano 2038

O tempo Unix usa um inteiro signed de 32 bits, que tem um valor máximo de 2.147.483.647. Em 19 de janeiro de 2038 às 03:14:07 UTC, o timestamp atingirá este limite. Um segundo depois, um inteiro signed de 32 bits passa para −2.147.483.648, que corresponde a 13 de dezembro de 1901.

2.147.483.647 → 2038-01-19 03:14:07 UTC (máx. 32-bit signed)
2.147.483.648 → wraps para negativo (underflow)

Sistemas ainda vulneráveis ao Y2038:

• Sistemas embarcados (roteadores, dispositivos IoT, firmware de automóveis)
• Bases de dados legadas que armazenam timestamps como INT(10)
• Kernels Linux antigos em arquiteturas de 32 bits
• Sistemas de ficheiros que usam timestamps de 32 bits
• Versões antigas do PHP em builds de 32 bits

Como verificar se um sistema é seguro para Y2038:

# Linux — verificar se time_t é 64-bit
getconf LONG_BIT
# 64 → seguro
# 32 → verificar versão do kernel e libc

# PHP — verificar tamanho do inteiro
php -r 'echo PHP_INT_SIZE;'
# 8 → seguro (64-bit)
# 4 → vulnerável (32-bit)

Os sistemas modernos com time_t de 64 bits podem representar timestamps até cerca de 292 mil milhões de anos no futuro, tornando o Y2038 um não-problema. A maioria dos servidores de produção já executa sistemas operativos de 64 bits, mas sistemas embarcados e legados permanecem em risco.

Segundos Bissextos: A Complexidade Oculta

O tempo Unix ignora segundos bissextos. Por definição, cada dia tem exatamente 86.400 segundos. Mas o tempo astronómico (UT1) ocasionalmente requer um segundo extra — um segundo bissexto — para permanecer alinhado com a rotação da Terra. Quando ocorre um segundo bissexto, o tempo Unix repete o mesmo segundo:

2016-12-31 23:59:59 UTC
2016-12-31 23:59:60 UTC  ← segundo bissexto (não representável em tempo Unix)
2017-01-01 00:00:00 UTC

A maioria das aplicações ignora segundos bissextos porque ocorrem de forma imprevisível (tipicamente uma vez a cada 1-3 anos) e lidar com eles adiciona complexidade significativa. Sistemas que exigem precisão temporal — como plataformas de negociação financeira e observatórios astronómicos — usam TAI (Tempo Atómico Internacional) ou tempo GPS em vez de tempo Unix.

Armadilhas Comuns

Armadilha 1: Usar a Unidade Errada

// API retorna timestamp em segundos
const apiTimestamp = 1782000000;

// ❌ Errado — new Date() espera milissegundos
const date = new Date(apiTimestamp);

// ✅ Correto
const date = new Date(apiTimestamp * 1000);

Armadilha 2: Armazenar como INT(10) no MySQL

-- ❌ Errado — INT(10) transborda aos 2,1 mil milhões (2038)
CREATE TABLE events (
    created_at INT(10) NOT NULL
);

-- ✅ Correto — usar BIGINT ou TIMESTAMP
CREATE TABLE events (
    created_at BIGINT NOT NULL,       -- 64-bit, seguro
    created_at2 TIMESTAMP NOT NULL     -- MySQL trata a conversão
);

Armadilha 3: Assumir que a Hora Local é o Padrão

// ❌ Errado — date() usa o fuso horário padrão do servidor
echo date('Y-m-d H:i:s', $timestamp);

// ✅ Correto — especificar explicitamente UTC
echo gmdate('Y-m-d H:i:s', $timestamp);
echo date('Y-m-d H:i:s', $timestamp); // se o TZ padrão estiver definido para UTC

Armadilha 4: Overflow de Inteiros em JavaScript

Os números em JavaScript são ponto flutuante de 64 bits, mas as operações bitwise tratam-nos como inteiros signed de 32 bits. Isto pode causar erros inesperados semelhantes ao Y2038 mesmo em navegadores modernos.

// Operação bitwise em JavaScript trata como 32-bit
const timestamp = 2500000000; // além do máximo signed de 32 bits
const shifted = timestamp << 1; // ❌ overflow!
console.log(shifted); // -1794967296 (wrap)

Ferramenta Conversor de Epoch

O Epoch / Unix Timestamp Converter no Help2Code fornece visualização ao vivo do timestamp atual em segundos e milissegundos, conversão bidirecional entre valores epoch e datas legíveis, e suporte para fusos horários local e UTC. Use-o para depurar problemas de timestamp, gerar timestamps para testes ou verificar respostas de API. O Timezone Converter também é útil para verificar como timestamps epoch mapeiam para diferentes fusos horários.

Conclusão

Timestamps epoch são uma forma simples e universal de representar momentos no tempo, mas apresentam algumas ressalvas críticas: verifique sempre se está a trabalhar com segundos ou milissegundos, use armazenamento de 64 bits para evitar o problema Y2038 e nunca assuma que o fuso horário padrão corresponde à sua intenção. Use o Epoch Converter para conversões rápidas e mantenha as diretrizes acima em mente ao lidar com timestamps em código de produção.