用途:本技能面向 Laravel 项目,指导使用 Spatie Laravel Data 包创建与维护数据传输对象(DTO),避免在层间传递多个原始值,统一以 Data 对象封装数据,从而获得类型安全、IDE 自动补全、清晰的层间契约、验证集成以及从请求到领域对象的转换能力。
主要能力与约定:优先使用 ::from() 配合数组,键名与构造函数属性名一致,由包根据属性类型自动完成类型转换(如字符串转 CarbonImmutable、转枚举、数组转 Collection)。避免使用 #[MapInputName] 等大小写映射属性,改为在调用代码中显式映射字段名。日期转换自动完成,需在 config/data.php 中配置 date_format。DTO 使用构造函数属性提升,所有属性显式声明类型,集合用 PHPDoc 标注泛型,支持嵌套 DTO。格式化逻辑放在构造函数中,例如 EmailFormatter、PhoneFormatter、PostcodeFormatter。小型应用可在 DTO 上添加 from{SourceType} 静态工厂方法(如 fromArray、fromRequest、fromModel);复杂转换使用独立 Transformer 类。模型可通过 casts() 将 JSON 列映射为 DTO。测试使用 HasTestFactory trait 与 testFactory() 生成水合 DTO,支持 make() 与 collect(count:)。
使用方式:控制器通过 Transformer 将请求转为 DTO 后传给 Action,Action 以 DTO 为参数执行领域逻辑。命名约定:响应 DTO 用 {Entity}Data,请求 DTO 用 {Action}{Entity}Data,嵌套 DTO 用 {Descriptor}{Entity}Data。目录结构建议 app/Data 下分 Concerns、Formatters、Transformers。
适用场景:Laravel 应用中需要结构化数据传递、请求到领域对象转换、外部 API 或 Webhook 数据映射、测试数据生成的场景。
限制:资料未提供该技能的安装命令、版本要求、收费信息或具体平台支持范围,这些事实暂未提供。使用前需自行确认 Spatie Laravel Data 包的官方文档与项目配置。