自定义事件必须用类封装并继承Event，通过dispatch()传实例触发；监听器靠自动发现或event_listener标签注册，不可手动addListener。
直接说结论：自定义事件必须用类封装、必须通过 EventDispatcherInterface 的 dispatch() 触发，不能只传字符串事件名；监听器注册靠自动发现或显式打 event_listener 标签，不手动调 addListener()。
怎么写一个可被调度的自定义事件类
事件类不是随便起个名字就行，它得是 PHP 对象，继承 Symfony\Contracts\EventDispatcher\Event（推荐）或 Symfony\Component\EventDispatcher\Event（旧版兼容）。关键点是：它要携带业务数据，且不能依赖构造函数参数以外的方式传值。
- 事件名建议用常量定义，如
public const NAME = 'user.registered';，避免拼写错误和魔法字符串 - 不要在事件类里做业务逻辑，只负责“带什么数据过去”——比如
getUser()、getOrder()这样的 getter 方法 - 别继承
AbstractEvent或自己搞静态方法分发，Symfony 5.4+ 已弃用这类写法 - 示例：
// src/Event/UserRegisteredEvent.php namespace App\Event; <p>use Symfony\Contracts\EventDispatcher\Event;</p><p>class UserRegisteredEvent extends Event { public const NAME = 'user.registered';</p><pre class='brush:php;toolbar:false;'>public function __construct(private \App\Entity\User $user) {} public function getUser(): \App\Entity\User { return $this->user; }}
监听器注册方式选哪个：自动发现 vs 手动打标签
自动发现（autowire + autoconfigure）最省事，但容易漏配或误配；手动打 event_listener 标签最可控，尤其适合多环境或需精细控制优先级的场景。
- 自动发现要求监听器类方法名匹配事件名规则（如
onUserRegistered），且类必须有__invoke()或明确的方法签名，否则不生效 - 手动配置更可靠：
# config/services.yaml services: App\EventListener\SendWelcomeEmailListener: tags: [{ name: 'event_listener', event: 'user.registered', method: 'onUserRegistered' }] - 如果监听器要响应多个事件，优先用
EventSubscriberInterface，避免一堆重复标签 - 注意：自动发现默认只扫描
src/EventListener/目录，路径不对就根本不会加载
dispatch() 调用位置和参数陷阱
dispatch() 必须传入事件对象实例，不能只传事件名字符串——这是新手最常踩的坑。传错会导致监听器收不到事件，且无报错，极难排查。
- 正确写法：
$dispatcher->dispatch(new UserRegisteredEvent($user)); - 错误写法：
$dispatcher->dispatch('user.registered');（Symfony 6+ 已废弃，5.4 会警告） - 事件对象必须在业务逻辑完成之后、事务提交前 dispatch，否则监听器中操作数据库可能因事务回滚而失效
- 如果事件需要跨服务边界（比如从命令行触发），确保
EventDispatcherInterface已注入，别用静态调用或全局容器访问
为什么监听器没执行？常见静默失败点
事件没触发成功，往往不是代码写错，而是环境或配置层面被忽略。
- 检查服务是否启用：运行
bin/console debug:event-dispatcher user.registered，看是否有监听器列出 - 确认事件名完全一致——大小写、点号、空格都算不同事件，
user.registered和user_registered是两个事件 - 监听器类没加
final？PHP 8.2+ 下非final类若被代理（如 AOP、缓存），可能破坏类型推导导致监听失败 - 开发环境下开了 OPcache 且没清理？改了监听器代码但没重启 Web server 或 CLI 进程，旧字节码还在跑
真正麻烦的从来不是“怎么写”，而是“为什么没进监听器”。把 debug:event-dispatcher 当成第一排查工具，比翻日志快得多。
