CakePHP 4 事件系统要求事件名必须为字符串常量，禁止拼接；监听器须实现 EventListenerInterface 或返回规范数组；dispatchEvent 同步执行，需注意性能与事务边界。
事件名必须用字符串常量，不能拼接
CakePHP 4 的事件系统靠 EventDispatcher 触发和监听，事件名是查找监听器的唯一键。一旦你用变量拼接（比如 'Model.afterSave.' . $entity->get('type')），就无法在配置里静态注册监听器，调试时也看不到完整事件路径。
常见错误现象：监听器没触发，但日志里又没报错；或者只在某个分支生效，换种数据就失效。
- 正确做法：定义清晰的事件常量，比如在
src/Event/EventName.php里声明public const AFTER_SAVE_USER = 'Model.afterSave.User'; - 触发时直接用
$this->dispatchEvent(EventName::AFTER_SAVE_USER, ['entity' => $user]); - 监听配置写在
config/events.php里，key 就是这个字符串常量，值是回调或监听器类名
监听器类必须实现 EventListenerInterface 或返回数组格式
CakePHP 4 不再接受任意闭包或函数作为监听器，必须显式声明接口或按约定返回结构化数组。否则 EventDispatcher 会跳过它，不报错也不执行。
使用场景：你在插件里封装通用逻辑（比如日志、通知），需要被主应用统一挂载。
立即学习“PHP免费学习笔记（深入）”；
- 推荐写法：新建类
src/Event/Listener/UserNotificationListener.php，implements EventListenerInterface，重写implementedEvents()返回关联数组 - 数组 key 是事件名（如
EventName::AFTER_SAVE_USER），value 是方法名（如'sendWelcomeEmail'） - 别把逻辑全塞进
implementedEvents()里——它只负责映射，实际处理要另写方法
dispatchEvent() 同步执行，别在循环里高频触发
所有监听器默认同步阻塞执行，没有队列或异步支持。如果在批量导入、导出或高并发请求中反复调用 dispatchEvent()，性能会明显下降，还可能引发事务锁或超时。
参数差异：dispatchEvent() 第二个参数是 $data 数组，建议只传必要字段，避免序列化大对象；第三个参数可选 $subject，用于绑定上下文（比如当前 Model 实例）。
- 批量场景下，改用“收集后统一触发”：先用
Collection::extract()提取关键 ID，再触发一次Model.afterBulkSave类事件 - 耗时操作（如发邮件、调外部 API）务必移到后台任务，监听器里只发消息到
Queue或写入 DB 待处理表 - 注意事务边界：监听器内抛异常会回滚整个事务，除非你手动
try/catch并明确忽略
插件事件监听需在 Plugin::routes() 之外注册
很多开发者以为在插件的 routes.php 或 bootstrap.php 里注册监听器就行，但 CakePHP 4 的事件系统初始化早于路由加载。如果监听器依赖未加载的类或配置，会直接失败且无提示。
兼容性影响：在 src/Application.php 的 bootstrap() 方法末尾注册最稳妥；若插件需独立启用/禁用，应在插件的 src/Plugin.php 的 bootstrap() 中注册，并检查 Configure::read('Plugins.MyPlugin.enabled')。
- 不要在
config/bootstrap.php里直接 new 监听器类——此时 DI 容器还没准备好，TableRegistry等服务不可用 - 监听器类构造函数里别做 heavy 初始化，改用 lazy getter 或
initialize()方法 - 测试时容易漏掉：单元测试跑得通，但功能测试里事件不触发——大概率是注册时机不对
