Agendador de tarefas em PHP: biblioteca cron‑expression para agendamento flexível

Agendador de tarefas PHP: biblioteca cron‑expression

Ao desenvolver aplicações web em PHP, surge frequentemente a necessidade de executar determinadas ações em um agendamento: enviar notificações, limpar cache, gerar relatórios ou sincronizar dados. O cron integrado no Linux é uma ferramenta poderosa, mas sua configuração requer acesso ao servidor e nem sempre é conveniente para agendamento dinâmico dentro do código PHP. A biblioteca cron‑expression resolve esse problema — ela permite analisar, verificar e calcular o tempo de execução de tarefas com base em expressões CRON diretamente no PHP.

Neste artigo, vamos abordar como instalar e usar a biblioteca cron‑expression, escrever um agendador de tarefas simples e ver exemplos com cenários reais.

O que é cron‑expression?

cron‑expression é uma biblioteca PHP para trabalhar com expressões CRON. Uma expressão CRON é uma string composta por cinco campos separados por espaços:

* * * * *| | | | || | | | +---- dia da semana (0–7) (domingo = 0 ou 7)| | | +------ mês (1–12)| | +-------- dia do mês (1–31)| +---------- hora (0–23)+------------ minuto (0–59)

Por exemplo, a expressão 30 4 * * 1-5 significa: "todos os dias úteis às 4:30 da manhã". A biblioteca permite:

• Verificar se a hora atual corresponde à expressão fornecida.
• Obter a próxima data de execução da tarefa.
• Calcular a data de execução anterior.
• Trabalhar com intervalos, passos e listas de valores.

Instalação

A instalação é feita via Composer. Abra o terminal na raiz do seu projeto e execute:

composer require mtdowling/cron-expression

Após a instalação, inclua o autoload do Composer no seu script PHP:

require 'vendor/autoload.php';

Principais recursos e exemplos

1. Verificação da hora atual

Suponha que queremos executar uma tarefa a cada 15 minutos. Expressão CRON: */15 * * * *. Vamos criar um objeto e verificar se a tarefa deve ser executada agora:

<?phpuse Cron\\CronExpression;

$expression = CronExpression::factory('*/15 * * * *');if ($expression->isDue()) {    echo "A tarefa deve ser executada agora!";} else {    echo "Ainda não é hora.";}?>

O método isDue() verifica se a hora atual corresponde à expressão. Por padrão, é usado o fuso horário do servidor.

2. Obtendo a próxima data de execução

Às vezes, precisamos saber com antecedência quando a tarefa será executada:

<?phpuse Cron\\CronExpression;

$expression = CronExpression::factory('0 6 * * 1-5'); // todos os dias úteis às 6:00$nextRun = $expression->getNextRunDate();echo "Próxima execução: " . $nextRun->format('Y-m-d H:i:s');?>

Resultado: Próxima execução: 2025-03-10 06:00:00 (se hoje for sexta-feira, a próxima será segunda-feira).

3. Data de execução anterior

O método getPreviousRunDate() retorna o último momento em que a condição foi atendida:

<?php$prevRun = $expression->getPreviousRunDate();echo "Execução anterior: " . $prevRun->format('Y-m-d H:i:s');?>

4. Trabalhando com fusos horários

Por padrão, é usado o fuso horário do servidor, mas você pode definir o seu próprio:

<?php$expression = CronExpression::factory('0 9 * * *');$expression->setTimezone(new DateTimeZone('Europe/Moscow'));if ($expression->isDue()) {    echo "Em Moscou agora são 9:00 — hora de agir!";}?>

Criando um agendador de tarefas simples

Agora vamos juntar tudo e escrever uma pequena classe que executará tarefas em um agendamento. Suponha que temos uma lista de tarefas com expressões CRON e callbacks.

<?phpclass