PHP Calendário

Introdução

Este capítulo aborda como trabalhar com datas, horas e calendários em PHP. Você aprenderá as principais funções de data e hora, como construir uma grade de calendário para um determinado mês e as boas práticas que mantêm a lógica de datas correta em diferentes fusos horários. Cada exemplo é pequeno e executável, para que você possa colá-lo diretamente em um arquivo PHP.

Para uma análise mais aprofundada de tópicos individuais, consulte os capítulos relacionados sobre Data e Hora em PHP, a função date() e Fusos Horários em PHP.

Compreendendo as Funções de Data e Hora do PHP

O PHP oferece um conjunto robusto de funções de data e hora para formatar, calcular e manipular datas, horas e fusos horários. Essas funções são essenciais para aplicações que precisam trabalhar com dados temporais, como agendadores, sistemas de reservas e, claro, calendários.

O PHP também inclui uma Extensão de Calendário separada (cal_days_in_month(), jdtogregorian() e outras) para conversão entre sistemas de calendário como Juliano, Gregoriano e Judaico. As duas são frequentemente confundidas: a Extensão de Calendário converte entre sistemas, enquanto as funções de data/hora abaixo lidam com formatação e aritmética do dia a dia. A maioria das tarefas de "construir um calendário" precisa apenas das funções de data/hora.

Funções Comuns de Data e Hora em PHP

1. date() – Formata uma string de data e hora local de acordo com um formato especificado.

   echo date("Y-m-d H:i:s"); // Outputs: 2023-10-25 14:30:00

   Copiar
2. mktime() – Cria um timestamp Unix para uma data e hora especificadas.

   echo mktime(14, 30, 0, 10, 25, 2023); // Outputs: 1698237000

   Copiar
   Nota: mktime() depende do fuso horário padrão do servidor. Para resultados reproduzíveis, defina explicitamente um fuso horário usando date_default_timezone_set() ou DateTimeZone.
3. strtotime() – Analisa uma string de data/hora textual em inglês e a converte em um timestamp Unix.

   echo strtotime("now"); // Outputs: current timestamp
   echo strtotime("+1 day"); // Outputs: timestamp for tomorrow

   Copiar
4. time() – Retorna o timestamp Unix atual.

   echo time(); // Outputs: current timestamp

   Copiar
5. DateTime & DateTimeImmutable – Classes orientadas a objetos para manipulação e formatação de data/hora com mais segurança.

   $dt = new DateTime('2023-10-25 14:30:00');
   echo $dt->format('Y-m-d H:i:s');

   Copiar

Além dessas funções, existem muitas outras para manipular datas e horas. Entender como elas funcionam permite criar aplicações PHP eficientes e confiáveis.

Quantos Dias Tem um Mês?

Uma tarefa comum em calendários é encontrar o número de dias em um determinado mês, que varia e depende de anos bissextos para fevereiro. Existem duas maneiras confiáveis de fazer isso:

// Using the Calendar Extension (requires ext-calendar)
echo cal_days_in_month(CAL_GREGORIAN, 2, 2024); // Outputs: 29 (2024 is a leap year)

// Using date() with the 't' format character (no extension needed)
echo date('t', mktime(0, 0, 0, 2, 1, 2024)); // Outputs: 29

A abordagem date('t', ...) é portátil porque não depende da Extensão de Calendário estar instalada.

Construindo um Calendário Simples para um Mês

Juntando as peças, veja como imprimir os dias de um mês alinhados sob colunas de dias da semana. Encontramos o primeiro dia da semana do mês com date('w', ...) (0 = domingo) e a contagem de dias com date('t', ...):

$month = 10;
$year  = 2023;

$firstDayTimestamp = mktime(0, 0, 0, $month, 1, $year);
$daysInMonth       = (int) date('t', $firstDayTimestamp);
$startWeekday      = (int) date('w', $firstDayTimestamp); // 0 = Sunday

echo "Su Mo Tu We Th Fr Sa\n";

// Pad the first row so day 1 lands under the correct weekday.
echo str_repeat('   ', $startWeekday);

for ($day = 1; $day <= $daysInMonth; $day++) {
    printf('%2d ', $day);
    // Break to a new line after Saturday.
    if (($startWeekday + $day) % 7 === 0) {
        echo "\n";
    }
}
echo "\n";

Este loop imprime outubro de 2023 como uma grade de calendário. Para saber mais sobre o loop utilizado aqui, consulte Loops em PHP.

Boas Práticas para Usar Funções de Data e Hora em PHP

Ao usar funções de data e hora em PHP, é importante seguir boas práticas para garantir que suas aplicações sejam eficientes e eficazes. Aqui estão algumas dicas a serem lembradas:

1. Prefira objetos DateTime e DateTimeImmutable em vez de funções procedurais para maior legibilidade e segurança integrada de fuso horário.
2. Sempre defina um fuso horário explícito usando DateTimeZone ou date_default_timezone_set() para evitar mudanças inesperadas durante o horário de verão ou migrações de servidor.
3. Valide datas analisadas usando DateTime::getLastErrors() para detectar entradas inválidas cedo e evitar falhas silenciosas.
4. Armazene em cache timestamps calculados ou strings formatadas em loops intensivos para reduzir a sobrecarga de chamadas de função.

Conclusão

As funções de data e hora do PHP são uma parte essencial de qualquer aplicação PHP que precise trabalhar com dados temporais. Ao entender como essas funções funcionam e seguir as boas práticas, você pode desenvolver aplicações confiáveis e eficientes.

Prática