Guias

Trabalho em segundo plano

Eventos de recursos, a fila de jobs e tarefas agendadas.

O trabalho que não deve atrasar uma requisição de página roda em segundo plano: e-mails de confirmação, importações, chamadas a outros sistemas, relatórios noturnos. O Nimbly tem três partes para isso: eventos de recursos, uma fila de jobs e um agendador.

Eventos de recursos

Um recurso declara o que acontece depois que um registro é criado, alterado ou excluído:

"events": {
  "create": ["job:lead-created"],
  "update": ["lead-updated"]
}
  • Um nome simples executa uma função logo depois da gravação. lead-updated chama lead_updated($event) de lib/lead-updated.php num módulo.
  • Uma entrada job: coloca um job na fila em vez disso, para que a requisição termine na hora e o trabalho aconteça um instante depois.

O evento traz a ação, o recurso, o UUID do registro e os dados dele.

Jobs

Um job na fila é tratado por uma função com o nome do seu tipo, no lib/ de um módulo:

<?php
// ext/modules/leads/lib/lead-created.php

function lead_created_job($job)
{
    $lead = $job['payload']['data'] ?? [];
    load_library('email');
    load_library('env');
    set_variable('lead', $lead);
    $sent = email([
        'service' => env('MAIL_SERVICE', 'resend'),
        'from' => env('MAIL_FROM'),
        'from_name' => env('MAIL_FROM_NAME'),
        'recipient' => $lead['email'],
        'subject' => 'Thank you for your message',
        'tpl' => 'email-lead-thanks',
    ]);
    if (!$sent) {
        throw new Exception('Confirmation email not sent');
    }
    return true;
}

Um job que lança um erro é tentado de novo, por padrão até cinco vezes. Um job que falha de vez é marcado como falho, aparece no admin e é informado por e-mail a SYSTEM_ALERT_EMAIL. Coloque um job na fila a partir do seu próprio código com job_enqueue('report-build', ['month' => '2026-10']).

A fila guarda o que fazer e os dados, nunca comandos. /nb-admin/jobs mostra os jobs na fila, em execução, concluídos e falhos, com o último erro de cada um.

O agendador

O agendador roda a cada minuto. Ele sempre executa a manutenção do framework: a fila de jobs, a limpeza de sessões, de jobs antigos e de histórico antigo, e o resumo das estatísticas a cada hora. Um projeto acrescenta suas próprias tarefas em ext/cli/schedule.inc, ou por ambiente em schedule.prod.inc e schedule.stage.inc:

<?php
return [
    ['id' => 'report-nightly', 'command' => 'report:build', 'daily_at' => '02:00', 'timezone' => 'Europe/Amsterdam'],
    ['id' => 'rates-refresh', 'command' => 'rates:refresh', 'every_minutes' => 15],
];

O ./nimbly schedule:init cria esses arquivos. Os comandos próprios são registrados em ext/cli/commands.php.

Num contêiner, o agendador inicia sozinho. Num servidor próprio, ele é instalado uma vez por servidor; veja Jobs e o agendador. O ./nimbly schedule:status informa se cada tarefa rodou no horário.

Ver esta página em Markdown