# Actietriggers

Met `Queuety::on_action()` kun je een gewone actie van WordPress omzetten in het starten van een duurzame workflow.

Zo ontstaat een heldere verbinding:

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

Dit is handig wanneer de gebeurtenis die ertoe doet al plaatsvindt in WordPress en de kostbare of langlopende reactie asynchroon moet plaatsvinden.

## Voorbeeld: content beoordelen wanneer een bericht wordt opgeslagen

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

In dat voorbeeld:

- `save_post` blijft de oorspronkelijke gebeurtenis van WordPress
- `map` zet ruwe hookargumenten om in eenvoudige workflowstatus
- `when` slaat ongewenste gebeurtenissen over voordat er iets in de wachtrij wordt geplaatst
- `idempotency_key` voorkomt dat herhaalde hookaanroepen dubbele runs starten

## Wat synchroon wordt uitgevoerd

De actiecallback zelf wordt nog steeds uitgevoerd binnen het huidige verzoek van WordPress.

Dat betekent dat deze onderdelen synchroon zijn:

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

Alleen de workflowstappen worden na het starten asynchroon uitgevoerd.

## Regels voor de inhoud

Toegewezen inhoud moet bestaan uit eenvoudige arrays, scalaire waarden en `null`.

Geef geen ruwe objecten van WordPress, zoals `WP_Post`, rechtstreeks door aan de workflowstatus. Normaliseer ze eerst binnen `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,
    ],
);
```

Sleutels die beginnen met `_` worden geweigerd, omdat die namen zijn gereserveerd voor interne workflowstatus.

## Geaccepteerde argumenten

WordPress vereist een aantal `accepted_args` bij het registreren van een actiecallback.

Queuety leidt dit standaard af uit je callbacks voor `map`, `when` en `idempotency_key`, zodat je in het gebruikelijke geval geen extra configuratie nodig hebt:

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

Als je de waarde handmatig wilt overschrijven, geef dan expliciet `accepted_args` mee:

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

## Inline workflowbouwers

Je kunt een geregistreerde workflownaam of een inline `WorkflowBuilder` starten.

Inline bouwers zijn handig wanneer de hookspecifieke workflow in hetzelfde bootstrapbestand is gedefinieerd:

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

## Wanneer dit goed past

Gebruik actietriggers wanneer:

- WordPress de gebeurtenis waar je om geeft al uitzendt
- de reactie bestand moet zijn tegen time-outs van verzoeken of herstarts van workers
- het vervolgwerk vertakkingen kan hebben, kan wachten of goedkeuring kan vereisen
- dubbele hookaanroepen duurzaam idempotent moeten worden afgehandeld

Gebruik in plaats daarvan een rechtstreekse aanroep van `Queuety::dispatch()` of `Queuety::workflow()` wanneer het werk niet gekoppeld is aan een gebeurtenisgrens van WordPress.

## Niet voor filters

`Queuety::on_action()` is bewust alleen voor acties bedoeld.

Filters zijn synchrone transformaties tijdens een verzoek. Ze moeten meestal synchroon blijven, omdat WordPress verwacht dat een gefilterde waarde onmiddellijk wordt geretourneerd.