¶

— 从平淡无奇的老式数组到令人眼前一亮的类型化对象 —

Valinor 负责将原始输入（JSON、普通数组等）构造成对象并进行验证，确保对象处于完全有效的状态。在整个应用生命周期内，都可以放心使用这些对象，无须担心其完整性。

验证系统会检测出所有不正确的值，并提供准确、易读的错误消息来帮助开发者。

映射器既能处理 PHP 原生类型，也能处理 [PHPStan] 和 [Psalm] 支持的其他高级类型，例如具有指定结构的数组、泛型和整数范围。

该库还提供了规范化机制，可在保留原始结构的同时，将任意输入转换为某种数据格式（JSON、CSV 等）。

为什么？¶

在代码库中使用对象代替普通数组有很多好处：

类型安全——对象的结构是已知的并得到保证，一旦对象被构造就不需要进行类型检查。
数据完整性——对象不能处于无效状态，它将始终包含有效数据。
封装——对象的逻辑与外部隔离。

如何进行序列化？¶

该库还提供了序列化系统，可在保留原始结构的同时，将给定输入转换为某种数据格式（JSON、CSV 等）。

您可以在规范化器章节中找到有关此主题的更多信息。

使用PHP 原生可以轻松实现验证原始数据并将其转换为对象，但需要大量样板代码。

下面是一个无需映射器即可完成此操作的简单示例：

final readonly class Person
{
    public string $name;

    public DateTimeInterface $birthDate;
}

$data = $client->request('GET', 'https://example.com/person/42')->toArray();

if (! isset($data['name']) || ! is_string($data['name'])) {
    // Cumbersome error handling
}

if (! isset($data['birthDate']) || ! is_string($data['birthDate'])) {
    // Another cumbersome error handling
}

$birthDate = DateTimeImmutable::createFromFormat('Y-m-d', $data['birthDate']);

if (! $birthDate instanceof DateTimeInterface) {
    // Yet another cumbersome error handling
}

$person = new Person($data['name'], $birthDate);

使用映射器可以节省大量时间和精力，特别是对于具有大量属性的对象：

$data = $client->request('GET', 'https://example.com/person/42')->toArray();

try {
    $person = (new \CuyZ\Valinor\MapperBuilder())
        ->mapper()
        ->map(Person::class, $data);
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Detailed error handling
}

该库为更复杂的情况提供了高级功能，请查看下一章以开始使用。