# Műveletindítók

A `Queuety::on_action()` segítségével egy szokásos WordPress műveletet tartós munkafolyamat-indítássá alakíthatsz.

Ez egyértelmű átjárót biztosít:

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

Ez akkor hasznos, ha az érdekes esemény már a WordPress rendszerben keletkezik, a költséges vagy hosszan futó műveletet pedig aszinkron módon kell végrehajtani.

## Példa: tartalom ellenőrzése bejegyzés mentésekor

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

A példában:

- A `save_post` továbbra is az eredeti WordPress esemény
- A `map` a nyers hookargumentumokat egyszerű munkafolyamat-állapottá alakítja
- A `when` még a sorba állítás előtt kiszűri a nem kívánt eseményeket
- A `idempotency_key` megakadályozza, hogy az ismétlődő hookhívások ismétlődő futtatásokat indítsanak

## Mi fut szinkron módon

Maga a művelet-visszahívás az aktuális WordPress kérésen belül fut le.

Ez azt jelenti, hogy ezek a részek szinkron módon futnak:

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

Csak az indítás után következő munkafolyamat-lépések futnak aszinkron módon.

## Adatcsomag-szabályok

A leképezett adatcsomagok csak egyszerű tömböket, skalárértékeket és `null` tartalmazhatnak.

Ne adj át nyers WordPress objektumokat, például `WP_Post` értékeket közvetlenül a munkafolyamat állapotának. Előbb normalizáld őket a `map()` elemen belül:

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

A `_` kezdetű kulcsokat a rendszer elutasítja, mert ezek a nevek a belső munkafolyamat-állapot számára vannak fenntartva.

## Elfogadott argumentumok

A WordPress megköveteli az `accepted_args` darabszámot a műveleti visszahívás regisztrálásakor.

Alapértelmezés szerint a Queuety az `map`, `when` és `idempotency_key` visszahívásokból állapítja meg ezt, így a szokásos esetben nincs szükség további beállításra:

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

Ha kézi felülbírálásra van szükséged, add meg explicit módon a `accepted_args` értékét:

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

## Beágyazott munkafolyamat-készítők

Regisztrált munkafolyamat-nevet vagy beágyazott `WorkflowBuilder` elemet is indíthatsz.

A beágyazott készítők akkor hasznosak, ha a hookra jellemző munkafolyamatot ugyanaz a rendszerindító fájl definiálja:

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

## Mikor illik ez jól a feladathoz

Akkor használd a műveletindítókat, ha:

- A WordPress már kibocsátja a számodra fontos eseményt
- A műveletnek túl kell élnie a kérés időtúllépését vagy a feldolgozó újraindítását
- Az utómunkának több ága lehet, várakozhat vagy jóváhagyást igényelhet
- Az ismétlődő hookhívásokhoz tartós idempotencia szükséges

Használj közvetlen `Queuety::dispatch()`- vagy `Queuety::workflow()`-hívást, ha a munka nem kötődik egy WordPress-esemény határához.

## Szűrőkhöz nem használható

A `Queuety::on_action()` szándékosan csak műveletekhez használható.

A szűrők szinkron, kérés közben végrehajtott átalakítások. Általában maradjanak szinkron módúak, mert a WordPress azonnali visszatérést vár a szűrt értéktől.