# Veiksmų paleidikliai

`Queuety::on_action()` leidžia įprastą WordPress veiksmą paversti patvariu darbo eigos iškvietimu.

Taip sukuriama aiški jungtis:

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

Tai naudinga, kai svarbus įvykis jau vyksta WordPress, o brangiai kainuojantis arba ilgai trunkantis atsakas turi būti vykdomas asinchroniškai.

## Pavyzdys: turinio peržiūra išsaugojus įrašą

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

Šiame pavyzdyje:

- `save_post` tebėra pradinis WordPress įvykis
- `map` neapdorotus kabliuko argumentus paverčia paprasta darbo eigos būsena
- `when` praleidžia nepageidaujamus įvykius, kol jie dar neįtraukti į eilę
- `idempotency_key` neleidžia pakartotinai suveikusiems kabliukams išsiųsti pasikartojančių paleidimų

## Kas vykdoma sinchroniškai

Pats veiksmo atgalinis iškvietimas vis dar vykdomas dabartinės WordPress užklausos metu.

Tai reiškia, kad šios dalys vykdomos sinchroniškai:

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

Asinchroniškai po iškvietimo vykdomi tik darbo eigos žingsniai.

## Naudingojo turinio taisyklės

Susietą naudingąjį turinį turėtų sudaryti paprasti masyvai, skaliarai ir `null`.

Nepersiųskite neapdorotų WordPress objektų, pvz., `WP_Post`, tiesiai į darbo eigos būseną. Pirmiausia normalizuokite juos `map()` viduje:

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

Raktai, prasidedantys `_`, atmetami, nes šie pavadinimai rezervuoti vidinei darbo eigos būsenai.

## Priimami argumentai

Registruojant veiksmo atgalinio iškvietimo funkciją, WordPress reikia nurodyti `accepted_args` skaičių.

Pagal numatytuosius nustatymus Queuety jį nustato pagal jūsų `map`, `when` ir `idempotency_key` atgalinio iškvietimo funkcijas, todėl įprastu atveju papildomos konfigūracijos nereikia:

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

Jei reikia rankiniu būdu nustatyti kitą reikšmę, aiškiai perduokite `accepted_args`:

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

## Įterptieji darbo eigos kūrimo įrankiai

Galite iškviesti registruotos darbo eigos pavadinimą arba įterptąjį `WorkflowBuilder`.

Įterptieji kūrimo įrankiai naudingi, kai konkrečiam kabliukui skirta darbo eiga apibrėžta tame pačiame paleidimo faile:

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

## Kada tai tinka

Veiksmų paleidiklius naudokite, kai:

- WordPress jau sukuria jums svarbų įvykį
- atsakas turi atlaikyti užklausos skirtąjį laiką arba darbuotojo paleidimą iš naujo
- tolesnis darbas gali išsišakoti, laukti arba reikalauti patvirtinimo
- pasikartojantiems kabliuko suveikimams reikia patvaraus apdorojimo tik vieną kartą

Vietoj to tiesiogiai iškvieskite `Queuety::dispatch()` arba `Queuety::workflow()`, kai darbas nesusijęs su WordPress įvykio riba.

## Netinka filtrams

`Queuety::on_action()` sąmoningai skirtas tik veiksmams.

Filtrai sinchroniškai transformuoja užklausas. Paprastai jie turi veikti sinchroniškai, nes WordPress tikisi, kad filtruota reikšmė bus grąžinta iš karto.