# Déclencheurs d’action

`Queuety::on_action()` vous permet de transformer une action WordPress ordinaire en lancement durable de workflow.

Cela vous offre un lien direct :

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

Cette approche est utile lorsque l’événement pertinent existe déjà dans WordPress et que le traitement coûteux ou de longue durée doit s’effectuer de façon asynchrone.

## Exemple : réviser le contenu à l’enregistrement d’un article

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

Dans cet exemple :

- `save_post` reste l’événement WordPress d’origine
- `map` transforme les arguments bruts du hook en état de workflow simple
- `when` ignore les événements indésirables avant leur mise en file d’attente
- `idempotency_key` empêche les déclenchements répétés du hook de lancer des exécutions en double

## Ce qui s’exécute de manière synchrone

Le callback de l’action lui-même s’exécute toujours dans la requête WordPress en cours.

Cela signifie que ces parties sont synchrones :

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

Seules les étapes du workflow s’exécutent de manière asynchrone après le déclenchement.

## Règles relatives à la charge utile

Les charges utiles mappées doivent contenir des tableaux simples, des scalaires et `null`.

Ne transmettez pas directement des objets WordPress bruts comme `WP_Post` à l’état du workflow. Normalisez-les d’abord dans `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,
    ],
);
```

Les clés commençant par `_` sont rejetées, car ces noms sont réservés à l’état interne du workflow.

## Arguments acceptés

WordPress exige un nombre d’`accepted_args` lors de l’enregistrement d’un callback d’action.

Queuety le déduit par défaut de vos callbacks `map`, `when` et `idempotency_key` ; le cas courant ne nécessite donc aucune configuration supplémentaire :

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

Si vous avez besoin d’une surcharge manuelle, transmettez explicitement `accepted_args` :

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

## Créateurs de workflow en ligne

Vous pouvez déclencher un workflow enregistré par son nom ou un `WorkflowBuilder` en ligne.

Les créateurs en ligne sont utiles lorsque le workflow propre au hook est défini dans le même fichier d’initialisation :

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

## Cas d’utilisation adaptés

Utilisez les déclencheurs d’action lorsque :

- WordPress émet déjà l’événement qui vous intéresse
- la réponse doit résister aux délais d’expiration des requêtes ou aux redémarrages des processus de travail
- le travail de suivi peut comporter des branches, attendre ou nécessiter une approbation
- les déclenchements répétés du hook doivent être rendus idempotents de façon durable

Utilisez plutôt un appel direct à `Queuety::dispatch()` ou `Queuety::workflow()` lorsque le travail n’est pas lié à une frontière d’événement WordPress.

## Pas pour les filtres

`Queuety::on_action()` est volontairement réservé aux actions.

Les filtres sont des transformations synchrones effectuées au moment de la requête. Ils doivent généralement rester synchrones, car WordPress attend que la valeur filtrée soit renvoyée immédiatement.