Acionadores de ações

Queuety::on_action() permite transformar uma ação WordPress comum em um despacho durável de fluxo de trabalho.

Isso cria uma ligação clara:

WordPress action -> mapped payload -> durable workflow

Isso é útil quando o evento de interesse já existe em WordPress e a resposta demorada ou de alto custo deve ocorrer de forma assíncrona.

Exemplo: revisar conteúdo quando uma publicação é salva

use Queuety\Queuety;

Queuety::on_action(
    'save_post',
    workflow: 'content_review',
    map: static fn ( int $post_id, object $post, bool $update ): array => [
        'post_id' => $post_id,
        'post_type' => $post->post_type,
        'update' => $update,
    ],
    when: static fn ( int $post_id, object $post ): bool => 'post' === $post->post_type,
    idempotency_key: static fn ( int $post_id ): string => "save_post:{$post_id}",
);

Nesse exemplo:

• save_post continua sendo o evento WordPress original
• map transforma argumentos brutos do hook em estado simples do fluxo de trabalho
• when ignora eventos indesejados antes que qualquer coisa seja enfileirada
• idempotency_key impede que chamadas repetidas do hook iniciem execuções duplicadas

O que é executado de forma síncrona

O próprio callback da ação continua sendo executado na solicitação atual de WordPress.

Isso significa que estas partes são síncronas:

• when
• map
• idempotency_key

Somente as etapas do fluxo de trabalho são executadas de forma assíncrona após o despacho.

Regras para o payload

Os payloads mapeados devem conter arrays simples, escalares e null.

Não passe objetos brutos de WordPress, como WP_Post, diretamente ao estado do fluxo de trabalho. Primeiro, normalize-os dentro de map():

Queuety::on_action(
    'save_post',
    workflow: 'content_review',
    map: static fn ( int $post_id, object $post, bool $update ): array => [
        'post_id' => $post_id,
        'post_type' => $post->post_type,
        'post_status' => $post->post_status,
        'update' => $update,
    ],
);

Chaves que começam com _ são rejeitadas porque esses nomes são reservados para o estado interno do fluxo de trabalho.

Argumentos aceitos

WordPress exige uma contagem de accepted_args ao registrar um callback de ação.

Queuety deduz esse valor por padrão com base nos callbacks map, when e idempotency_key, portanto o caso mais comum não exige configuração adicional:

Queuety::on_action(
    'save_post',
    workflow: 'content_review',
    map: static fn ( int $post_id, object $post, bool $update ): array => [
        'post_id' => $post_id,
        'update' => $update,
    ],
);

Se precisar substituir o valor manualmente, passe accepted_args explicitamente:

Queuety::on_action(
    'comment_post',
    workflow: 'comment_review',
    accepted_args: 2,
);

Criadores de fluxos de trabalho em linha

Você pode iniciar um fluxo de trabalho registrado pelo nome ou um WorkflowBuilder em linha.

Criadores em linha são úteis quando o fluxo de trabalho específico do hook é definido no mesmo arquivo de inicialização:

$review = Queuety::workflow( 'comment_review' )
    ->then( ModerateCommentStep::class )
    ->then( NotifyModeratorStep::class );

Queuety::on_action(
    'comment_post',
    workflow: $review,
    map: static fn ( int $comment_id ): array => [
        'comment_id' => $comment_id,
    ],
    idempotency_key: static fn ( int $comment_id ): string => "comment:{$comment_id}",
);

Quando é adequado

Use acionadores de ações quando:

• WordPress já emitir o evento de seu interesse
• a resposta precisar resistir a tempos limite da solicitação ou reinicializações do processo de trabalho
• o trabalho de acompanhamento puder se ramificar, aguardar ou exigir aprovação
• chamadas duplicadas do hook precisarem de idempotência durável

Use uma chamada direta a Queuety::dispatch() ou Queuety::workflow() quando o trabalho não estiver vinculado a um limite de evento WordPress.

Não use para filtros

Queuety::on_action() foi projetado intencionalmente apenas para ações.

Filtros são transformações síncronas executadas durante a solicitação. Em geral, devem continuar síncronos, pois WordPress espera que um valor filtrado seja retornado imediatamente.