Symfony Workflow七大事件全解从Guard到Announce的状态流转钩子详解【免费下载链接】workflowProvides tools for managing a workflow or finite state machine项目地址: https://gitcode.com/gh_mirrors/workflo/workflowSymfony Workflow 组件提供了管理工作流与有限状态机的完整工具其核心亮点是贯穿状态流转全过程的7 大事件钩子Guard、Leave、Transition、Enter、Entered、Completed、Announce。无论是校验权限、记录审计日志还是推送业务通知都能在这七个时机精准介入。本文带你逐一拆解每个事件的触发时机、事件命名规则与监听方式帮你彻底吃透 Symfony Workflow 事件机制。一次状态流转的完整旅程 当你调用工作流的apply()方法执行一次转换transition时Symfony Workflow 会按固定顺序派发以下事件定义在 Workflow.php 中Guard守卫→Leave离开→Transition转换中→Enter进入→ 持久化 Marking →Entered已进入→Completed已完成→Announce公告七大事件的完整清单如下所有常量与别名映射集中在 WorkflowEvents.php#事件类事件名触发时机核心作用1GuardEventworkflow.guard转换前校验决定能不能转可阻断转换2LeaveEventworkflow.leave离开旧状态时记录正在离开哪3TransitionEventworkflow.transition转换进行中转换途中传递/修改上下文4EnterEventworkflow.enter进入新状态时记录正要进入哪5EnteredEventworkflow.entered进入后Marking已持久化确认状态已落库6CompletedEventworkflow.completed整个转换完成时收尾统计、埋点7AnnounceEventworkflow.announce转换完成后广播接下来还能做什么1️⃣ GuardEvent权限校验的第一道关卡Guard 事件是唯一拥有一票否决权的事件。在can()判断或apply()执行转换前Symfony Workflow 都会先派发 Guard 事件各监听器可以通过setBlocked()或addTransitionBlocker()阻断本次转换并附带失败原因——这些原因最终会汇总进NotEnabledTransitionException方便定位为什么转不了。事件类GuardEvent.php独有的isBlocked()/setBlocked()/getTransitionBlockerList()方法内置监听器GuardListener.php 会执行 YAML 中配置的守卫表达式GuardExpression.php表达式失败即添加 TransitionBlocker天然支持is_granted、is_valid等安全校验函数⚠️重点Guard 事件永远派发、无法禁用。构造函数中尝试屏蔽workflow.guard会直接抛出InvalidArgumentException见 Workflow.php。Guard 事件会派发三个粒度的事件名让你可以精确到某条转换workflow.guard—— 所有工作流的全部转换workflow.{工作流名}.guard—— 指定工作流workflow.{工作流名}.guard.{转换名}—— 指定工作流的指定转换2️⃣ LeaveEvent离开旧状态当对象即将离开当前状态但还没真正移出时触发。它会为每个源状态from place额外派发一条细粒度事件适合做离库前清理、快照保存这类操作。事件类LeaveEvent.php事件名workflow.leave、workflow.{工作流名}.leave以及按源状态派发的workflow.{工作流名}.leave.{状态名}3️⃣ TransitionEvent转换途中的传声筒转换正在进行、Marking 尚未持久化时触发。它是七大事件里唯一能写回上下文的事件——监听器通过setContext()修改后后续事件都能拿到新值常用于在转换途中注入审计人、时间戳等信息。事件类TransitionEvent.php独有setContext()方法事件名workflow.transition、workflow.{工作流名}.transition、workflow.{工作流名}.transition.{转换名}4️⃣ EnterEvent即将进入新状态与 Leave 相对对象即将进入新状态时触发同样会为每个目标状态to place派发细粒度事件适合做入场前准备资源的操作。事件类EnterEvent.php事件名workflow.enter、workflow.{工作流名}.enter、workflow.{工作流名}.enter.{状态名}5️⃣ EnteredEvent已稳稳进入新状态此时 Marking已经写入存储状态真正落定。一个容易忽略的细节getMarking()首次初始化对象时transition 为null也会派发 Entered 事件因此它是做对象首次进入工作流钩子的最佳位置。事件类EnteredEvent.php事件名workflow.entered、workflow.{工作流名}.entered、workflow.{工作流名}.entered.{状态名}初始状态下取初始状态名6️⃣ CompletedEvent一次转换彻底完成在 Entered 之后触发表示整个转换动作包括持久化已全部结束适合做耗时统计、指标埋点、发送状态已变更确认等收尾工作。事件类CompletedEvent.php事件名workflow.completed、workflow.{工作流名}.completed、workflow.{工作流名}.completed.{转换名}7️⃣ AnnounceEvent广播接下来还能做什么转换完成后Symfony Workflow 会计算对象当前所有可用的转换为每一条派发 Announce 事件。这是做动态渲染操作按钮、权限提示、进度通知的神器——前端下一步能点哪些按钮完全不用硬编码。事件类AnnounceEvent.php事件名workflow.announce、workflow.{工作流名}.announce、workflow.{工作流名}.announce.{可用转换名}三级事件命名规则把监听精准到某个状态除 Guard 外其余事件的派发规则统一遵循全局 → 工作流 → 具体目标三级粒度由 Workflow.php 中的leave()、enter()等方法实现层级事件名格式说明全局workflow.{事件}监听所有工作流的该事件工作流workflow.{工作流名}.{事件}只监听指定工作流细粒度workflow.{工作流名}.{事件}.{转换名/状态名}只监听某条转换或某个状态 技巧细粒度事件按**状态leave/enter/entered或转换transition/completed/announce**派发用对了粒度可以避免在监听器里写一堆if判断。快速编写监听器的三种方式 ✍️方式一PHP 8 属性Attribute最简洁Workflow 为每个事件都提供了专用属性事件名自动拼装见 BuildEventNameTrait.phpAsGuardListener.php —— 守卫监听按转换过滤AsEnterListener.php —— 进入监听按状态过滤同目录还有 AsLeaveListener.php、AsEnteredListener.php、AsCompletedListener.php、AsAnnounceListener.php、AsTransitionListener.php所有事件类都继承自 Event.php监听器中可用getSubject()拿到业务对象、getTransition()拿到转换、getWorkflowName()拿到工作流名、getMetadata()读取元数据。方式二事件订阅器实现EventSubscriberInterface在getSubscribedEvents()中声明事件名。项目内置的 AuditTrailListener.php 就是典范它订阅workflow.leave、workflow.transition、workflow.enter三个事件把每次状态流转写入日志直接注册为服务即可获得完整的审计追踪能力。方式三YAML 配置守卫表达式不写代码在 YAML 里为工作流声明guards表达式由 GuardListener.php 统一求值配合is_granted、is_valid即可实现无代码权限控制。性能调优按需开关事件 ⚡七大事件并非必须全部启用Workflow 构造函数Workflow.php提供两种控制手段构造函数eventsToDispatch参数传null默认派发全部事件传白名单如[workflow.transition, workflow.enter]只派发指定事件传黑名单如[!workflow.announce]屏蔽指定事件且未来新增事件默认派发白名单与黑名单不可混用屏蔽workflow.guard会抛异常apply()时的上下文标志如workflow_disable_leave_event等六个常量DISABLE_*_EVENT可在单次调用中临时关闭某事件适合高并发场景下的局部优化。总结事件一句话记忆Guard转不转听它的且无法禁用Leave我正在离开 ATransition路上可以捎带个消息Enter我正要进 BEntered我已经稳稳站在 B已落库Completed这次转换彻底结束了Announce接下来还能走这些路理解这七大事件及其三级命名规则你就能在 Symfony Workflow 中实现从权限守卫到动态按钮的完整业务闭环。更多定义细节可参考 Definition.php 与 Transition.php项目结构见 composer.json。【免费下载链接】workflowProvides tools for managing a workflow or finite state machine项目地址: https://gitcode.com/gh_mirrors/workflo/workflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考