PHP jdtounix() — Converter um Dia Juliano em Timestamp Unix

A função jdtounix() converte uma Contagem de Dias Julianos em um timestamp Unix. Ela faz parte da extensão de calendário do PHP e é a ponte entre a aritmética de datas no estilo calendário (que trabalha com dias inteiros) e o tempo baseado em segundos utilizado pelas demais funções de data do PHP.

Esta página explica o que são esses dois sistemas de numeração, demonstra jdtounix() em ação, aborda seu intervalo válido e armadilhas, e encerra com as conversões de timestamp Unix mais usadas no dia a dia (date() e strtotime()).

Duas formas de contar o tempo

Antes de usar jdtounix(), é útil entender exatamente o que ela converte.

Um timestamp Unix é o número de segundos decorridos desde 1970-01-01 00:00:00 UTC (o "Unix epoch"). É o padrão utilizado em todo o PHP — time(), date(), strtotime() e DateTime trabalham todos com timestamps Unix.

Uma Contagem de Dias Julianos (JDC) é o número de dias inteiros decorridos desde o meio-dia de 1º de janeiro de 4713 a.C. (no calendário juliano proléptico). Astrônomos e bibliotecas de calendário a utilizam porque ela atribui um único inteiro a cada dia, tornando trivial a contagem de dias entre datas em diferentes sistemas de calendário. As funções gregoriantojd(), jdtogregorian() e similares do PHP produzem e consomem essas contagens.

jdtounix() traduz uma JDC para o timestamp Unix equivalente à meia-noite UTC daquele dia.

Sintaxe

jdtounix(int $julian_day): int

• $julian_day — a Contagem de Dias Julianos a converter.
• Retorna o timestamp Unix correspondente. O dia deve estar dentro do intervalo suportado; um valor fora do intervalo lança um ValueError no PHP 8.0+ (versões anteriores retornavam false).

Exemplo básico

Raramente se tem um número de Dia Juliano à mão, portanto o fluxo habitual é: converter uma data gregoriana em JDC com gregoriantojd(), e então passar o resultado para jdtounix().

<?php

// Build the Julian Day Count for 15 February 2022 (month, day, year).
$jd = gregoriantojd(2, 15, 2022);
echo $jd, "\n";                       // 2459626

// Convert that day to a Unix timestamp (midnight UTC).
$timestamp = jdtounix($jd);
echo $timestamp, "\n";                // 1644883200

// Confirm by formatting it back to a readable date.
echo gmdate('Y-m-d H:i:s', $timestamp); // 2022-02-15 00:00:00

Como um Dia Juliano representa um dia inteiro e não um momento específico, jdtounix() sempre retorna o timestamp para 00:00:00 UTC daquele dia. A informação de hora simplesmente não faz parte da entrada.

Intervalo válido

jdtounix() funciona apenas dentro da janela do Unix epoch. O dia mais baixo aceito é 1970-01-01, que corresponde ao timestamp 0:

<?php

// 1 January 1970 is the lowest day jdtounix() can represent.
var_dump(jdtounix(gregoriantojd(1, 1, 1970))); // int(0)

Passar um dia anterior ao epoch é um erro: no PHP 8.0 e versões mais recentes, lança um ValueError, enquanto o PHP 7 retornava false. Se o dia de entrada for fornecido pelo usuário, valide o intervalo (ou envolva a chamada em um bloco try/catch) antes de confiar no resultado. Em sistemas onde os timestamps são armazenados como inteiros de 32 bits com sinal, o limite superior prático é o ano 2038.

A função inversa é unixtojd(), que converte um timestamp Unix de volta em uma Contagem de Dias Julianos.

Converter um timestamp Unix em data legível

Tendo um timestamp — proveniente de jdtounix(), time() ou de um banco de dados — você o formata para leitura humana com a função date(). Ela recebe uma string de formato e um timestamp:

As barras invertidas em \a\t escapam as letras a e t para que sejam impressas literalmente, em vez de serem interpretadas como caracteres de formato. Alguns dos caracteres de formato mais comuns são:

• Y — ano com quatro dígitos
• m — mês com zeros à esquerda (01–12)
• M — abreviação do mês (Jan–Dec)
• d — dia do mês com zeros à esquerda (01–31)
• D — abreviação do dia da semana (Sun–Sat)
• g — hora no formato de 12 horas, sem zero à esquerda (1–12)
• H — hora no formato de 24 horas com zeros à esquerda (00–23)
• i — minutos com zeros à esquerda (00–59)
• s — segundos com zeros à esquerda (00–59)
• a — am/pm em minúsculas

Uma observação sobre fusos horários

O PHP formata cada timestamp em relação ao fuso horário padrão do script, portanto o mesmo timestamp pode ser exibido como horários diferentes em servidores distintos. Defina o fuso horário explicitamente no início do script — com date_default_timezone_set() como acima — para que os resultados sejam reproduzíveis em qualquer ambiente. Os exemplos desta página utilizam UTC.

Converter uma data legível em timestamp Unix

No sentido inverso, strtotime() analisa uma descrição de data em inglês e retorna um timestamp Unix:

<?php

date_default_timezone_set('UTC');

$timestamp = strtotime('February 15, 2022 6:17 pm');
echo $timestamp; // 1644949020

strtotime() compreende muitos formatos — 2022-02-15, next Friday, +1 week — mas é rigorosa com a redação. Palavras de preenchimento como at não são permitidas: strtotime('February 15, 2022 at 6:17 pm') retorna false. Quando a análise falha, strtotime() retorna false, portanto valide o resultado antes de utilizá-lo.

Quando usar jdtounix()?

Para o trabalho cotidiano de "armazenar e exibir uma data", use date(), strtotime() e DateTime — eles lidam diretamente com datas e horários reais do calendário. Use jdtounix() (com gregoriantojd()) quando já estiver trabalhando com números de Dias Julianos, por exemplo ao integrar dados astronômicos, interoperar com outro sistema de calendário ou contar dias inteiros entre datas e depois precisar de um timestamp padrão de volta.

Conversão em resumo

graph LR;
    A[Gregorian date] -->|gregoriantojd| B[Julian Day Count];
    B -->|jdtounix| C[Unix timestamp];
    C -->|unixtojd| B;
    C -->|date| D[Readable string];

Conclusão

jdtounix() converte uma Contagem de Dias Julianos no timestamp Unix para a meia-noite UTC daquele dia, retornando false para dias fora do intervalo do epoch. Combina naturalmente com gregoriantojd() na entrada e unixtojd() para o caminho inverso. Para o tratamento comum de datas, o conjunto de ferramentas mais amplo em PHP Date and Time — especialmente date() e strtotime() — é o que você utilizará com maior frequência.

Prática