跳转到正文

操作触发器

以 Markdown 格式查看 在 GitHub 上编辑 文档位置 2cc7b2b

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。

不要将 WP_Post 之类的原始 WordPress 对象直接传入工作流状态。请先在 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 已经会发出你关注的事件
  • 响应需要在请求超时或工作进程重启后继续
  • 后续工作可能需要分支、等待或审批
  • 重复触发钩子时需要持久化幂等性

如果工作与 WordPress 事件边界无关，请改用直接的 Queuety::dispatch() 或 Queuety::workflow() 调用。

不适用于过滤器

Queuety::on_action() 有意仅用于操作。

过滤器是在请求期间同步执行的转换。它们通常应保持同步，因为 WordPress 需要立即返回经过过滤的值。