# Åtgärdstriggers

`Queuety::on_action()` låter dig göra en vanlig åtgärd i WordPress till en beständig utskickning av arbetsflöde.

Det ger en smidig koppling:

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

Det här är användbart när den intressanta händelsen redan finns i WordPress och den kostsamma eller långvariga åtgärden bör ske asynkront.

## Exempel: granska innehåll när ett inlägg sparas

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

I det exemplet:

- `save_post` är fortfarande den ursprungliga WordPress-händelsen
- `map` omvandlar råa hook-argument till ett enkelt arbetsflödestillstånd
- `when` hoppar över oönskade händelser innan något läggs i kön
- `idempotency_key` förhindrar att upprepade hook-anrop skickar iväg dubbletter av körningar

## Vad som körs synkront

Själva åtgärdsåteranropet körs fortfarande i den aktuella WordPress-begäran.

Det innebär att följande delar är synkrona:

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

Det är bara arbetsflödesstegen som körs asynkront efter att de skickats iväg.

## Regler för nyttolasten

Mappade nyttolaster ska innehålla vanliga arrayer, skalärer och `null`.

Skicka inte råa WordPress-objekt, som `WP_Post`, direkt till arbetsflödestillståndet. Normalisera dem först i `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,
    ],
);
```

Nycklar som börjar med `_` avvisas eftersom de namnen är reserverade för internt arbetsflödestillstånd.

## Godkända argument

WordPress kräver ett antal `accepted_args` när ett åtgärdsåteranrop registreras.

Queuety härleder det som standard från dina återanrop för `map`, `when` och `idempotency_key`, så det vanliga fallet kräver ingen extra konfiguration:

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

Om du behöver åsidosätta detta manuellt skickar du med `accepted_args` uttryckligen:

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

## Inline-byggare för arbetsflöden

Du kan skicka iväg ett registrerat arbetsflödesnamn eller en inline-`WorkflowBuilder`.

Inline-byggare är användbara när det hook-specifika arbetsflödet definieras i samma bootstrap-fil:

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

## När detta passar bra

Använd åtgärdsutlösare när:

- WordPress redan skickar ut händelsen du bryr dig om
- svaret ska överleva tidsgränser för begäranden eller omstarter av arbetare
- uppföljningsarbetet kan förgrenas, vänta eller kräva godkännande
- upprepade hook-anrop kräver beständig idempotens

Använd i stället ett direkt anrop till `Queuety::dispatch()` eller `Queuety::workflow()` när arbetet inte är kopplat till en händelsegräns i WordPress.

## Inte för filter

`Queuety::on_action()` är avsiktligt begränsad till åtgärder.

Filter är synkrona omvandlingar vid begärandetillfället. De bör vanligtvis förbli synkrona eftersom WordPress förväntar sig att ett filtrerat värde returneras omedelbart.