README

将 JMS serializer 库绑定到 Laravel，并允许根据正常的 Laravel 配置约定定义模式。

设置

要将 Laravel Serializer 集成到您的项目中，请按照设置 Laravel 包的常规步骤操作。

• 将 atrauzzi/laravel-serializer 添加到您的 composer.json 文件中。
• 在您的项目根目录下运行 composer update。
• 编辑您的 app/config/app.php 文件，并将以下内容添加到 providers 数组的底部附近：
  • 'Atrauzzi\LaravelSerializer\ServiceProvider',
• 复制配置文件：./artisan config:publish atrauzzi/laravel-serializer

Note: Because this package does not perform any data storage, no migrations are required.

配置

在内部，JMS serializer 库使用元数据映射。通常这些是通过 XML、YAML 或被序列化类的注解来配置的。另一方面，Laravel Serializer 认为这些定义应该位于业务对象外部，并保持在 Laravel 项目的本地格式中。因此，映射被存储为 Laravel 配置数组系统的一部分。

如果您想覆盖这一点并配置 serializer 以使用默认或您自己制作的自定义元数据驱动程序工厂，您只需在依赖注入容器中重新绑定 JMS\Serializer\Builder\DriverFactoryInterface 即可。

映射

如果您打开在设置步骤中最后一步创建的 config.php 复制，您将看到它已经填充了一个示例 serializer 映射。

映射配置模式相当简单，形式如下：

[
    'mappings' => [
        'My\Namespace\Domain\User' => [
            'attributes' => [
                'id' => 'integer',
                'name' => [
                    'type' => 'string'
                ]
            ]
        ]
    ]
]

在 mappings 下的每个键都是将被序列化的对象的完全限定类名。每个类中 attributes 下的键是属性或变更器方法的名称（关于变更器将在使用部分详细说明）。在 mappings 下指定的每个键的值可以是数组、字符串或未指定。当值为字符串时，该字符串将是该字段的类型。当值为数组时，可以为单个字段指定多个配置指令。无值的键将获得最佳猜测的默认映射配置。

使用方法

由于您正在查找序列化数据，我将假设您已经在项目中使用某种形式的领域对象。

在执行序列化时，映射配置中的每个字段都指示属性或变更器方法，类似于可以在 Eloquent 模型上创建的变更器。换句话说，如果您使用任何其他 ORM 和/或 POPOs，您也可以定义遵循相同约定的方法。

序列化是通过从 Laravel 容器请求 JMS\Serializer\Serializer 实例来完成的。一旦您拥有该实例，您就可以按照 正常 JMS serializer 文档 中的说明使用它。

假设以下映射配置：

...
[
	'attributes' => [
		'firstName'
		'fullName' => [
			'type' => 'string'
		]
	]
]
...

以及与之相关的，我们还将假设有一个业务对象定义如下：

protected $firstName;

protected $lastName;

public function getFullNameAttribute() {
    return $this->userName . ' ' . $this->lastName;
}

您的控制器可能看起来像这样：

/** @var \JMS\Serializer\Serializer */
protected $serializer;

/**
 * @param \JMS\Serializer\Serializer $serializer
 */
public function __construct(
	Serializer $serializer
) {
	$this->serializer = $serializer;
}

public function myController() {
    // ...
	$serializedData = $this->serializer->serialize($myInstance, 'json');
    // ...
}

在这种情况下，当序列化为 JSON 时，将生成以下架构：

{
    "_type": "...",
    "first_name": "...",
    "full_name": "... ..."
}

如您所见，输出了 firstName，并且 fullName 由 firstName 和 lastName 变更而来。但独立的 lastName 属性没有输出，因为它没有在映射配置中指定。您还可以观察到生成了一个 _type 字段，以便于任何可能对混合和多项式结果集感兴趣的消费者。

关注点分离

您可能会想到——尤其是如果您正在使用 Doctrine——并非所有变更器都应属于包含它们所变更的数据的类。通常，变更可能是由于两个或多个关注点的情境性组合的结果。最好的也是最常见的一个例子是在为对象生成规范 URI 时。理想情况下，您不应该在您的模型上编写 getUri 方法，因为这会创建不良的隐式依赖。

在这种情况下，利用组合并创建一个可以由 Laravel 的依赖注入容器创建的类更有意义。此类实例在调用其 __construct 方法后，将分配给您的模型对象实例。

class PostSerializer {

    protected $uriGeneratorService;

    protected $post;

    public function __construct(UriGeneratorService $uriGeneratorService) {
        $this->uriGeneratorService = $uriGeneratorService;
    }

    public function setPost(Post $post) {
        $this->post = $post;
    }

    public function getUriAttribute() {
        return $this->uriGeneratorService->getUriForPost($this->post);
    }

}

以上述示例为例，可以通过传递数据向上的变更器输出来自 Post 的附加属性。在这种情况下，PostSerializer 已经成为一种视图，有助于保持您的域类干净且易于携带，通过维持合理的关注点分离。

Eloquent

Laravel 的默认 ORM 是 Eloquent，它是一个非常方便的工具，用于操作查询和数据建模。作为副作用，它往往会在模型类中捆绑许多非域关注点。而不是忽略这些有用的元数据，这种集成试图利用它来最小化您在编写项目代码时的努力。以下是您在使用 Eloquent 进行数据存储时可以享受的一些快捷方式列表。

• 当存在时，Laravel Serializer 会检测并使用变更器。
• 在元数据设置期间，读取 Model 子类的 $visible 属性。对于每个字段，假定最基本的设置，然而这可能是您的需求，如果是这样，这意味着您不需要在您的模型类之外创建配置映射。

元数据

本库的文档和部分功能仍在不断发展。如果您想贡献或建议功能或改进，请不要犹豫，在 GitHub 上提交一个工单！:)

致谢

Laravel Serializer 由 Alexander Trauzzi 创建和维护。