README

$ composer require dbstudios/doze

基本配置

Doze只需两样东西即可开箱即用：序列化和响应器。对于序列化器，Doze使用symfony/serializer包。您可以在他们的README中找到更多关于使用其功能的信息，但以下是一个简单的示例。

<?php
    use Symfony\Component\Serializer\Serializer;
    use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
    use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
    use Symfony\Component\Serializer\Encoder\JsonEncoder;

    $serializer = new Serializer([
        new DateTimeNormalizer(),
        new ObjectNormalizer(),
    ], [
        new JsonEncoder(),
    ]);

    $responder = new Responder($serializer);
    $response = $responder->createResponse('json', [
        'name' => 'Example',
        'someOtherField' => 'Value',
    ]);

    echo $response->getContent();

    // {"name":"Example","someOtherField":"Value"}

在示例中，我们首先创建一个新的序列化器实例。构造函数的第一个参数是一个正常化器数组，序列化器使用它来在序列化之前简化数据。DateTimeNormalizer和ObjectNormalizer都包含在symfony/serializer中，分别用于规范化DateTime和通用对象。第二个参数是支持的编码器格式列表。我们的示例仅支持JSON。

接下来，我们创建一个新的Responder实例，并调用其createResponse()方法来获取我们的Response对象，该对象包含诸如头、HTTP状态码和响应体等信息。有关Response对象的更多信息，请参阅symfony/httpfoundation包。

字段选择符号

有时，使用您的API的开发者可能只想或需要从对象或数组中获取几个特定字段。为此，Doze实现了一种选择符号，可以用于限制要序列化和返回的字段。

在调用Responder::createResponse()时，您可以为“attributes”键提供值，这将告诉序列化器哪些属性应该被序列化和返回。关于在序列化器包中使用“attributes”上下文键的文档，但Doze还支持构建属性过滤器的一种替代方法。

在下面的示例中，$responder是我们在前面的示例中创建的Responder实例。由于字段选择功能旨在暴露给您的API的最终用户，因此我们从$_GET全局变量中检索选择器。

<?php
    // $_GET['fields'] = 'name,anotherField'

    use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;

    $parser = new FieldSelectorParser($_GET['fields']);
    $attributes = $parser->all();

    /**
     *  [
     *      'name' => true,
     *      'anotherField' => true,
     *  ]
     */

     $response = $responder->createResponse('json', [
        'name' => 'Example',
        'someOtherField' => 'Value',
        'anotherField' => 'Another Value',
    ], null, [], [
        AbstractNormalizer::ATTRIBUTES => $attributes,
    ]);

    echo $response->getContent();

    // {"name":"Example","anotherField":"Another Value"}

请注意，由$response->getContent()生成的JSON输出不包含“someOtherField”字段，该字段不是选择器的一部分。

字段选择器也可以包含嵌套选择器。在下面的示例中，假设$data有一个名为“nestedObject”的字段，该字段有“name”和“property”字段。

<?php
    // $_GET['fields'] = 'name,nestedObject{property}';

    use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;

    $parser = new FieldSelectorParser($_GET['fields']);
    $attributes = $parser->all();

    /**
     *  [
     *      'name' => true,
     *      'nestedObject' => [
     *          'property' => true,
     *      ],
     *  ]
     */

     $response = $responder->createResponse('json', $data, null, [], [
        AbstractNormalizer::ATTRIBUTES => $attributes,
    ]);

    echo $response->getContent();

    // {"name":"Example","nestedObject":{"property":"Value"}}

序列化数据库对象

某些库（如Doctrine）从数据库中加载数据库对象时无法干净地序列化，因为这些对象会自动链接到相关对象。在某些情况下，序列化数据库实体可能导致大量子实体被序列化，这会导致大量的不必要数据通过网络传输。

Doze提供了一个特殊的正常化器，即EntityNormalizer，它了解此类数据库实体（通过EntityInterface接口），并且除非使用字段选择器明确请求，否则只会序列化实体ID。要使用它，您的DBAL使用的任何类都必须实现EntityInterface，并且EntityNormalizer必须在您的序列化器的正常化器堆栈中位于任何可能意外尝试序列化您的对象的其他正常化器（如前面示例中使用的ObjectNormalizer）之上。

<?php
    use Symfony\Component\Serializer\Serializer;
    use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
    use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
    use Symfony\Component\Serializer\Encoder\JsonEncoder;
    use DaybreakStudios\Doze\Serializer\EntityNormalizer;

    $serializer = new Serializer([
        new DateTimeNormalizer(),
        new EntityNormalizer(),
        // EntityNormalizer must be added above less specific normalizers, like the ObjectNormalizer
        new ObjectNormalizer(),
    ], [
        new JsonEncoder(),
    ]);

添加了额外的规范化器后，实现 EntityInterface 的任何对象将只序列化其 ID，而不是整个对象及其子对象。这可以通过使用显式选择实体（以及可选地，其字段）的 字段选择符号 来覆盖。

分页集合

即将推出。