# Declanșatoare pentru acțiuni

`Queuety::on_action()` vă permite să transformați o acțiune obișnuită WordPress într-o lansare durabilă a unui flux de lucru.

Astfel obțineți o punte clară:

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

Acest lucru este util când evenimentul relevant există deja în WordPress, iar răspunsul costisitor sau de lungă durată trebuie executat asincron.

## Exemplu: revizuirea conținutului la salvarea unei postări

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

În acest exemplu:

- `save_post` rămâne evenimentul WordPress original
- `map` transformă argumentele brute ale hook-ului în starea simplă a fluxului de lucru
- `when` omite evenimentele nedorite înainte să fie puse în coadă
- `idempotency_key` împiedică declanșările repetate ale hook-ului să lanseze execuții duplicate

## Ce rulează sincron

Callback-ul acțiunii rulează în continuare în cadrul cererii WordPress curente.

Asta înseamnă că următoarele părți sunt sincrone:

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

Doar pașii fluxului de lucru rulează asincron după trimitere.

## Reguli pentru payload

Payload-urile mapate trebuie să conțină array-uri simple, valori scalare și `null`.

Nu pasați obiecte brute WordPress, precum `WP_Post`, direct în starea fluxului de lucru. Normalizați-le mai întâi în `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,
    ],
);
```

Cheile care încep cu `_` sunt respinse, deoarece aceste nume sunt rezervate pentru starea internă a fluxului de lucru.

## Argumente acceptate

WordPress necesită un număr de `accepted_args` la înregistrarea unui callback de acțiune.

În mod implicit, Queuety îl deduce din callback-urile `map`, `when` și `idempotency_key`, așa că nu este nevoie de configurare suplimentară în cazul obișnuit:

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

Dacă aveți nevoie de o suprascriere manuală, pasați explicit `accepted_args`:

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

## Constructori inline de fluxuri de lucru

Puteți trimite numele unui flux de lucru înregistrat sau un `WorkflowBuilder` inline.

Constructorii inline sunt utili când fluxul de lucru specific hook-ului este definit în același fișier de inițializare:

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

## Când este potrivit

Folosiți declanșatoarele de acțiune când:

- WordPress emite deja evenimentul care vă interesează
- răspunsul trebuie să reziste expirării cererii sau repornirii proceselor worker
- activitățile ulterioare pot urma ramuri, pot aștepta sau pot necesita aprobare
- declanșările duplicate ale hook-ului trebuie să fie idempotente în mod persistent

Folosiți direct un apel `Queuety::dispatch()` sau `Queuety::workflow()` când activitatea nu este legată de limita unui eveniment WordPress.

## Nu pentru filtre

`Queuety::on_action()` este conceput exclusiv pentru acțiuni.

Filtrele sunt transformări sincrone, efectuate în timpul cererii. De regulă, ar trebui să rămână sincrone, deoarece WordPress se așteaptă să primească imediat o valoare filtrată.