README

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

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

目前，所需集成的唯一集成是 枚举，请参见下面的示例。

此扩展已更新，现在可在 Symfony 5 和 PHP 7.4 上运行。

使用方法

枚举 表示一组预定义的值，当然，您也希望能够序列化和反序列化这些值。由于 枚举 是对象，并且您只希望（反）序列化代表值，因此必须有一些映射。

您可以在下面的示例中看到，您想要（反）序列化 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<您的\枚举\类, 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安装包scattercz/consistence-jms-serializer-symfony

composer require scattercz/consistence-jms-serializer-symfony

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

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

这就完成了，您现在可以开始了！