Trigger delle azioni

Queuety::on_action() permette di trasformare una normale azione WordPress nell’avvio di un workflow duraturo.

Questo crea un collegamento diretto:

WordPress action -> mapped payload -> durable workflow

È utile quando l’evento di interesse esiste già in WordPress e la risposta costosa o di lunga durata deve avvenire in modo asincrono.

Esempio: revisionare i contenuti quando si salva un articolo

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}",
);

In questo esempio:

• save_post è ancora l’evento WordPress originale
• map trasforma gli argomenti grezzi dell’hook in uno stato del workflow semplice
• when esclude gli eventi indesiderati prima che venga messo qualcosa in coda
• idempotency_key evita che le attivazioni ripetute dell’hook avviino esecuzioni duplicate

Cosa viene eseguito in modo sincrono

La callback dell’azione viene comunque eseguita all’interno della richiesta WordPress corrente.

Ciò significa che queste parti sono sincrone:

• when
• map
• idempotency_key

Solo i passaggi del workflow vengono eseguiti in modo asincrono dopo l’avvio.

Regole per il payload

I payload mappati devono contenere array semplici, valori scalari e null.

Non passate oggetti WordPress grezzi come WP_Post direttamente allo stato del workflow. Prima normalizzateli all’interno di 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,
    ],
);

Le chiavi che iniziano con _ vengono rifiutate, perché questi nomi sono riservati allo stato interno del workflow.

Argomenti accettati

WordPress richiede un conteggio accepted_args quando si registra una callback di azione.

Per impostazione predefinita, Queuety lo deduce dalle callback map, when e idempotency_key, quindi nel caso comune non serve alcuna configurazione aggiuntiva:

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 serve un override manuale, passate esplicitamente accepted_args:

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

Builder inline dei workflow

Potete avviare un workflow registrato per nome o tramite un builder inline WorkflowBuilder.

I builder inline sono utili quando il workflow specifico dell’hook è definito nello stesso file di bootstrap:

$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 è una scelta adatta

Usate i trigger delle azioni quando:

• WordPress emette già l’evento che vi interessa
• la risposta deve resistere ai timeout delle richieste o ai riavvii dei worker
• il lavoro successivo può diramarsi, attendere o richiedere un’approvazione
• le attivazioni duplicate dell’hook richiedono un’idempotenza duratura

Usate invece una chiamata diretta a Queuety::dispatch() o Queuety::workflow() quando il lavoro non è legato a un confine di evento WordPress.

Non per i filtri

Queuety::on_action() è intenzionalmente riservato alle azioni.

I filtri sono trasformazioni sincrone eseguite durante la richiesta. Di solito devono restare sincroni, perché WordPress si aspetta di ricevere immediatamente il valore filtrato.