README

用于附加到 ApiController 事件的数据库规范化监听器

1) 主题

API 的规范化部分负责响应格式化前的对象转换。

这种规范化允许格式化过程使用常规数组类型而不是一组对象。

2) 类架构

API 规范化是一个用于更强大现有规范化的纯装饰器类。选择使用 Symfony serializer 是为了允许配置上下文并在安全输出中使用高级分组。

3) 依赖描述和在元素中的使用

撰写本文时，规范化器被设计为具有四个生产依赖项，如下

• psr/log
• symfony/event-dispatcher
• kairos-project/api-loader
• symfony/serializer

3.1) psr/log

在开发中，每个项目部分的调试和错误回溯是基本法则之一，而且它也缺失了 OWASP 十大威胁之一。

根据第三版 PHP 标准参考定义，日志组件必须实现特定的接口。顺便说一下，日志系统将可由每个现有的框架使用。

3.2) symfony/event-dispatcher

规范化系统被设计成易于扩展，并将实现一个事件分发系统，允许按优先级附加和分离逻辑。

3.3) kairos-project/api-loader

规范化器是为了用于 API 和 kairos 项目中的通用系统。即使系统需要访问 API 加载器的常量。这个 Loader 使用 API 控制器本身。

3.4) symfony/serializer

如果我们想提供一个通用接口，规范化逻辑可能很难实现。我们将使用 Symfony serializer 来绕过这个困难。

4) 实施规范

规范化组件将提供一个独特的方法来规范化，该过程处理规范化。

组件的配置将是实例化参数的一部分。

将创建一个规范化事件来存储处理事件、数据和上下文。

4.1) 依赖注入规范

处理逻辑需要一个规范化实例、一个用于检索要规范化的元素的参数键以及一个用于存储结果的参数键。默认情况下，参数键将是 API 加载器的一个。

将提供一个默认上下文，以允许规范化设置，如分组。

此外，还将注入两个事件名称，以定义派发的事件。

4.2) 规范化算法

规范化方法负责数据规范化。

We assume to receive the process event from the parameters.
We assume the process event parameter key to be part of the attributes.

Get the data to normalize from the process event, using the parameter key.
Create a distinct normalizer event. This element encloses the data to be normalized, the normalizer context, and the initial one.

Dispatch the before normalizing event.
Normalize the data and replace the normalize event content.
Dispatch the after normalizing event.

Set a new parameter into the process event to store the normalized data.

5) 使用

需要 symfony/property-access 来使用 ObjectNormalizer，并且需要 sensio/framework-extra-bundle 来进行注解分组。

5.1) 基本使用

use KairosProject\ApiNormalizer\Normalizer\Normalizer;
use KairosProject\ApiLoader\Loader\AbstractApiLoader;
use KairosProject\ApiController\Event\ProcessEvent;

$normalizer = new Normalizer(
    $logger,
    $objectNormalizer
);

$processEvent = new ProcessEvent();
$processEvent->setParameter(AbstractApiLoader::EVENT_KEY_STORAGE, $data);

$dispatcher->addListener('event', [$normalizer, 'normalize']);
$dispatcher->dispatch('event', $processEvent);

$normalizedData = $processEvent->getParameter(Normalizer::NORMALIZED_DATA);

5.1) 使用属性分组

use Doctrine\Common\Annotations\AnnotationReader;
use Doctrine\Common\Annotations\AnnotationRegistry;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
use Symfony\Component\Serializer\Mapping\Loader\AnnotationLoader;

AnnotationRegistry::registerLoader('class_exists');
$objectNormalizer = new ObjectNormalizer(
   new ClassMetadataFactory(
       new AnnotationLoader(
           new AnnotationReader()
       )
   )
);

$normalizer = new Normalizer(
   $logger,
   $objectNormalizer,
   ['groups' => ['output_group']]
);

5.1) 完整构造函数

public function __construct(
   LoggerInterface $logger,
   NormalizerInterface $normalizer,
   array $context = [],
   string $inputParameter = AbstractApiLoader::EVENT_KEY_STORAGE,
   string $outputParameter = Normalizer::NORMALIZED_DATA,
   string $beforeNormalizeEvent = Normalizer::EVENT_BEFORE,
   string $afterNormalizerEvent = Normalizer::EVENT_AFTER
);