README

归一化组件允许轻松地将复杂对象图归一化到原始数组的数组，以便进行持久化。

基本上，它使得将 POPO 转换为人类可读的、平台无关的原始序列化数组变得容易。

它可以用于

• 以支持 PHP 数组和原始数据类型的任何格式进行序列化。
• 将对象导出到 SQL 数据库，无需使用 ORM。
• 将复杂对象图导出到文档存储。
• 从序列化表示形式加载内存中的对象。
• 将 HTTP 请求转换为类型对象。

安装

用法

让我们以一个对象图为例

class Project 
{
    /** @var string */
    private $id;
    
    /** @var string */
    private $title;
    
    /** @var string */
    private $description;
    
    /** @var Task[] */
    private $tasks;
    
    // ...
}

class Task 
{
    /** @var string */
    private $id;
    
    /** @var string */
    private $name;
    
    /** @var DateTime */
    private $dueDate;
    
    /** @var bool */
    private $completed;
    
    // ...
}

以下是归一化对象的方法

use Morebec\Orkestra\Normalization\ObjectNormalizer;$project = new Project('prj123456789', 'A new Project', 'This is our latest project');
$project->addTask(new Task('tsk123456789', 'Deploy to production', $dueDate));

// Normalize
$normalizer = new ObjectNormalizer();
$data = $normalizer->normalize($project);

print_r($data);
// Would print:
[
    'id' => 'prj123456789',
    'title' => 'A new Project',
    'description' => 'This is our latest project',
    'tasks' => [
        [
            'id' => 'tsk123456789',
            'name' => 'Deploy to production',
            'dueDate' => '2021-01-01T10:25:55+00:00',
            'completed' => false
        ]       
    ]
];

这种最后的表示可以轻松地序列化为 json、xml、yaml 或其他任何格式。

反归一化

以下是将归一化对象转换回其实例的方法

// Would print:
use Morebec\Orkestra\Normalization\ObjectNormalizer;$data = [
    'id' => 'prj123456789',
    'title' => 'A new Project',
    'description' => 'This is our latest project',
    'tasks' => [
        [
            'id' => 'tsk123456789',
            'name' => 'Deploy to production',
            'dueDate' => '2021-01-01T10:25:55+00:00',
            'completed' => false
        ]       
    ]
];
$normalizer = new ObjectNormalizer();
$project = $normalizer->denormalize($data, Project::class);

反归一化过程通过反射检查对象的结构。为了知道将值归一化为什么类型，归一化器会检查 PHP < 7.4 的对象上的 @var 注释，或 PHP >= 7.4 的声明类型。因此，如果使用较旧的 PHP 版本，正确声明 @var 注释非常重要。

自定义归一化器/反归一化器。

根据您对象的结构，您可能希望个性化它们（反）归一化的方式。一个常见的例子是使用包装原始数据类型的值对象。

class Username {

    /** @var string */    
    private $value;

    public function __construct(string $value) {
        $this->value = $value;
    }
    
    public function __toString()
    {
        return $this->value;
    }
}

这样的对象默认归一化如下

[
    'value' => 'the_username'
];

对于这样的对象，尤其是在它们是对象图的一部分时，您可能希望将它们归一化为它们所包装的原始类型，例如。

要执行此操作，您需要指定自定义归一化器/反归一化器对并将其添加到您的归一化器中

use Morebec\Orkestra\Normalization\Denormalizer\DenormalizationContextInterface;
use Morebec\Orkestra\Normalization\ObjectNormalizer;
use Morebec\Orkestra\Normalization\Normalizer\ObjectNormalizer\FluentNormalizer;
use Morebec\Orkestra\Normalization\Denormalizer\ObjectDenormalizer\FluentDenormalizer;

$normalizer = new ObjectNormalizer();

$normalizer->addNormalizer(FluentNormalizer::for(Username::class)->asString());
$normalizer->addDenormalizer(FluentDenormalizer::for(Username::class)->as(static function (DenormalizationContextInterface $context) {
    return new Username($context->getValue());
}));

FluentNormalizer 和 FluentDenormalizer 是定义（反）归一化器最方便的方式。如果您想完全控制它们，您可以实现 NormalizerInterface 和 DenormalizerInterface。