类型的严格性与灵活性¶

该库提供的映射器设计得尽可能严格。任何与预期类型或结构的偏差都会导致映射错误。

标量类型仅接受与其类型严格匹配的值。
对象只接受可以映射到其构造函数参数的值，不需要的数组条目将导致映射错误。
数组和列表仅接受与其子类型和结构严格匹配的值。

像mixed或object这样的类型过于宽松，是不允许的，因为它们不够精确。

如果这些限制过于严格，则可以使映射器更灵活地禁用上面声明的一个或多个规则。

允许标量值转换¶

启用此设置后，标量类型将接受可转换值：

整数类型将接受任何有效的数值，例如字符串值"42" 。
浮点类型将接受任何有效的数值，例如字符串值"1337.42" 。
字符串类型将接受任何实现Stringable接口的整数、浮点数或对象。
布尔类型将接受任何真值或假值：
- (string) "true" 、 (string) "1"和(int) 1将被转换为true
- (string) "false" 、 (string) "0"和(int) 0将被转换为false

(new \CuyZ\Valinor\MapperBuilder())
    ->allowScalarValueCasting()
    ->mapper()
    ->map('array{id: string, price: float, active: bool}', [
        'id' => 549465210, // Will be cast to string
        'price' => '42.39', // Will be cast to float
        'active' => 1, // Will be cast to bool
    ]);

注意

此设置放宽了映射器处理的每个标量值的严格性。为了更好地控制，标量转换配置器转换单个属性或给定类型的每个值，而不会立即放松所有标量的规则。

允许非顺序列表¶

默认情况下，列表类型仅接受从 0 开始的连续键。

此设置允许映射器将关联数组转换为具有顺序键的列表。

(new \CuyZ\Valinor\MapperBuilder())
    ->allowNonSequentialList()
    ->mapper()
    ->map('list<int>', [
        'foo' => 42,
        'bar' => 1337,
    ]);

// => [0 => 42, 1 => 1337]

注意

此设置将每个映射到列表的关联数组转换。要改为针对单个属性，可以将MapArrayToList配置器作为特性应用。

允许未定义的值¶

允许映射器接受未定义的值（输入中缺少），方法是将它们转换为null （如果当前类型可为 null）或空数组（如果当前类型是对象或可迭代对象）。

(new \CuyZ\Valinor\MapperBuilder())
    ->allowUndefinedValues()
    ->mapper()
    ->map('array{name: string, age: int|null}', [
        'name' => 'John Doe',
        // 'age' is not defined
    ]);

// => ['name' => 'John Doe', 'age' => null]

允许多余的键¶

默认情况下，当源数组包含与类属性/参数或指定结构的数组元素不匹配的键时，会引发错误。

此设置允许映射器忽略这些多余的键。

(new \CuyZ\Valinor\MapperBuilder())
    ->allowSuperfluousKeys()
    ->mapper()
    ->map('array{name: string, age: int}', [
        'name' => 'John Doe',
        'age' => 42,
        'city' => 'Paris', // Will be ignored
    ]);

允许宽松类型¶

允许在映射期间使用mixed的许可类型和object 。

(new \CuyZ\Valinor\MapperBuilder())
    ->allowPermissiveTypes()
    ->mapper()
    ->map('array{name: string, data: mixed}', [
        'name' => 'some_product',
        'data' => 42, // Could be any value
    ]);