# Sprožilci dejanj

`Queuety::on_action()` vam omogoča, da običajno dejanje WordPress spremenite v trajen zagon poteka dela.

To omogoča preprosto povezavo:

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

To je uporabno, kadar zanimiv dogodek že obstaja v WordPress, odziv, ki zahteva veliko virov ali traja dolgo, pa naj se izvede asinhrono.

## Primer: pregled vsebine ob shranjevanju objave

```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 tem primeru:

- `save_post` je še vedno izvirni dogodek WordPress
- `map` spremeni surove argumente hooka v preprosto stanje poteka dela
- `when` prezre neželene dogodke, preden so dodani v čakalno vrsto
- `idempotency_key` prepreči, da bi ponavljajoči se klici hooka sprožili podvojene izvedbe

## Kaj se izvaja sinhrono

Sama povratna funkcija dejanja se še vedno izvaja znotraj trenutne zahteve WordPress.

To pomeni, da so ti deli sinhroni:

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

Asinhrono se po sprožitvi izvajajo samo koraki poteka dela.

## Pravila za koristni tovor

Preslikani koristni tovori naj vsebujejo preproste nize, števila in `null`.

Surovih objektov WordPress, kot je `WP_Post`, ne posredujte neposredno v stanje poteka dela. Najprej jih normalizirajte znotraj `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,
    ],
);
```

Zavrnjeni so ključi, ki se začnejo z `_`, saj so ta imena rezervirana za interno stanje poteka dela.

## Sprejeti argumenti

WordPress pri registraciji povratne funkcije dejanja zahteva število `accepted_args`.

Queuety ga privzeto določi na podlagi vaših povratnih funkcij `map`, `when` in `idempotency_key`, zato v običajnem primeru dodatna nastavitev ni potrebna:

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

Če ga želite ročno nastaviti, izrecno posredujte `accepted_args`:

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

## Sprotni gradniki potekov dela

Sprožite lahko registrirano ime poteka dela ali sprotni `WorkflowBuilder`.

Sprotni gradniki so uporabni, kadar je potek dela za določeni hook opredeljen v isti zagonski datoteki:

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

## Kdaj je to primerna rešitev

Sprožilce dejanj uporabite, kadar:

- WordPress že oddaja dogodek, ki vas zanima
- naj se odziv ohrani tudi po časovni omejitvi zahteve ali ponovnem zagonu delavca
- se lahko nadaljnje delo razveji, počaka ali zahteva odobritev
- je za podvojene klice hooka potrebna trajna idempotentnost

Namesto tega neposredno pokličite `Queuety::dispatch()` ali `Queuety::workflow()`, kadar delo ni povezano z mejo dogodka WordPress.

## Ni namenjeno filtrom

`Queuety::on_action()` je namenjen izključno dejanjem.

Filtri so sinhrone pretvorbe med obdelavo zahteve. Običajno naj ostanejo sinhroni, saj WordPress pričakuje, da bo filtrirana vrednost vrnjena takoj.