# Spouštěče akcí

`Queuety::on_action()` umožňuje změnit běžnou akci WordPress na spuštění trvalého workflow.

Tím vznikne přehledné propojení:

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

Hodí se to, když událost, která vás zajímá, už existuje v WordPress a náročná nebo dlouhotrvající reakce má proběhnout asynchronně.

## Příklad: kontrola obsahu při uložení příspěvku

```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 příkladu:

- `save_post` je stále původní událost WordPress
- `map` převádí nezpracované argumenty háku na jednoduchý stav workflow
- `when` přeskočí nežádoucí události dříve, než se cokoli zařadí do fronty
- `idempotency_key` zabrání tomu, aby opakované spuštění háku vyvolalo duplicitní běhy

## Co se spouští synchronně

Samotná zpětná volací funkce akce se stále spouští v rámci aktuálního požadavku WordPress.

To znamená, že tyto části probíhají synchronně:

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

Asynchronně se po spuštění provádějí pouze kroky workflow.

## Pravidla pro data

Mapovaná data by měla obsahovat jednoduchá pole, skalární hodnoty a `null`.

Nepředávejte nezpracované objekty WordPress, jako je `WP_Post`, přímo do stavu workflow. Nejprve je 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,
    ],
);
```

Klíče začínající na `_` jsou odmítnuty, protože tyto názvy jsou vyhrazené pro interní stav workflow.

## Přijímané argumenty

WordPress vyžaduje při registraci zpětné volací funkce akce počet `accepted_args`.

Queuety jej ve výchozím nastavení odvodí z vašich zpětných volacích funkcí `map`, `when` a `idempotency_key`, takže běžný případ nevyžaduje žádnou další konfiguraci:

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

Pokud potřebujete ruční přepsání, zadejte výslovně `accepted_args`:

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

## Sestavovače vložených workflow

Můžete spustit registrovaný název workflow nebo vložené `WorkflowBuilder`.

Vložené sestavovače se hodí, když je workflow specifické pro daný hák definováno ve stejném inicializačním souboru:

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

## Kdy se tento přístup hodí

Spouštěče akcí použijte, když:

- WordPress už vysílá událost, která vás zajímá
- reakce má přežít vypršení časového limitu požadavku nebo restart workeru
- následná práce se může větvit, čekat nebo vyžadovat schválení
- opakovaná spuštění háku vyžadují trvalou idempotenci

Pokud práce není navázaná na hranici události WordPress, použijte přímé volání `Queuety::dispatch()` nebo `Queuety::workflow()`.

## Ne pro filtry

`Queuety::on_action()` je záměrně určen pouze pro akce.

Filtry synchronně transformují data během požadavku. Obvykle by měly zůstat synchronní, protože WordPress očekává okamžité vrácení filtrované hodnoty.