Laravel Eloquent 本身不支持属性状态机，推荐使用 spatie/laravel-model-states：通过状态类封装、强制 transitionTo() 流转、自动校验与事件钩子，避免硬编码导致的失控、难测、不可审计问题。
PHP 中 Laravel 的 Eloquent 模型本身不内置“属性状态机”（Attribute State Machine）功能，State Machine 是业务逻辑层概念，不是 Eloquent 原生能力。直接在模型里用 $casts 或访问器/修改器硬编码状态流转，容易失控、难测试、无法审计——这不是“怎么写”，而是“怎么不踩坑地组织它”。
用 spatie/laravel-model-states 管理字段状态流转
这是目前最轻量、契约最清晰的方案：把状态封装成类，强制流转必须通过 transitionTo()，自动校验合法性，支持事件钩子和数据库持久化。
- 安装：
composer require spatie/laravel-model-states - 定义状态类，比如
PublishingState，继承State，每个常量对应一个状态值（如draft、published） - 在模型中使用
use HasStates;trait，并声明$stateField = 'status';（对应数据库字段名） - 调用
$post->publish();实际触发transitionTo(Published::class)，失败时抛出InvalidTransitionException - 状态类内部可重写
canTransitionTo()控制条件，比如“只有草稿才能发布”，避免在控制器里散落 if 判断
为什么不用 $casts + 访问器模拟状态机
常见错误是把状态字段 status 用 $casts = ['status' => 'string']，再配一堆 isDraft()、markAsPublished() 方法手动赋值。问题很实际：
- 没有流转路径约束：代码可以直接
$model->status = 'archived'; $model->save();，绕过所有业务规则 - 无法追溯变更：谁、何时、从什么状态变到什么状态？没日志、没事件、没快照
- 测试困难：状态逻辑分散在多个方法里，mock 成本高，边界 case 容易漏（比如重复发布、已归档再编辑）
- 迁移成本高：后期想加审批流或状态超时自动降级，得重写全部逻辑
自定义状态字段与数据库兼容性要点
spatie/laravel-model-states 默认要求状态字段是字符串类型，但实际项目中常遇到整数枚举或 JSON 字段存多状态。处理方式很明确：
立即学习“PHP免费学习笔记（深入）”；
- 整数状态码（如 0=draft, 1=published）：需自定义
State类的fromInt()和toInt()方法，并在模型中覆盖getStateValue()和setStateValue() - JSON 字段存复合状态（如
{"status": "reviewing", "reviewed_by": 123}）：不建议直接塞进状态机；应拆出主状态字段（status）用于流转，其余元数据走普通属性或关联模型 - MySQL enum 类型：不推荐。ORM 层难以映射变更，且迁移时 DDL 风险高；统一用
VARCHAR(20)更安全 - 注意迁移文件中字段长度：状态值如
'pending_review'超过默认 255 可能截断，显式设$table->string('status', 64)
状态变更前后需要拦截的典型场景
真实业务中，状态跳转从来不只是改个字段。spatie 包提供 transitioning、transitioned 事件，比在 saving 中判断更精准：
- 发送通知：在
transitioned事件里发邮件/SMS，只对真正成功的流转生效，不因验证失败或事务回滚误发 - 更新关联数据：比如从
published变为archived，需同步将published_at设为 null，或标记关联评论为只读 - 权限清理：用户取消订阅后，状态变为
cancelled，此时应主动调用revokePermissions()，而不是等下次请求时检查 - 避免在事件中做耗时操作：如调用外部 API，应 dispatch job 异步处理，防止阻塞主流程
状态机不是加个 trait 就完事。关键在于把“谁可以什么时候做什么”变成不可绕过的代码契约，而不是靠文档或 code review 约束。一旦状态流转逻辑开始出现在 controller、job、command 多个地方，就该立刻抽离——哪怕只有一处 $model->status = 'xxx' 直接赋值，就是破口。
