cal_days_in_month()

A função PHP cal_days_in_month() retorna o número de dias em um mês para um determinado calendário, mês e ano. Como ela compreende anos bissextos e diferentes sistemas de calendário, é mais confiável do que codificar contagens de dias manualmente ou fazer o cálculo de ano bissexto à mão. Esta página aborda sua assinatura, exemplos de uso (incluindo anos bissextos e o calendário Juliano), armadilhas comuns e a alternativa para quando a extensão Calendar não estiver disponível.

Sintaxe

cal_days_in_month(int $calendar, int $month, int $year): int

Retorna o número de dias como um int. cal_days_in_month() faz parte da extensão Calendar, que é fornecida com o PHP mas deve estar habilitada (está por padrão na maioria das instalações). Se a extensão não estiver disponível, a função não existe; veja Sem a extensão Calendar abaixo.

Uso básico

Passe a constante do calendário, o mês e o ano:

Isso imprime There are 31 days in January 2022.

Tratamento de anos bissextos

A função leva em conta automaticamente os anos bissextos, portanto fevereiro retorna 28 ou 29 sem nenhuma lógica extra da sua parte:

<?php
echo cal_days_in_month(CAL_GREGORIAN, 2, 2020); // 29 — 2020 is a leap year
echo "\n";
echo cal_days_in_month(CAL_GREGORIAN, 2, 2023); // 28 — 2023 is not
?>

Listando todos os meses de um ano

Uma tarefa comum é construir um calendário ou um seletor de datas. Percorra os 12 meses em um loop:

<?php
$year = 2024;
$names = ['January', 'February', 'March', 'April', 'May', 'June',
          'July', 'August', 'September', 'October', 'November', 'December'];

for ($month = 1; $month <= 12; $month++) {
    $days = cal_days_in_month(CAL_GREGORIAN, $month, $year);
    echo "{$names[$month - 1]} $year: $days days\n";
}
?>

Para 2024 (um ano bissexto), isso imprime February 2024: 29 days, enquanto todos os outros meses mostram sua contagem habitual.

Usando um calendário diferente

Alterar o primeiro argumento muda o sistema de calendário. O calendário Juliano, por exemplo, trata 1900 como ano bissexto, enquanto o calendário Gregoriano não:

<?php
echo cal_days_in_month(CAL_JULIAN, 2, 1900);    // 29
echo "\n";
echo cal_days_in_month(CAL_GREGORIAN, 2, 1900); // 28
?>

Armadilhas comuns

• Mês ou ano inválido: passar um mês fora do intervalo válido (por exemplo 13 ou 0) gera um aviso e retorna false, não uma contagem de dias. Valide a entrada antes de chamar a função.
• Conversão de tipos: false é vagamente igual a 0. Use uma verificação estrita (if ($days === false)) em vez de if (!$days) ao tratar erros.
• Dependência da extensão: a função só existe quando a extensão Calendar está carregada. Use function_exists('cal_days_in_month') em código portável.

Sem a extensão Calendar

Se a extensão Calendar não estiver disponível, a classe DateTime (sempre disponível) fornece o mesmo resultado Gregoriano por meio do caractere de formato t, que representa o número de dias no mês:

<?php
$date = new DateTime('2024-02-01');
echo $date->format('t'); // 29
?>

Esta é a opção mais portável para o calendário Gregoriano e não requer nenhuma extensão extra.

Conclusão

cal_days_in_month() retorna a contagem de dias de um mês em um determinado calendário e ano, tratando anos bissextos e múltiplos sistemas de calendário automaticamente. Use-a quando trabalhar com a extensão Calendar ou precisar de um calendário não Gregoriano; caso contrário, DateTime::format('t') é uma alternativa sem dependências.

Para continuar trabalhando com datas em PHP, veja PHP Date and Time e a função checkdate() para validar uma data Gregoriana.

Diagrama

graph LR
A[Input Calendar Type, Month, and Year] -- cal_days_in_month --> B[Output Number of Days]

Prática