# Тригери за действия

`Queuety::on_action()` ви позволява да превърнете обикновено действие WordPress в изпращане на устойчив работен процес.

Така получавате ясен мост:

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

Това е полезно, когато интересното събитие вече съществува в WordPress, а скъпият или продължителен отговор трябва да се изпълни асинхронно.

## Пример: преглед на съдържание при запазване на публикация

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

В този пример:

- `save_post` все още е първоначалното събитие WordPress
- `map` превръща суровите аргументи на хука в обикновено състояние на работния процес
- `when` пропуска нежеланите събития, преди да бъдат поставени на опашка
- `idempotency_key` не позволява повтарящи се извиквания на хука да изпращат дублирани изпълнения

## Какво се изпълнява синхронно

Самата функция за обратно извикване на действието продължава да се изпълнява в текущата заявка WordPress.

Това означава, че следните части са синхронни:

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

Само стъпките на работния процес се изпълняват асинхронно след изпращането.

## Правила за полезния товар

Съпоставените полезни товари трябва да съдържат обикновени масиви, скаларни стойности и `null`.

Не предавайте сурови обекти WordPress като `WP_Post` директно в състоянието на работния процес. Първо ги нормализирайте в `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,
    ],
);
```

Ключове, започващи с `_`, се отхвърлят, защото имената са запазени за вътрешното състояние на работния процес.

## Приети аргументи

WordPress изисква брой `accepted_args` при регистриране на функция за обратно извикване на действие.

Queuety го извежда по подразбиране от функциите ви за обратно извикване `map`, `when` и `idempotency_key`, така че обичайният случай не изисква допълнителна конфигурация:

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

Ако е необходимо ръчно задаване, подайте изрично `accepted_args`:

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

## Вградени конструктори на работен процес

Можете да изпратите регистрирано име на работен процес или вграден `WorkflowBuilder`.

Вградените конструктори са полезни, когато специфичният за хука работен процес е дефиниран в същия файл за начална настройка:

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

## Кога това е подходящо

Използвайте тригери за действия, когато:

- WordPress вече излъчва събитието, което ви интересува
- отговорът трябва да издържа на изтичане на времето за заявката или рестартиране на работника
- последващата работа може да се разклонява, изчаква или да изисква одобрение
- повтарящите се извиквания на хука изискват устойчива идемпотентност

Вместо това използвайте директно извикване на `Queuety::dispatch()` или `Queuety::workflow()`, когато работата не е свързана с граница на събитие WordPress.

## Не е за филтри

`Queuety::on_action()` умишлено е само за действия.

Филтрите са синхронни трансформации по време на заявката. Обикновено трябва да останат синхронни, защото WordPress очаква филтрираната стойност да бъде върната незабавно.