Download the PHP package hongxunpan/simple-event without Composer

simple-event

hongxunpan/simple-event 是面向 hongxunpan/simple-framework 的事件 Module。

它提供：

• 同步监听器；
• 可选的 Redis Streams 异步监听器；
• 严格 Event 快照和持久化协议；
• best-effort 监听器；
• Worker、失败摘要与监听器白名单；
• framework 应用生命周期适配；
• Module 启用后加载的 event()。

同步模式不依赖 Redis。只有选择 RedisStreamDriver 时才需要安装并启用 hongxunpan/simple-redis。

安装与启用

Composer 只负责安装包。event()、Provider 和生命周期适配只有在 Event Module 启用后才进入 应用运行时。

定义事件与监听器

Event

Event 表达已经发生的业务事实快照：

约束：

• Event 必须是 final readonly；
• 构造参数必须与公开实例属性一一对应；
• 未声明 VERSION 时默认为 1；
• 快照字段只允许标量、null、BackedEnum 和 DateTimeImmutable；
• 不允许携带 ORM Model、Request、Service、数组或任意对象。

监听器

同步监听器：

异步监听器实现 ShouldQueue：

监听器的 handle() 必须：

• 是公开实例方法；
• 只接收一个参数；
• 参数类型精确等于配置中的 Event；
• 显式返回 void。

分发与消费

同步配置

项目 config/events.php：

触发：

同步监听器按配置顺序执行。普通同步监听器异常会原样向上传播，并停止后续监听器。

best-effort

明确允许失败且不应污染调用链的监听器可以实现：

best-effort 异常会交给 ListenerFailureReporter，但不会阻断后续监听器。 项目可以通过 Provider 覆盖该契约。

Redis Streams

安装并启用 Redis Module：

config/redis.php 只保存连接配置：

config/events.php 保存 Event Driver 配置：

Redis host、认证、TLS、database 和 prefix 属于 Redis Module；stream、group、批次、 pending 回收和 failed stream 属于 Event Driver。两个配置边界不能混用。

RedisStreamDriver 不读取或编辑 module.enable，只校验 Redis 公开类型、容器绑定与所选 命名连接。通常由已启用的 Redis Module 提供这些运行时能力；项目若替换 Redis Provider， 也必须完整提供相同公开绑定。

Worker

单轮消费：

持续运行：

信号处理、命令退出码和 Supervisor/systemd 配置由项目负责。

Redis Streams 使用 at-least-once 语义：

• ACK 前退出时整条事件消息可能重新执行；
• 所有异步监听器必须幂等；
• 普通异步监听器失败后，整条消息写入 failed stream；
• XACK 成功后，XDEL 失败只留下可清理残留，不重新执行消息；
• 消息内监听器必须是当前 Event 已登记异步监听器的子集。

Worker 执行上下文

EventExecutionContext 是容器单例，用于暴露当前正在处理的异步消息事实。监听器和项目级失败 Reporter 执行期间可以读取：

• message_id
• event_id
• trace_id
• event_class
• listener_class

Worker 会在每条消息开始时建立上下文，并在 ACK、失败转存或异常结束后通过 finally 清空；上下文不能作为业务数据存储，也不能跨消息保留。

项目覆盖 TraceIdProvider 时可使用 FrameworkRequestTraceIdProvider：HTTP 发布 Event 时沿用 framework Request ID，Worker 内再次发布 Event 时沿用当前消息的 trace ID。

项目覆盖

项目 Provider 可以覆盖：

• EventConfigLoader
• TraceIdProvider
• ListenerFailureReporter
• Serializer
• Driver

默认 Loader 只读取 config/events.php。若项目不希望使用 events 作为配置名称，应覆盖 EventConfigLoader，不要在包内增加旧键兼容或项目专用回退。

生命周期

Event Module 会把 framework 的：

• RequestHandledSnapshot
• ExceptionOccurredSnapshot

转换为 Event Module 自己的生命周期事件。framework core 不引用 simple-event，也不会直接调用 event()。

验证

共享工作区使用：

当前开发线要求 PHP ^8.5。