jddayofweek()

A função jddayofweek() do PHP retorna o dia da semana para um determinado número de dia juliano. Esta página explica o que é um número de dia juliano, o valor exato que cada mode retorna (a parte que mais confunde as pessoas) e um exemplo executável e verificado.

O que é um Número de Dia Juliano?

Um número de dia juliano (JDN) é um único inteiro que conta o número de dias decorridos desde o meio-dia de 1 de janeiro de 4713 a.C. (a época do período juliano). Por ser apenas um contador contínuo, sem meses, anos ou regras de calendário, ele é a "moeda" comum usada para converter datas entre diferentes sistemas de calendário e para realizar aritmética de datas em astronomia e história.

Raramente você digita um número de dia juliano manualmente. Em vez disso, você o obtém a partir de uma data do calendário usando um conversor como cal_to_jd() (e converte de volta com jdtogregorian()). A jddayofweek() então informa em qual dia da semana esse JDN cai.

O "número de dia juliano" usado aqui não tem relação com o calendário juliano (o calendário da era de César substituído pelo calendário gregoriano em 1582). Os nomes são semelhantes, mas são conceitos diferentes.

Sintaxe

jddayofweek(int $julian_day, int $mode = CAL_DOW_DAYNO): int|string

• $julian_day — o número de dia juliano a inspecionar (um inteiro, por exemplo, o resultado de cal_to_jd()).
• $mode — opcional. Seleciona o que a função retorna. O padrão é CAL_DOW_DAYNO (0).

O parâmetro mode

O mode é a parte desta função que mais confunde as pessoas. Existem três modos, e o padrão retorna um número começando em 0 para domingo — não um intervalo de 1 a 7 começando na segunda-feira.

Use as constantes nomeadas (CAL_DOW_LONG, etc.) em vez dos números brutos para manter seu código legível.

Como usar jddayofweek() no PHP

Primeiro converta a data desejada em um número de dia juliano com cal_to_jd(), que recebe o tipo de calendário mais inteiros separados para mês, dia e ano (nessa ordem). Em seguida, passe o resultado para jddayofweek() com o modo desejado.

A função jddayofweek() no PHP

<?php
// Convert the Gregorian date 2023-03-02 to a Julian day number.
// Argument order is: calendar, month, day, year.
$julianDay = cal_to_jd(CAL_GREGORIAN, 3, 2, 2023);

// Mode 0 (default): integer, 0 = Sunday ... 6 = Saturday
echo "Day number: " . jddayofweek($julianDay, CAL_DOW_DAYNO) . "\n";

// Mode 1: full weekday name
echo "Full name:  " . jddayofweek($julianDay, CAL_DOW_LONG) . "\n";

// Mode 2: abbreviated weekday name
echo "Short name: " . jddayofweek($julianDay, CAL_DOW_SHORT) . "\n";
?>

Isso imprime:

Day number: 4
Full name:  Thursday
Short name: Thu

2 de março de 2023 foi uma quinta-feira, portanto o modo padrão retorna 4 (domingo é 0, então quinta-feira é o quarto índice), CAL_DOW_LONG retorna "Thursday" e CAL_DOW_SHORT retorna "Thu".

Erros comuns

• O padrão é baseado em domingo, não em segunda-feira. O modo 0 retorna 0 para domingo, não 1 para segunda-feira. Se você espera a numeração ISO-8601 (segunda-feira = 1), adicione seu próprio deslocamento ou use DateTime.
• A extensão de calendário deve estar habilitada. jddayofweek() e cal_to_jd() pertencem à extensão calendar do PHP. Ela vem com a maioria das versões, mas pode ser desabilitada.
• Ordem errada dos argumentos em cal_to_jd(). A ordem é (calendar, month, day, year), não (year, month, day). Trocar mês e dia produz silenciosamente o dia da semana errado.

Conclusão

jddayofweek() mapeia um número de dia juliano para um dia da semana, seja como um índice baseado em domingo (CAL_DOW_DAYNO), um nome completo (CAL_DOW_LONG) ou uma abreviação (CAL_DOW_SHORT). Combinada com cal_to_jd(), ela permite determinar com precisão os dias da semana para trabalhos históricos, astronômicos ou de datas entre calendários diferentes.

Prática