# Toimintokäynnistimet

`Queuety::on_action()`-palvelulla voit muuttaa tavallisen kohteen WordPress toiminnon kestävän työnkulun käynnistykseksi.

Näin saat selkeän yhteyden:

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

Tästä on hyötyä, kun kiinnostava tapahtuma syntyy jo kohteessa WordPress ja kalliin tai pitkäkestoisen käsittelyn pitäisi tapahtua asynkronisesti.

## Esimerkki: tarkista sisältö, kun artikkeli tallennetaan

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

Tässä esimerkissä:

- `save_post` on edelleen alkuperäinen kohteen WordPress tapahtuma
- `map` muuntaa koukun raaka-argumentit tavalliseksi työnkulun tilaksi
- `when` ohittaa tarpeettomat tapahtumat ennen jonotusta
- `idempotency_key` estää toistuvia koukkukutsuja käynnistämästä päällekkäisiä suorituksia

## Mikä suoritetaan synkronisesti

Toiminnon takaisinsoittokoodi suoritetaan edelleen nykyisen kohteen WordPress pyynnön sisällä.

Tämä tarkoittaa, että seuraavat osat suoritetaan synkronisesti:

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

Vain työnkulun vaiheet suoritetaan asynkronisesti käynnistyksen jälkeen.

## Hyötykuorman säännöt

Kohdistettujen hyötykuormien tulee sisältää tavallisia taulukoita, skalaareja ja arvoja `null`.

Älä välitä raakamuotoisia WordPress-objekteja, kuten `WP_Post`, suoraan työnkulun tilaan. Normalisoi ne ensin kohteessa `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,
    ],
);
```

Avaimet, joiden alussa on `_`, hylätään, koska nimet on varattu työnkulun sisäiseen tilaan.

## Hyväksytyt argumentit

WordPress vaatii argumenttien määrän `accepted_args`, kun toimintokutsun takaisinsoitto rekisteröidään.

Queuety päättelee määrän oletuksena takaisinsoitoista `map`, `when` ja `idempotency_key`, joten tavallinen käyttötapaus ei vaadi lisäasetuksia:

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

Jos tarvitset manuaalisen ohituksen, välitä `accepted_args` nimenomaisesti:

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

## Työnkulkujen luonti suoraan koodissa

Voit käynnistää rekisteröidyn työnkulun nimen tai suoraan määritellyn kohteen `WorkflowBuilder`.

Suoraan määritellyt työnkulut ovat hyödyllisiä, kun koukkukohtainen työnkulku määritellään samassa käynnistystiedostossa:

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

## Milloin tämä sopii hyvin

Käytä toimintokäynnistimiä, kun:

- WordPress tuottaa jo tarvitsemasi tapahtuman
- käsittelyn pitäisi kestää pyyntöjen aikakatkaisut tai työntekijöiden uudelleenkäynnistykset
- jatkotyö voi haarautua, odottaa tai vaatia hyväksynnän
- toistuvien koukkukutsujen käsittelyyn tarvitaan pysyvä idempotenssi

Käytä sen sijaan suoraa `Queuety::dispatch()`- tai `Queuety::workflow()`-kutsua, kun työ ei liity kohteen WordPress tapahtumarajaan.

## Ei suodattimille

`Queuety::on_action()` on tarkoitettu vain toimintoihin.

Suodattimet ovat synkronisia pyyntöaikaisia muunnoksia. Niiden tulisi yleensä pysyä synkronisina, koska WordPress odottaa suodatetun arvon palautuvan heti.