README

Symfony Object Normalizer 用于改进序列化过程，与内置规范化器相比，性能提升最多 5 倍（例如，400%）。这种性能提升可以通过为您的数据类生成专用规范化器来实现，因此您无需担心运行时开销，如反射或依赖于元数据（例如，ClassMetadata）的代码。

安装

composer require tsantos/fast-object-normalizer

Symfony 应用程序

此包附带一个 Symfony Bundle，可自动将规范化器添加到规范化器堆栈中。

使用 Flex 的应用程序

只需安装包，Symfony Flex 将自动将包注册到您的应用程序中。

不使用 Flex 的应用程序

您需要手动注册包

<?php
// config/bundles.php
return [
    // ..
    TSantos\FastObjectNormalizer\Bridge\Symfony\FastObjectNormalizerBundle::class => ['all' => true]
];

独立应用程序

对于使用 Symfony Serializer 作为独立组件的应用程序，您需要手动注册规范化器

<?php

require 'vendor/autoload.php';

use Symfony\Component\Serializer\Mapping\ClassDiscriminatorFromClassMetadata;
use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
use Symfony\Component\Serializer\Mapping\Loader\AnnotationLoader;
use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
use Symfony\Component\Serializer\Normalizer\ObjectDenormalizer;

$classMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
$discriminator = new ClassDiscriminatorFromClassMetadata($classMetadataFactory);

$serializer = new Serializer([
    new ArrayDenormalizer(),
    new FastObjectNormalizer(
        classGenerator: new NormalizerClassGenerator($classMetadataFactory, $discriminator),
        classDumper: new NormalizerClassDumper('./var/cache/serializer'),
        classMetadataFactory: $classMetadataFactory,
    ),
    new ObjectNormalizer($classMetadataFactory)
], ['json' => new JsonEncoder()]);

注意，ObjectNormalizer 仍在规范化器堆栈中。这不是强制性的，但最好让内置规范化器工作，因为 Fast Object Normalizer 可能不支持正在序列化的对象。

配置

Fast Object Normalizer 致力于序列化数据类（例如：DTO），但在某些情况下，您的应用程序可能尝试序列化包含资源或连接的对象，并且通常有一个专用的规范化器来处理该类型。为确保 Fast Object Normalizer 跳过此类类型，您可以将它配置为仅序列化与某些模式匹配的类型。

<?php
$normalizer = new FastObjectNormalizer(
    includedTypes: ['^App\\\Entity']
    //... other args here
)

# config/packages/fast_object_normalizer.yaml
fast_object_normalizer:
  includedTypes: ["^App\\Entity"]

使用 includedTypes 配置规范化器，您可以确切知道规范化器将支持哪些类型。在大多数情况下，您将选择此配置以避免异常行为。

还有 includedTypes 的对立面，它现在将接受所有类型，除非在 excludedList 中定义的类型。

<?php
$normalizer = new FastObjectNormalizer(
    includedTypes: ['^App\\\Entity']
    //... other args here
)

# config/packages/fast_object_normalizer.yaml
fast_object_normalizer:
  excludedTypes: ["^Some\\Vendor\\Object"]

最后，您可以结合这两种选项

<?php
$normalizer = new FastObjectNormalizer(
    includedTypes: ['^App\\\Entity'],
    excludedTypes: ['^App\\\Entity\\\\ExcludedType'],
    //... other args here
)

# config/packages/fast_object_normalizer.yaml
fast_object_normalizer:
  excludedTypes: ['^App\\\Entity']
  includedTypes: ["^App\\\Entity\\\\ExcludedType"]

使用此配置，您允许所有以 App\Entity 开头的类型，但排除 App\Entity\ExcludedType。

请注意

此包力求尽可能透明，以便您可以在不破坏应用程序的情况下使用它。如前所述，此包创建专用规范化器以尽可能快地序列化您的数据，这意味着内置规范化器 AbstractObjectNormalizer 将无法访问。这意味着功能如属性分组、跳过空值、属性回调等必须在此处重新实现以提升性能，也就是说，可能 与 AbstractObjectNormalizer 有一些不同的行为。如果您发现一些不同的行为，请提交一个问题。

下表列出了当前内置规范化器和 Fast Object Normalizer 支持的所有功能。

如果您想使用 Fast Object Normalizer 但需要实现特定功能，我会很高兴为您指出如何实现它。