easter_date()

Introdução

Calcular a data da Páscoa de forma programática é uma tarefa surpreendentemente comum — aplicativos de calendário, sistemas de agendamento e softwares de folha de pagamento precisam saber em que dia do ano a Páscoa cai, pois a data muda todos os anos. PHP possui duas funções nativas para isso: easter_date() e easter_days(). Este capítulo explica como a Páscoa é calculada, como cada função se comporta e qual delas usar para evitar problemas com fuso horário.

Por que a data da Páscoa muda

A Páscoa é uma festa móvel: ao contrário do Natal, não tem uma data fixa no calendário. Pela regra estabelecida no Concílio de Niceia em 325 d.C., o Domingo de Páscoa é o primeiro domingo após a primeira lua cheia no ou após o equinócio da primavera (vernal). Como isso depende do ciclo lunar, a data varia entre 22 de março e 25 de abril de ano para ano.

PHP implementa internamente o algoritmo padrão computus, de modo que você nunca precisa calcular a fase lunar por conta própria.

easter_date()

easter_date() retorna o timestamp Unix para o Domingo de Páscoa de um determinado ano.

• Assinatura: easter_date(?int $year = null, int $mode = CAL_EASTER_DEFAULT): int
• Parâmetros: O $year de quatro dígitos (padrão para o ano atual). O $mode opcional seleciona o cálculo gregoriano ou juliano.
• Valor de retorno: Um timestamp Unix para o Domingo de Páscoa.

Nota: Um erro comum é passar um timestamp para easter_date(). O argumento é um ano (ex.: 2023), não um timestamp. Passar mktime(...) produz um resultado incorreto.

O problema está nos fusos horários. O timestamp retornado aponta para o meio-dia UTC do Domingo de Páscoa; portanto, ao formatá-lo com date() sob um fuso horário padrão a oeste do UTC, o resultado pode retroceder para o dia anterior. Para exibição, prefira a abordagem com easter_days() descrita abaixo.

easter_days()

easter_days() retorna o número de dias após 21 de março em que a Páscoa cai, em vez de um timestamp. Esse é o bloco de construção seguro para fusos horários: combine-o com uma data de calendário simples e você obterá o dia correto independentemente de date_default_timezone_set().

• Assinatura: easter_days(?int $year = null, int $mode = CAL_EASTER_DEFAULT): int
• Valor de retorno: Um deslocamento inteiro (por exemplo, 19 significa 21 de março + 19 dias).

Disponibilidade: easter_date() e easter_days() fazem parte da extensão de calendário do PHP. Foram movidas para o núcleo no PHP 8.0 e ainda estão disponíveis no PHP atual (8.x) — não foram removidas. Se você ver Call to undefined function easter_date() em uma versão mais antiga, habilite a extensão calendar.

Código de exemplo

Recomendado — seguro para fuso horário com easter_days()

<?php

$year = 2023;
$easter = (new DateTimeImmutable("$year-03-21"))
    ->modify('+' . easter_days($year) . ' days');

echo $easter->format('F j, Y'); // Outputs: April 9, 2023

Linha única rápida com easter_date()

<?php

$year = 2023;
echo date('F j, Y', easter_date($year));

easter_date() ancora o timestamp ao meio-dia UTC, portanto o dia do calendário exibido depende do fuso horário de formatação — observe como o mesmo ano é impresso de forma diferente abaixo. É exatamente por isso que a versão com easter_days() acima é a escolha mais segura:

<?php

date_default_timezone_set('UTC');
echo date('F j, Y H:i', easter_date(2024)); // Outputs: March 30, 2024 20:00

Leitura relacionada

• Função date() do PHP
• PHP date_default_timezone_set()
• Data e Hora em PHP

Conclusão

A Páscoa é uma festa móvel, portanto sua data deve ser calculada a partir do calendário lunar a cada ano. PHP faz o trabalho pesado por você por meio da extensão de calendário. Para código de exibição, prefira easter_days() combinado com DateTimeImmutable para que o resultado não seja afetado pelo fuso horário do servidor; use easter_date() para um timestamp rápido quando você controla o fuso horário padrão.

Prática