# Activadores de acciones

`Queuety::on_action()` permite convertir una acción normal de WordPress en el inicio de un flujo de trabajo duradero.

Esto crea un puente sencillo:

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

Resulta útil cuando el evento que importa ya existe en WordPress y la respuesta costosa o de larga duración debe ejecutarse de forma asíncrona.

## Ejemplo: revisar el contenido al guardar una entrada

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

En ese ejemplo:

- `save_post` sigue siendo el evento WordPress original
- `map` convierte los argumentos sin procesar del hook en un estado de flujo de trabajo simple
- `when` omite los eventos no deseados antes de poner nada en cola
- `idempotency_key` evita que las activaciones repetidas del hook inicien ejecuciones duplicadas

## Qué se ejecuta de forma síncrona

La propia función de retorno de llamada de la acción sigue ejecutándose dentro de la solicitud actual de WordPress.

Eso significa que estas partes son síncronas:

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

Solo los pasos del flujo de trabajo se ejecutan de forma asíncrona después del envío.

## Reglas de la carga útil

Las cargas útiles asignadas deben contener matrices simples, escalares y `null`.

No pase objetos WordPress sin procesar como `WP_Post` directamente al estado del flujo de trabajo. Normalícelos primero dentro de `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,
    ],
);
```

Se rechazan las claves que empiezan por `_` porque esos nombres están reservados para el estado interno del flujo de trabajo.

## Argumentos aceptados

WordPress requiere un recuento de `accepted_args` al registrar una función de retorno de llamada de una acción.

De forma predeterminada, Queuety lo deduce de sus funciones de retorno de llamada `map`, `when` y `idempotency_key`, así que el caso habitual no requiere configuración adicional:

```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 necesita anularlo manualmente, pase `accepted_args` explícitamente:

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

## Creadores de flujos de trabajo en línea

Puede enviar el nombre de un flujo de trabajo registrado o un `WorkflowBuilder` en línea.

Los creadores en línea son útiles cuando el flujo de trabajo específico del hook se define en el mismo archivo de arranque:

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

## Cuándo conviene usarlo

Use activadores de acciones cuando:

- WordPress ya emite el evento que le interesa
- la respuesta debe sobrevivir a los tiempos de espera agotados de las solicitudes o a los reinicios de los procesos de trabajo
- el trabajo posterior puede bifurcarse, esperar o requerir aprobación
- las activaciones duplicadas del hook requieren idempotencia duradera

Use una llamada directa a `Queuety::dispatch()` o `Queuety::workflow()` cuando el trabajo no esté vinculado a un límite de evento de WordPress.

## No se aplica a filtros

`Queuety::on_action()` está diseñado intencionadamente solo para acciones.

Los filtros son transformaciones síncronas durante la solicitud. Por lo general, deben seguir siendo síncronos, porque WordPress espera que el valor filtrado se devuelva de inmediato.