Biblioteca cron.php

Caminho no Gestor bibliotecas/cron.php

Rotinas automáticas têm três partes:

1. A declaração, na chave cron do JSON do módulo, que o pipeline grava na tabela cron_tarefas.

2. A engine gestor/cron.php, um script de linha de comando que executa as tarefas de uma frequência.

3. O agendador do servidor (crontab, painel da hospedagem), que chama a engine. Nada no Conn2Flow cria esse agendamento: nem o instalador, nem o painel. Sem ele, nenhuma tarefa roda.

A biblioteca cron.php concentra o que a engine, o compilador de recursos e o painel admin-cron compartilham.

Declarar uma tarefa

Na raiz do <modulo>.json:

{
  "cron": [
    {
      "id": "expiracao-trials",
      "nome": "Expirar assinaturas de teste",
      "funcao": "meu_modulo_cron_expirar_trials",
      "frequencia": "diario",
      "hora": "03:30",
      "parametros": { "dias": 7 },
      "ativo": true
    }
  ]
}

Tarefa sem id ou funcao, com frequência desconhecida ou expressão inválida vira órfã na compilação e não chega ao banco (recursos). No painel, ativo, expressao_cron e parametros podem ser ajustados e são preservados no deploy.

A função da tarefa

// gestor/modulos/meu-modulo/meu-modulo.cron.php
function meu_modulo_cron_expirar_trials($parametros) {
    $dias = (int)($parametros['dias'] ?? 7);
    // ...
    echo "12 assinaturas expiradas\n";          // vira o log da execução
    return ['status' => 'aviso', 'log' => '3 sem e-mail']; // opcional
}

cron_tarefa_executar() captura tudo que a função imprime e o retorno:

• ['status' => 'sucesso|erro|aviso', 'log' => …] define o resultado;

• false é erro; qualquer outro retorno é sucesso;

• uma exceção vira erro e não interrompe as outras tarefas.

O resultado vai para a própria linha em cron_tarefas (ultimo_disparo, ultima_duracao_ms, ultimo_status e ultimo_log, cortado em 4000 bytes) e para gestor/logs/cron-<dd-mm-aaaa>.log.

Agendar a engine

php gestor/cron.php frequencia=<frequencia> [server=<dominio>] [debug]
php gestor/cron.php tarefa=<id> [debug]      # uma tarefa, fora da janela (pausada não roda)
php gestor/cron.php listar

Registre um tick por frequência no agendador do servidor, com os horários padrão da biblioteca (cron_expressao_padrao()):

*/10 * * * *  php /caminho/gestor/cron.php frequencia=minutario
0 * * * *     php /caminho/gestor/cron.php frequencia=horario
0 3 * * *     php /caminho/gestor/cron.php frequencia=diario
0 4 1 * *     php /caminho/gestor/cron.php frequencia=mensal

Com uma única pasta com .env em autenticacoes/, o domínio é detectado; com várias, server=<dominio> é obrigatório (sem ele, a engine sai com erro em vez de rodar contra o banco errado).

O painel admin-cron só infere se há agendador: se alguma tarefa ativa rodou nas últimas 24 horas.

Para compatibilidade, cada tick também dispara o hook cron.<frequencia> (hooks).

Funções auxiliares

• cron_frequencias_validas(), cron_status_validos(): os vocabulários.

• cron_expressao_valida($e): só a forma (cinco campos com dígitos e * , - /), não se os valores fazem sentido.

• cron_expressao_declarada($tarefa, $frequencia): a expressão final, ou null se inválida.

• cron_tarefas_carregar($frequencia, $tarefaId, $todas, $campos): lê cron_tarefas (sem as excluídas; sem as pausadas, a menos que $todas).

Auxiliares internos (usados pelas funções acima; raramente chamados direto): cron_callback_preparar(), cron_tarefa_registrar().

Funções

cron_frequencias_validas()

cron_status_validos()

cron_expressao_valida(string $expressao): bool

cron_expressao_padrao(string $frequencia): string|null

cron_expressao_declarada(array $tarefa, string $frequencia): string|null

cron_callback_preparar(array $tarefa): string|null

cron_tarefa_executar(array $tarefa): array{status: string, duracao: int, log: string}

cron_tarefa_registrar(string $id, string $status, int $duracaoMs, string $log): void

cron_tarefas_carregar(string|null $frequencia = null, string|null $tarefaId = null, bool $todas = false, array $campos = null): array