# Wyzwalacze akcji

`Queuety::on_action()` pozwala przekształcić zwykłą akcję WordPress w trwałe uruchomienie przepływu pracy.

Zapewnia to prosty most:

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

To przydatne, gdy interesujące zdarzenie już występuje w WordPress, a kosztowna lub długotrwała reakcja powinna odbyć się asynchronicznie.

## Przykład: weryfikacja treści po zapisaniu wpisu

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

W tym przykładzie:

- `save_post` nadal jest oryginalnym zdarzeniem WordPress
- `map` przekształca surowe argumenty hooka w zwykły stan przepływu pracy
- `when` pomija niepożądane zdarzenia, zanim cokolwiek zostanie umieszczone w kolejce
- `idempotency_key` zapobiega uruchamianiu duplikatów przy wielokrotnym wywołaniu hooka

## Co wykonuje się synchronicznie

Samo wywołanie zwrotne akcji nadal działa w ramach bieżącego żądania WordPress.

Oznacza to, że te elementy działają synchronicznie:

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

Tylko kroki przepływu pracy są wykonywane asynchronicznie po wysłaniu.

## Zasady dotyczące ładunku

Zmapowane ładunki powinny zawierać zwykłe tablice, wartości skalarne i `null`.

Nie przekazuj surowych obiektów WordPress, takich jak `WP_Post`, bezpośrednio do stanu przepływu pracy. Najpierw normalizuj je w `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,
    ],
);
```

Klucze zaczynające się od `_` są odrzucane, ponieważ te nazwy są zarezerwowane dla wewnętrznego stanu przepływu pracy.

## Akceptowane argumenty

WordPress wymaga podania liczby argumentów `accepted_args` podczas rejestrowania wywołania zwrotnego akcji.

Domyślnie Queuety ustala ją na podstawie wywołań zwrotnych `map`, `when` i `idempotency_key`, więc typowy przypadek nie wymaga dodatkowej konfiguracji:

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

Jeśli potrzebujesz ręcznego ustawienia, przekaż jawnie `accepted_args`:

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

## Kreatory przepływów pracy inline

Możesz wysłać zarejestrowaną nazwę przepływu pracy lub kreator inline `WorkflowBuilder`.

Kreatory inline są przydatne, gdy przepływ pracy zależny od hooka jest zdefiniowany w tym samym pliku rozruchowym:

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

## Kiedy to rozwiązanie się sprawdza

Używaj wyzwalaczy akcji, gdy:

- WordPress emituje już interesujące Cię zdarzenie
- odpowiedź powinna przetrwać przekroczenie limitu czasu żądania lub ponowne uruchomienie workera
- dalsze zadania mogą się rozgałęziać, czekać lub wymagać zatwierdzenia
- wielokrotne wywołania hooka wymagają trwałej idempotencji

Zamiast tego użyj bezpośredniego wywołania `Queuety::dispatch()` lub `Queuety::workflow()`, jeśli zadanie nie jest powiązane z granicą zdarzenia WordPress.

## Nie dotyczy filtrów

`Queuety::on_action()` celowo obsługuje wyłącznie akcje.

Filtry to synchroniczne przekształcenia wykonywane podczas żądania. Zwykle powinny pozostać synchroniczne, ponieważ WordPress oczekuje natychmiastowego zwrócenia przefiltrowanej wartości.