README

Ngexp/hydrator

概览

Ngexp/hydrator是一个库，允许您将数据填充到对象中。填充是将数据从数组或JSON等来源填充到对象中的过程。该库利用属性为过程添加额外的行为，例如将数据从一种类型转换为另一种类型、验证数据等。

该库需要PHP 8.1或更高版本，并支持严格的类型检查，同时仍允许混合数据类型。其一些功能包括：

✅ 修改和验证数据的各种属性
✅ 使用记忆化的反射进行可重用的填充以提高速度
✅ 通过新的属性和适配器扩展填充数据
✅ 能够进行任意深度的填充
✅ 可修改的错误信息
✅ 创建自定义属性简单

安装

要安装库的最新版本，请运行以下命令

composer require ngexp/hydrator

基本用法

以下是一个如何使用该库进行类填充的示例

<?php

declare(strict_types = 1);

require_once '../vendor/autoload.php';

use Ngexp\Hydrator\Adapters\JsonAdapter;
use Ngexp\Hydrator\Asserts as Assert;
use Ngexp\Hydrator\Hydrator;
use Ngexp\Hydrator\HydratorException;

// The data we want to hydrate the instance with.
$json = <<<JSON
{
  "name": "John Doe",
  "age": 20,
  "unrelated": "data"
}
JSON;

// The class has the same data structure as the json data.
class User
{
  public string $name;
  #[Assert\Min(30)]
  public int $age;
}

try {
  // We create a new instance of the class by specifying its class name.
  $hydrator = new Hydrator(User::class);
  // Hydrate using the json adapter.
  $class = $hydrator->hydrate(new JsonAdapter($json));

  var_dump($class);

} catch (HydratorException $e) {
  echo $e->getMessage();
}

填充器将创建类的新的实例，并用来自JSON数据的填充数据填充它。填充器还会验证数据，如果数据无效，则抛出异常。

它还会忽略类中未定义的任何属性，例如JSON数据中的unrelated属性。

作为演示，运行上面的代码将抛出HydrationException异常

Ngexp\Hydrator\Docs\User::age can not be less than 30, got 20.

在这个例子中，年龄属性有一个设置为30的最小验证属性，但JSON数据中年龄的值是20。

填充器需要严格的类型检查，但某些属性可以自动将值转换为特定类型，如果可能的话。例如，如果值是字符串，添加AutoCast属性将自动将其转换为整数。

#[AutoCast]
private int $age;

您也可以使用CoerceInt来缩小范围，两者都会在内部使用CoerceInt，因为属性类型是int。

#[CoerceInt]
private int $age;

构造函数不会被调用

当填充器实例化一个类时，它不会调用类构造函数。这意味着可以直接在构造函数中声明属性，而无需在实例化时提供数据。

class User
{
  public function __construct(public string $name, #[CoerceInt] public int $age)
  {
  }
}

从蛇形案例到驼峰案例

填充器还通过其适配器自动将蛇形属性名（例如，user_id到userId）转换为驼峰形式。

属性

不同的属性类型可用，限制属性限制了可以填充的内容，而填充属性则说明了如何填充。

限制属性

验证属性验证并约束输入值。

#[Email(message="Custom error message", errorCode="unique_error_code")]
private string $email;

请注意，约束属性按添加到类的顺序执行，因此请注意声明它们的顺序。您还可以在单个属性上使用多个约束属性以实现更复杂的验证。

所有约束在失败时都会返回一个错误代码作为错误消息的一部分，如果需要用自定义消息覆盖它，您可以在这里设置自己的唯一错误代码。如果需要，使用消息参数覆盖默认错误消息。

填充属性

填充属性定义了值在填充过程中应该如何转换。前面提到的AutoCast和CoerceInt属性是填充属性的例子。

您可以使用填充属性来自动将字符串转换为整数、浮点数或布尔值，或格式化日期和时间。其他填充属性可用于修剪字符串、删除HTML标签或应用自定义转换。

属性顺序很重要

需要注意的是，属性的顺序很重要。IHydratorAttribute接口可用于填充和验证，属性将按照添加的顺序执行。这使得具有灵活的验证和填充过程成为可能。

从不同的来源进行填充

填充器配备了两个适配器，用于从不同来源填充数据。

要从JSON源进行填充，请使用JsonAdapter

$class = $hydrator->hydrate(new JsonAdapter($json));

要从数组源进行填充，请使用ArrayAdapter

$class = $hydrator->hydrate(new ArrayAdapter($array));

ngexp / hydrator

维护者

详细信息