Symfony状态机需装symfony/workflow组件、配config/packages/workflow.yaml、实体字段名类型初始值与配置一致；通过$workflow->apply()触发转换，$workflow->can()预判但不保证成功。
Symfony状态机用起来不难，关键在三点：装对组件、配对YAML、实体字段对得上。它不是装完就能跑的“黑盒”，而是靠明确的状态定义 + 严格的转换校验来保障业务逻辑不越界。
安装与启用组件
别用 composer install，直接执行：
-
composer require symfony/workflow—— 这会拉取最新稳定版（如 v6.4），并自动注册基础服务 - 确保项目已启用
Symfony\Bundle\FrameworkBundle\FrameworkBundle（绝大多数 Symfony 应用默认已启用） - 不依赖 FrameworkBundle 的极简项目，需手动注册
WorkflowExtension，但非常规场景
写对 workflow.yaml 配置
配置文件必须放在 config/packages/workflow.yaml，名字和路径都不能错。最小可用示例如下：
- 顶层键必须是
framework:→workflows:，不能顶格写workflows: - 每个 workflow 必须声明
type: state_machine -
marking_store要匹配实体字段名，比如设为['currentState']，实体里就得有public string $currentState = 'draft'; -
supports列出能被该状态机管理的类全名，如- App\Entity\Order -
places是所有合法状态名（字符串数组），transitions的from和to必须严格来自其中
实体类与状态变更操作
状态变更不是改属性值，而是调用 Workflow::apply() 方法：
- 实体无需实现接口，但字段名、类型（必须是
string）、初始值要和配置一致 - 不要手动赋值
$order->currentState = 'shipped'，否则数据库和状态机脱节 - 正确流程：
$workflow->apply($order, 'ship');→ 检查通过后自动更新字段 → 再调用$entityManager->flush() - 用
$workflow->can($order, 'ship')可提前判断是否允许触发，但它不保证apply()一定成功（guard 或事件监听器仍可能中断）
排查常见报错
最典型的是 "Transition 'xxx' does not exist"：
- 先确认当前对象的
currentState值（比如是'pending'），再看shiptransition 的from是否包含它 - 检查大小写和空格——
'Pending'和'pending'是两个不同状态 - 多个 workflow 共存时，别用
$registry->get($order)，显式传 name：$registry->get($order, 'order_main_workflow') - Guard 函数返回
false会静默拦截，建议开头加日志输出，或测试时临时注释掉
