README

1of0/php-serializer

此库提供了基于 PHP 的 json_encode() 和 json_decode() 函数的高级序列化功能。大多数功能都受到流行的 .NET 库 Json.NET 的启发。

安装

此库可在 Packagist 上找到，并可以使用 composer 安装。

composer require 1of0/json

快速入门

使用此库的最直接方法是使用 Convert 类的静态方法。该 Convert 类是序列化类单例实例的静态外观。

<?php

use OneOfZero\Json\Convert;
use OneOfZero\Json\Serializer;

// Basic serialization
$json = Convert::toJson($myObject);

// Basic deserialization
$object = Convert::fromJson($json);

// Type hint example
$object = Convert::fromJson($json, \MyNamespace\MyClass::class);

// This is a more verbose form of Convert::toJson($myObject)
$json = Serializer::get()->serialize($myObject);

它是如何工作的？

序列化器在将对象传递给 json_encode() 函数之前，会先对标注或 XML/YAML/JSON/PHP 映射对象进行预处理。反过来，反序列化器将 JSON 传递给 json_decode() 函数，并对结果进行后处理，以尽可能接近原始对象（假设已正确映射/标注）。

文档

有 ApiGen 生成的文档可用。

• 最小文档 不包括内部类的文档。
• 完整文档 包括内部类，当扩展序列化器时可能很有用。

其他文档和一组示例正在开发中。如果您需要帮助使某些内容工作，或者某些内容不明确，请毫不犹豫地 提交问题。

功能

映射器和映射器链

序列化器和反序列化器的行为可以通过类和类成员上的映射来影响。此库支持以下映射：

• 注解
• XML
• YAML
• JSON
• PHP

这些映射器可以按任何顺序链在一起，以提供单个合并的映射。

嵌入类型信息

这是从 zumba/json-serializer 库中受到启发的功能。

默认情况下，序列化器将在序列化对象中嵌入类型信息。类型信息允许反序列化器将 JSON 对象反序列化为其原始类型，而无需 PHPDoc、注解或映射。

嵌入的数据是额外的 @type 属性，它包含序列化对象的完全限定类名

{
	"@type": "MyNamespace\\MyClass",
	"propertyA": "valueA",
	"propertyB": "valueB",
	...
}

序列化

可以通过类级映射禁用单个类的类型信息嵌入，或可以在配置中全局禁用。

<?php
$configuration->embedTypeMetadata = false;

反序列化

由于安全考虑，反序列化器仅反序列化白名单中的类型（默认情况下，此白名单为空）。可以通过配置将类添加到白名单中。

<?php
$configuration->getMetaHintWhitelist()->allowClass(MyClass::class);

您还可以通过命名空间、类继承或正则表达式进行白名单。有关详细信息，请参阅 MetaHintWhiteList 类的 API 文档。

对象和成员转换器

类似于 Json.NET 的自定义转换器，此库还允许您为指定的属性构建和指定自定义转换器。

合同解析器

从Json.NET松散移植的另一个功能是契约解析器。契约解析器允许您动态地操作(反)序列化树中每个节点的序列化映射。契约解析器的一个示例用途是属性名称的转换。

序列化组

(尚未实现)

引用属性

您可能会经常处理不需要序列化而只是引用的子对象。这个库可以像那样序列化和反序列化引用。要实现这一点

• 被引用的对象需要实现ReferableInterface接口
• 持有被引用对象的属性必须使用@IsReference注解标记
• 需要存在一个支持被引用对象（并需要实现ReferenceResolverInterface接口）的引用解析器

错误和功能请求

请将任何错误和功能请求发布到GitLab上的问题跟踪器。

如果文档不足，请不要犹豫提交问题。

许可证

该库采用MIT许可证，其全文可在LICENSE文件中找到。