README

这是一个 Symfony 扩展包，用于集成独立包 consistence/consistence-jms-serializer，如果你不使用 Symfony，请遵循那里的说明。

此扩展包提供 Consistence 值对象与 JMS Serializer 的集成，以便你可以在序列化映射中使用它们。

目前，需要的唯一集成是对 枚举，下面有示例。

用法

枚举表示预定义值集，当然，你也会希望序列化和反序列化这些值。由于 枚举 是对象，并且你只想（反）序列化表示的值，所以必须有一些映射。

以下是一个示例，你想要为你的 User 对象（反）序列化性别

<?php

namespace Consistence\JmsSerializer\Example\User;

class Sex extends \Consistence\Enum\Enum
{

	public const FEMALE = 'female';
	public const MALE = 'male';

}

现在你可以在你的 User 对象中使用 Sex 枚举。类型指定为 enum<Your\Enum\Class>

<?php

namespace Consistence\JmsSerializer\Example\User;

use JMS\Serializer\Annotation as JMS;

class User extends \Consistence\ObjectPrototype
{

	// ...

	/**
	 * @JMS\Type("enum<Consistence\JmsSerializer\Example\User\Sex>")
	 * @var \Consistence\JmsSerializer\Example\User\Sex|null
	 */
	private $sex;

	// ...

	public function __construct(
		// ...
		Sex $sex = null
		// ...
	)
	{
		// ...
		$this->sex = $sex;
		// ...
	}

}

现在一切准备就绪，当你序列化对象时，只有 female 将作为表示枚举的值返回

<?php

namespace Consistence\JmsSerializer\Example\User;

/** @var \JMS\Serializer\Serializer $serializer */
$user = new User(Sex::get(Sex::FEMALE));
var_dump($serializer->serialize($user, 'json'));

/*

{
   "sex": "female"
}

*/

当反序列化对象时，你将再次收到 Sex 枚举对象

<?php

namespace Consistence\JmsSerializer\Example\User;

/** @var \JMS\Serializer\Serializer $serializer */
var_dump($serializer->deserialize('{
   "sex": "female"
}', User::class, 'json'));

/*

class Consistence\JmsSerializer\Example\User\User#46 (1) {
  private $sex =>
  class Consistence\JmsSerializer\Example\User\Sex#5 (1) {
    private $value =>
    string(6) "female"
  }
}

*/

这意味着对象的 API 是对称的（你得到你设置的相同类型），你可以开始享受枚举的优点，例如确保你得到的是有效值，并且可以在表示的值上定义方法。

默认可为空

序列化和反序列化都将接受 null 值，没有特别的映射（按照 Jms Serializer 的约定），所以如果你期望一个非空值，你必须通过其他方式强制执行这一点 - 要么通过限制你对象的 API，要么通过验证（尤其是在反序列化时）。

无效值

在序列化时，不应该有无效值，因为 枚举 保证实例只包含有效值。

在反序列化时，可能给出一个无效值，将抛出异常

<?php

namespace Consistence\JmsSerializer\Example\User;

/** @var \JMS\Serializer\Serializer $serializer */
var_dump($serializer->deserialize('{
   "sex": "FOO"
}', User::class, 'json'));

// \Consistence\Enum\InvalidEnumValueException: FOO [string] is not a valid value, accepted values: female, male

如果你在 API 中使用此功能，请确保你捕获此异常，并向消费者发送详细说明此错误的响应，你也可以编写自定义消息，可用的值列在 InvalidEnumValueException::getAvailableValues() 中。

XML 支持

与 JSON 不同，在 XML 中无法直接从值推断值类型。因此，如果你需要反序列化 XML，你必须手动提供此类型。你可以通过在类型定义中写入类型来完成此操作 - 对于上面的示例，它将是 string

<?php

namespace Consistence\JmsSerializer\Example\User;

use JMS\Serializer\Annotation as JMS;

class User extends \Consistence\ObjectPrototype
{

	// ...

	/**
	 * @JMS\Type("enum<Consistence\JmsSerializer\Example\User\Sex, string>")
	 * @var \Consistence\JmsSerializer\Example\User\Sex|null
	 */
	private $sex;

	// ...

}

对映射的 MultiEnums 的特殊支持

由于序列化和反序列化仅与枚举表示的值相关，因此对于多枚举（MultiEnums）而言，这意味着输出内部位掩码的值。如果客户端和服务器使用相同的枚举对象，这可能是有用的，否则这会破坏抽象，并且对于人类用户来说也更难以阅读。

如果您使用的是一个映射到单个枚举（MultiEum）的枚举，提供了一个方便的解决方案。如果您在映射中添加了enum<Your\Enum\Class, as_single> - 注意新参数as_single，则MultiEnum的值将被序列化为单个Enum值的集合。

<?php

namespace Consistence\JmsSerializer\Example\User;

use Consistence\Type\ArrayType\ArrayType;

use JMS\Serializer\Annotation as JMS;

class RoleEnum extends \Consistence\Enum\Enum
{

	public const USER = 'user';
	public const EMPLOYEE = 'employee';
	public const ADMIN = 'admin';

}

class RolesEnum extends \Consistence\Enum\MultiEnum
{

	/** @var int[] format: single Enum value (string) => MultiEnum value (int) */
	private static $singleMultiMap = [
		RoleEnum::USER => 1,
		RoleEnum::EMPLOYEE => 2,
		RoleEnum::ADMIN => 4,
	];

	public static function getSingleEnumClass(): string
	{
		return RoleEnum::class;
	}

	/**
	 * Converts value representing a value from single Enum to MultiEnum counterpart
	 *
	 * @param string $singleEnumValue
	 * @return int
	 */
	protected static function convertSingleEnumValueToValue($singleEnumValue): int
	{
		return ArrayType::getValue(self::$singleMultiMap, $singleEnumValue);
	}

	/**
	 * Converts value representing a value from MultiEnum to single Enum counterpart
	 *
	 * @param int $value
	 * @return string
	 */
	protected static function convertValueToSingleEnumValue(int $value): string
	{
		return ArrayType::getKey(self::$singleMultiMap, $value);
	}

}

class User extends \Consistence\ObjectPrototype
{

	// ...

	/**
	 * @JMS\Type("enum<Consistence\JmsSerializer\Example\User\RolesEnum, as_single>")
	 * @var \Consistence\JmsSerializer\Example\User\RolesEnum
	 */
	private $roles;

	// ...

	public function __construct(
		// ...
		RolesEnum $roles
		// ...
	)
	{
		// ...
		$this->roles = $roles;
		// ...
	}

}

$user = new User(RolesEnum::getMultiByEnums([
	RoleEnum::get(RoleEnum::USER),
	RoleEnum::get(RoleEnum::ADMIN),
]));

/** @var \JMS\Serializer\Serializer $serializer */
var_dump($serializer->serialize($user, 'json'));

/*

{
   "roles": [
      "user",
      "admin"
   ]
}

*/

反序列化同样是对称的 - 提供一个单个Enum值的数组将产生一个MultiEnum实例。

<?php

namespace Consistence\JmsSerializer\Example\User;

/** @var \JMS\Serializer\Serializer $serializer */
var_dump($serializer->deserialize('{
   "roles": [
      "user",
      "admin"
   ]
}', User::class, 'json'));

/*

class Consistence\JmsSerializer\Example\User\User#48 (1) {
  private $roles =>
  class Consistence\JmsSerializer\Example\User\RolesEnum#37 (1) {
    private $value =>
    int(5)
  }
}

*/

安装

1. 使用Composer安装包consistence/consistence-jms-serializer-symfony

composer require consistence/consistence-jms-serializer-symfony

1. 在您的应用程序中注册该扩展包

// config/bundles.php
return [
	// ...
	Consistence\JmsSerializer\SymfonyBundle\ConsistenceJmsSerializerBundle::class => ['all' => true],
];

就这样，您已经准备好出发了！