# Spúšťače akcií

`Queuety::on_action()` umožňuje zmeniť bežnú akciu WordPress na odolné odoslanie úlohy do pracovného postupu.

Tým vzniká čisté prepojenie:

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

Hodí sa to, keď zaujímavá udalosť už nastala v WordPress a náročná alebo dlhotrvajúca reakcia sa má vykonať asynchrónne.

## Príklad: kontrola obsahu pri uložení príspevku

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

V tomto príklade:

- `save_post` je stále pôvodná udalosť WordPress
- `map` mení nespracované argumenty hooku na obyčajný stav pracovného postupu
- `when` preskočí nežiaduce udalosti skôr, než sa čokoľvek zaradí do frontu
- `idempotency_key` zabraňuje tomu, aby opakované spustenia hooku odoslali duplicitné úlohy

## Čo sa vykonáva synchrónne

Samotná spätná funkcia akcie sa stále vykonáva v rámci aktuálnej požiadavky WordPress.

To znamená, že tieto časti sú synchrónne:

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

Asynchrónne sa po odoslaní vykonávajú iba kroky pracovného postupu.

## Pravidlá pre údaje požiadavky

Mapované údaje požiadavky by mali obsahovať obyčajné polia, skaláre a `null`.

Neposielajte nespracované objekty WordPress, ako je `WP_Post`, priamo do stavu pracovného postupu. Najprv ich normalizujte v `map()`:

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

Kľúče začínajúce na `_` sa odmietnu, pretože tieto názvy sú vyhradené pre interný stav pracovného postupu.

## Prijaté argumenty

WordPress pri registrácii spätnej funkcie akcie vyžaduje počet `accepted_args`.

Queuety ho štandardne odvodí z vašich spätných funkcií `map`, `when` a `idempotency_key`, takže v bežnom prípade nie je potrebná ďalšia konfigurácia:

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

Ak potrebujete manuálne zadať inú hodnotu, výslovne nastavte `accepted_args`:

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

## Vstavané nástroje na tvorbu pracovných postupov

Môžete odoslať registrovaný názov pracovného postupu alebo vložený nástroj na jeho tvorbu `WorkflowBuilder`.

Vložené nástroje na tvorbu sa hodia, keď je pracovný postup špecifický pre hook definovaný v tom istom zavádzacom súbore:

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

## Kedy sa to hodí

Spúšťače akcií použite, keď:

- WordPress už vysiela udalosť, ktorá vás zaujíma
- reakcia má pretrvať aj po vypršaní časového limitu požiadavky alebo reštarte workera
- nadväzujúca práca sa môže vetviť, čakať alebo vyžadovať schválenie
- opakované spustenia hooku musia byť spoľahlivo idempotentné

Ak práca nesúvisí s hranicou udalosti WordPress, použite namiesto toho priame volanie `Queuety::dispatch()` alebo `Queuety::workflow()`.

## Nie pre filtre

`Queuety::on_action()` je zámerne určené iba pre akcie.

Filtre sú synchrónne transformácie vykonávané počas požiadavky. Zvyčajne by mali zostať synchrónne, pretože WordPress očakáva, že filtrovaná hodnota sa vráti okamžite.