# Toimingu käivitajad

`Queuety::on_action()` võimaldab muuta tavalise WordPress toimingu vastupidavaks töövoo käivituseks.

See loob selge ühenduse:

`WordPress action -> mapped payload -> durable workflow`

See on kasulik, kui vajalik sündmus on WordPress-is juba olemas ja kulukas või pikaajaline vastus peaks toimuma asünkroonselt.

## Näide: vaadake sisu üle postituse salvestamisel

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

Selles näites:

- `save_post` on endiselt algne WordPress sündmus
- `map` teisendab toored hook’i argumendid lihtsaks töövoo olekuks
- `when` jätab soovimatud sündmused vahele enne, kui midagi järjekorda pannakse
- `idempotency_key` takistab korduvatel hook’i käivitustel duplikaattööde käivitamist

## Mis käivitub sünkroonselt

Toimingutagasihelistus ise käivitub endiselt praeguse WordPress päringu sees.

See tähendab, et järgmised osad on sünkroonsed:

- `when`
- `map`
- `idempotency_key`

Asünkroonselt käivituvad pärast väljasaatmist ainult töövoo sammud.

## Kasuliku koorma reeglid

Seostatud kasulikud koormad peaksid sisaldama lihtsaid massiive, skalaare ja `null`.

Ära edasta tooreid WordPress objekte, näiteks `WP_Post`, otse töövoo olekusse. Normaliseeri need esmalt `map()` sees:

```php
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,
    ],
);
```

Võtmed, mis algavad `_`-ga, lükatakse tagasi, sest need nimed on reserveeritud töövoo sisemisele olekule.

## Aktsepteeritavad argumendid

WordPress nõuab toimingutagasihelistuse registreerimisel argumentide arvu `accepted_args`.

Queuety tuletab selle vaikimisi sinu `map`, `when` ja `idempotency_key` tagasihelistustest, seega tavalisel juhul pole lisaseadistusi vaja:

```php
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,
    ],
);
```

Kui vajad käsitsi määramist, edasta selgesõnaliselt `accepted_args`:

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

## Töövoo sisemised koostajad

Saad välja saata registreeritud töövoo nime või sisemise `WorkflowBuilder`.

Sisemised koostajad on kasulikud, kui hook’iga seotud töövoog on määratletud samas alglaadimisfailis:

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

## Millal see sobib

Kasuta toimingu käivitajaid, kui:

- WordPress väljastab juba sind huvitava sündmuse
- vastus peaks säilima ka päringu ajalõpu või töötaja taaskäivitamise korral
- järeltegevusel võib olla mitu haru, see võib oodata või vajada heakskiitu
- korduvate hook’i käivituste jaoks on vaja püsivat idempotentsust

Kasuta selle asemel otsest `Queuety::dispatch()`- või `Queuety::workflow()`-kutset, kui töö pole seotud WordPress sündmuse piiriga.

## Filtrite jaoks mitte

`Queuety::on_action()` on teadlikult mõeldud ainult toimingute jaoks.

Filtrid on sünkroonsed teisendused päringu ajal. Need peaksid tavaliselt jääma sünkroonseks, sest WordPress eeldab, et filtreeritud väärtus tagastatakse kohe.