unixtojd()

Convertendo um Timestamp Unix em um Dia Juliano no PHP

A função unixtojd() do PHP converte um timestamp Unix em uma contagem do Dia Juliano — um único inteiro que conta o número de dias desde o início do Período Juliano (1º de janeiro de 4713 a.C. no calendário juliano proléptico). Esta página explica o que a função retorna, como chamá-la, os casos em que ela difere da sua intuição e como converter de volta.

Um timestamp Unix é o número de segundos decorridos desde 1º de janeiro de 1970, 00:00:00 UTC. Um Número do Dia Juliano (JDN) é uma contagem contínua de dias amplamente utilizada em astronomia e em cálculos de calendário, pois a diferença entre dois Dias Julianos é simplesmente o número de dias entre eles — sem necessidade de aritmética de meses ou anos bissextos. Observe que o "Dia Juliano" aqui não é o mesmo que uma data no calendário juliano histórico; é uma contagem sequencial de dias.

Como unixtojd() Funciona

unixtojd() recebe o número inteiro de segundos em um timestamp Unix, divide-o em dias inteiros e adiciona o Número do Dia Juliano da época Unix (1970-01-01), que é 2440588. A conversão é feita em UTC e o resultado tem granularidade de dia — as horas, minutos e segundos do timestamp são descartados, de modo que cada momento dentro do mesmo dia UTC é mapeado para o mesmo Dia Juliano.

unixtojd() faz parte da extensão Calendar do PHP. Ela é compilada por padrão na maioria das instalações, mas em uma instalação mínima do PHP pode ser necessário habilitar a extensão calendar antes que a função esteja disponível.

Sintaxe

unixtojd(?int $timestamp = null): int|false

• $timestamp — O timestamp Unix a ser convertido. Se omitido (ou null), o tempo atual é utilizado, exatamente como se você tivesse passado time().
• Retorna um inteiro com o Número do Dia Juliano, ou false se o timestamp não puder ser convertido.

Exemplo Básico

Converta o timestamp Unix atual em um Dia Juliano:

Isso imprime o timestamp Unix atual e o Número do Dia Juliano correspondente.

Pontos de Referência Conhecidos

Como a conversão é fixa, alguns timestamps sempre produzem o mesmo Dia Juliano. Estes são úteis para verificar a sanidade do seu código:

<?php

echo unixtojd(0), "\n";                          // 2440588  -> 1970-01-01 (the Unix epoch)
echo unixtojd(mktime(0, 0, 0, 1, 1, 2000)), "\n"; // 2451545  -> 2000-01-01
echo unixtojd(mktime(0, 0, 0, 7, 4, 2025)), "\n"; // 2460861  -> 2025-07-04

Chamando Sem Argumento

Passar nenhum argumento é equivalente a passar time(), então ambas as linhas abaixo retornam o mesmo valor:

<?php

echo unixtojd(), "\n";        // current day, no timestamp needed
echo unixtojd(time()), "\n";  // identical result

Convertendo de Volta: jdtounix()

O inverso de unixtojd() é jdtounix(), que transforma um Número do Dia Juliano de volta em um timestamp Unix definido para meia-noite UTC daquele dia. Como unixtojd() descarta a parte do horário, uma ida e volta resulta no início do dia em vez do momento original:

<?php

$start = mktime(15, 30, 0, 7, 4, 2025); // 2025-07-04 15:30:00
$jd    = unixtojd($start);
$back  = jdtounix($jd);

echo "Original: ", gmdate("Y-m-d H:i:s", $start), " UTC\n"; // 2025-07-04 15:30:00 UTC
echo "Back:     ", gmdate("Y-m-d H:i:s", $back),  " UTC\n"; // 2025-07-04 00:00:00 UTC

Quando Usar Isso?

Os Números do Dia Juliano são úteis sempre que você precisa contar dias inteiros entre duas datas sem as complicações de comprimentos de meses e anos bissextos: cálculos astronômicos, lógica de agendamento, contadores de "dias restantes" e interoperação com conjuntos de dados científicos que armazenam datas como Dias Julianos. Para formatação e aritmética de datas comuns, a API DateTime e as funções de data geralmente são a melhor opção.

Conclusão

unixtojd() converte um timestamp Unix em um Número do Dia Juliano — uma contagem de dias em nível UTC com raiz no valor da época 2440588. Ela usa o tempo atual quando chamada sem argumento, ignora a parte do horário e é revertida por jdtounix(). Combine-a com mktime() e time() para converter qualquer momento em um Dia Juliano para cálculos baseados em dias.

Prática