frenchtojd()

Introdução

A função frenchtojd() do PHP converte uma data do calendário republicano francês em um Julian Day Count — um único inteiro que identifica univocamente um dia do calendário. Esta página explica o que esses dois termos significam, como chamar a função, o que seus valores de retorno significam e os casos extremos que costumam confundir as pessoas.

Um Julian Day Count (JDC) é a contagem contínua de dias desde o início do período Juliano: meio-dia UTC de 1º de janeiro de 4713 a.C. Por ser um inteiro simples, é o formato "pivô" comum que o PHP usa para converter entre calendários — você converte o calendário A para um dia Juliano, e depois converte esse dia Juliano para o calendário B. Ele também é amplamente utilizado em astronomia e em qualquer área que precise de medição de tempo contínua e independente de calendário.

O calendário republicano francês foi utilizado na França de 1793 a 1805, introduzido pela Revolução Francesa para substituir o calendário gregoriano. Ele tem 12 meses de 30 dias cada, divididos em três semanas de dez dias (décades), mais 5 ou 6 "dias complementares" extras no final do ano. Os anos são contados a partir da fundação da República (Ano I, Ano II, …), convencionalmente escritos com algarismos romanos.

Usando a Função Nativa frenchtojd() do PHP

Para converter uma data republicana francesa em um dia Juliano no PHP, chame a função nativa frenchtojd(). O PHP lida internamente com a matemática do calendário, portanto você não precisa implementar o algoritmo por conta própria.

Nota: Esta função exige que a extensão calendar esteja habilitada. Verifique com extension_loaded('calendar'); se retornar false, habilite a extensão no seu php.ini.

<?php

$jd = frenchtojd($month, $day, $year);

?>

A função aceita três parâmetros inteiros e retorna um int:

• $month: O número do mês (1–13). Os meses 1–12 são os meses regulares de 30 dias (Vendémiaire … Fructidor); o mês 13 contém os dias complementares.
• $day: O dia do mês (1–30 para os meses 1–12, 1–6 para o mês 13).
• $year: O ano da República Francesa, por exemplo, 1 para o Ano I.

O intervalo válido vai aproximadamente de 1 Vendémiaire do Ano 1 até o final do Ano 14. Qualquer data fora do intervalo suportado — incluindo frenchtojd(0, 0, 0) — retorna 0. Sempre verifique se o resultado é 0 antes de usar o valor.

Exemplo de Uso

Passe o mês, o dia e o ano da data francesa como parâmetros:

<?php

$jd = frenchtojd(12, 22, 1);
echo $jd; // Output: 2376191

?>

Aqui convertemos 22 Fructidor, Ano I (mês 12, dia 22, ano 1) para seu Julian Day Count, 2376191. Esse dia Juliano corresponde a 8 de setembro de 1793 no calendário gregoriano.

Conversão para Outros Calendários

Como o resultado é um dia Juliano, você pode passá-lo para qualquer função jdto*() para expressar o mesmo dia em outro calendário. Esse é o motivo mais comum para chamar frenchtojd():

<?php

$jd = frenchtojd(12, 22, 1);     // 22 Fructidor, Year I → 2376191

echo jdtogregorian($jd), "\n";   // Output: 9/8/1793
echo jddayofweek($jd, 1), "\n";  // Output: Sunday

?>

Para converter no sentido inverso, use jdtofrench(), o inverso de frenchtojd().

Armadilhas Comuns

• A ordem dos argumentos é month, day, year — não a ordem dia-mês-ano usada nas datas francesas do dia a dia. Trocar os dois primeiros é o erro mais frequente.
• Um retorno 0 significa "inválido ou fora do intervalo", não "um erro foi lançado." A função não lança uma exceção, portanto valide o resultado você mesmo.
• Os dias complementares ficam no mês 13, não acrescentados ao mês 12. Use frenchtojd(13, 1, $year) a frenchtojd(13, 6, $year) para eles.
• A extensão calendar nem sempre está habilitada, especialmente em imagens Docker mínimas. Proteja com extension_loaded('calendar') em código portátil.

Funções Relacionadas

• jdtofrench() — o inverso: dia Juliano → data do calendário republicano francês.
• gregoriantojd() — converte uma data gregoriana em um dia Juliano.
• juliantojd() — converte uma data do calendário Juliano (proléptico) em um dia Juliano.
• jddayofweek() — obtém o dia da semana para um dia Juliano.

Conclusão

frenchtojd() torna a conversão de datas republicanas francesas em dias Julianos uma única chamada de função. Lembre-se da ordem de argumentos month, day, year, trate um retorno 0 como "fora do intervalo" e use o dia Juliano resultante como ponte para outros calendários por meio da família jdto*().

Prática