用途
Valinor PHP 技能用于编写和修复基于 cuyz/valinor 库的 PHP 代码。它面向 Valinor 的公共 API，帮助开发者产出生产级质量的代码，并倾向于使用最小且正确的 Valinor 配置，将代码保持在公共接口层面。
核心立场
- 默认采用严格映射，仅在输入契约确实需要时才放宽规则。
- 优先使用精确的 PHP 与 PHPDoc 类型，而非
mixed或object。 - 优先使用公共入口点，例如
MapperBuilder、NormalizerBuilder、Mapper\Source\Source、Normalizer\Format、HttpRequest、AsConverter、AsTransformer和Object\Constructor。 - 将构建器视为不可变的配置对象：通过链式调用或重新赋值使用，不要假设会原地修改。
- 对于共享的应用策略，优先使用可复用的配置器。
- 避免使用
Library、Compiler、Definition等区域下的内部类或具体映射器内部实现。
按需阅读参考
技能提供按任务查阅的参考文件：
- 通用映射、构建器设置、缓存、公共 API：
references/api-surface.md - 选择精确类型与签名：
references/type-signatures.md - JSON/YAML/文件源、路径映射、自定义可迭代源：
references/source-shaping.md - 转换器、键重映射、构造器、接口推断、自定义错误：
references/customization.md - HTTP 请求映射、PSR-7 集成、源绑定属性：
references/http-request-mapping.md - 数组或 JSON 规范化与转换器：
references/normalization.md - 格式化、翻译与重映射验证消息：
references/error-messages-formatting.md - 静态分析插件、纯度、框架集成与升级说明：
references/static-analysis-and-integration.md - 根据用户请求选择实现模式：
references/common-use-cases.md - 调试映射失败或异常行为：
references/troubleshooting-workarounds.md
示例片段包括：examples/happy-path.md、examples/http-requests.md、examples/error-formatting.md、examples/production-safe.md、examples/anti-patterns.md。
工作流程
- 识别边界：对象映射、可调用参数、HTTP 请求映射、规范化或自定义。
- 加载与任务匹配的一到两个参考文件。
- 使用最窄的正确目标类型。
- 从严格默认值开始；仅在输入契约有正当理由时添加
allowScalarValueCasting()或allowSuperfluousKeys()等开关。 - 在预期会出现无效外部输入的应用边界处捕获
CuyZ\Valinor\Mapper\MappingError。 - 如果同一 Valinor 策略会被复用，将其提取为构建器配置器，而不是重复链式调用。
- 如果代码面向生产，在适当情况下添加缓存使用。
首选默认值
- 对于 JSON、YAML 和文件，优先使用
Mapper\Source\Source::json()、Source::yaml()和Source::file()。 - 对于新代码，优先使用提供的键大小写配置器，而非已弃用的源修饰符如
Source::camelCaseKeys()。 - 当重塑入站负载时，
Source::map()路径映射仍然有效；仅在新代码中避免已弃用的键大小写源修饰符。 - 当专用 DTO 不必要时，使用直接类型签名，如
'list<Foo>'或'array{status: non-empty-string, page?: positive-int}'。 - 当结构会被复用、承载领域含义或值得构造器验证时，使用 DTO 或值对象。
- 当具体实现取决于输入数据时，使用
infer()处理接口或抽象类多态。 - 当对象创建不是简单的构造器映射问题时，使用
registerConstructor()或#[Object\Constructor]。 - 使用
registerConverter()进行输入值转换，使用registerTransformer()进行输出规范化。 - 对于 HTTP 请求映射，记住路由和查询参数已支持标量转换，无需启用全局
allowScalarValueCasting()。
硬性规则
- 不要为应用代码推荐 Valinor 内部类。
- 不要为了让映射通过而静默放宽类型。
- 不要在没有明确理由的情况下全局启用宽松行为。
- 不要忘记自定义构造器、转换器、转换器和推断回调必须保持纯净且确定性。
交付检查清单
完成前，确保代码：
- 仅使用公共 Valinor API。
- 使用边界所需的精确类型签名。
- 对任何非默认的灵活性设置，用输入契约解释原因。
- 在可能出现无效外部输入的地方处理
MappingError。 - 避免已弃用模式，除非是在维护现有代码。
该技能是自包含的，在运行时应当足够使用。