WordPress 钩子事件对象模式：do_action 传类型化对象的工程实践

WordPress 的 do_action() 传多个散参数时，参数顺序、参数个数、类型全靠人记；而 filter 链要求每个回调都 return，忘一个就静默出错。 WordPress 官方开发者博客 2026 年 8 月 3 日 Justin Tadlock 提出的解法很直接：传一个带类型的 PHP 事件对象，用对象自己的类名当 hook 名。上下文用只读属性，监听器可改的决策用可写属性——还是原来的 do_action()，不需要新框架。

传统写法到底有多容易出错

先看最常见的一个通知型 action：

do_action( 'myplugin_member_registered', $userId, $plan );

add_action( 'myplugin_member_registered', static function ( $userId, $plan ) {
    // ...
}, 10, 2 );

三个隐性契约：参数顺序必须一致、两边都要记住传了几个参数、回调必须显式写 10, 2（WordPress 默认不会把所有参数透传）。而且 $plan 是什么完全看不出来——字符串、 ID 还是对象，编辑器给不了任何提示。

filter 更麻烦一层：

$sendWelcomeEmail = apply_filters( 'myplugin_send_welcome_mail', true, $userId, $plan );

add_filter( 'myplugin_send_welcome_email', static function ( $send, $userId, $plan ) {
    if ( 'free' === $plan ) {
        $send = false;
    }
    return $send;
}, 10, 3 );

每个回调都必须返回处理后的值。忘写 return $send;，值就被吞成 null，后续整条链拿到错误结果，而且不报错。

顺带一提，上面这段原文里派发用的是 myplugin_send_welcome_mail，监听器用的是 myplugin_send_welcome_email——两个名字对不上，照抄不会触发。这看起来是原文笔误，实际用的时候必须统一。

核心模式：对象作 payload，类名作 hook

一句话概括作者的提议：

do_action( $event::class, $event );

为什么 ::class 能直接当 hook 名？因为它返回完整类名字符串：

namespace MyPlugin\Members;

final class MemberRegistered
{
    public function __construct(
        public readonly int    $userId,
        public readonly string $plan,
        public          bool   $sendWelcomeEmail = true,
    ) {}
}

那么 MemberRegistered::class 就是 MyPlugin\Members\MemberRegistered。 WordPress 的 do_action() 第一个参数就是字符串，完整类名直接可用，不需要任何特殊 API 。而且 PHP 里如果两个插件声明了完全相同的全限定类名，通常会在类加载时就报冲突；两个相同的普通字符串 hook 则可能静默共享错误的监听器——这是类名方案的一个真实优势。

两类属性的分工

这就是关键设计：把 filter 的返回值搬到了对象内部。监听器不再负责「返回下一个值」，而是修改共享对象上的一个决策字段。

派发端：do_action 之后读属性

namespace MyPlugin\Members;

final class MemberRegistrar
{
    public function register( int $userId, string $plan ): void
    {
        $event = new MemberRegistered( userId: $userId, plan: $plan );

        do_action( $event::class, $event );

        if ( $event->sendWelcomeEmail ) {
            // ...queue the welcome email.
        }
    }
}

整个流程里没有 apply_filters()，没有中间变量。do_action() 执行完，返回值被丢弃也不影响——真正被读的是对象属性的新状态。

监听端：一个事件两种姿态

观察型（不改，只记）

use MyPlugin\Members\MemberRegistered;

add_action( MemberRegistered::class, static function ( MemberRegistered $event ): void {
    error_log( sprintf(
        'Member #%d registered on the %s plan.',
        $event->userId,
        $event->plan
    ) );
} );

回调参数声明了具体类，$event->userId 直接有属性补全。日志、审计、统计、同步这类副作用行为走这条。

修改型（改决策字段）

use MyPlugin\Members\MemberRegistered;

add_action( MemberRegistered::class, function ( MemberRegistered $event ): void {
    // Free-plan members skip the paid welcome sequence.
    if ( 'free' === $event->plan ) {
        $event->sendWelcomeEmail = false;
    }
} );

不需要 return。就这么简单。

hook 名用类名还是固定字符串

这是作者给的唯一需要你做决定的地方，判断标准是一句话：你是否希望 hook 名永远不随代码重构而改变？

作者的推荐很明确：内部 hook 用类名，对外暴露的长期公共 API 用固定字符串，并且用类名时要配套 deprecation 流程。

迁移旧 hook 的风险清单

如果你是想把已有插件的散参数 hook 改成事件对象，下面几条必须提前处理：

七个必须知道的限制

原文里明确提到的，加上这种模式天然带来的：

1. 类名 hook 会随重构断裂，且无警告。
2. 旧 hook 的 payload 改动会破坏第三方。原本期望 function ( $userId, $plan ) 的回调，改成只传一个对象后可能不再执行，或收到类型完全不同的参数。
3. 对象是共享可变状态，最终结果受 priority 和执行顺序影响。
4. do_action() 不使用返回值。监听器只 return $event; 是无效的，必须改属性。
5. 类型安全不是 Core 强制执行的。do_action() 收 mixed。别人用同一个 hook 名派发另一种对象，错误只会在类型化回调真正执行时暴露。
6. $event::class 取的是运行时类名。允许继承时，子类会派发出不同的 hook 名。需要固定事件入口就显式写基类名。
7. 不是 PSR-14 事件系统。缺少传播控制、自定义 listener provider 、 subscriber 批量注册、可替换 dispatcher 。priority 和 remove_action() 只提供有限能力。

还有一条容易被忽略的：这不能当安全边界用。WordPress 里每个 hook 都是全局的，任何代码都能 add_action( 'MyPlugin\Members\MemberRegistered', $cb )。事件对象的可写字段只是插件间的协作协议，不是权限控制。

[h3]和 PSR-14 的关系[/h3]

作者把这个模式和 PSR-14 事件分发器做了对照：event 是携带信息的对象，listener 是响应的 callable，dispatcher 负责分发。 WordPress 的 do_action() / add_action() 在 2004 年插件 API 1.2 就有了核心模型，但缺少上面那四项正式事件系统能力。如果你的项目后面真的需要「让监听器叫停后续执行」「批量管理监听器」「测试时替换整个分发机制」，那时再上完整事件系统，别在今天用 do_action() 硬凑。

什么时候值得用，什么时候不值得

相关阅读

• Anthropic 提示词工程最佳实践——把边界和约束写清楚，同样是「约定优于强制」的思路。
• 区块图案在模板中复用——区块主题开发里另一类「约定 + 工具」协作模式。
• OpenAI Agents API 是什么——另一种事件驱动架构的对照参考。