{"id":21951439,"url":"https://github.com/consistence/consistence-jms-serializer","last_synced_at":"2025-08-21T02:31:50.323Z","repository":{"id":16067743,"uuid":"79221795","full_name":"consistence/consistence-jms-serializer","owner":"consistence","description":"Integration of Consistence library with JMS Serializer","archived":false,"fork":false,"pushed_at":"2024-12-04T12:50:02.000Z","size":89,"stargazers_count":4,"open_issues_count":1,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-12T16:24:11.736Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/consistence.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-17T11:39:15.000Z","updated_at":"2024-12-04T12:50:04.000Z","dependencies_parsed_at":"2024-06-20T23:38:18.792Z","dependency_job_id":null,"html_url":"https://github.com/consistence/consistence-jms-serializer","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistence%2Fconsistence-jms-serializer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistence%2Fconsistence-jms-serializer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistence%2Fconsistence-jms-serializer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistence%2Fconsistence-jms-serializer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/consistence","download_url":"https://codeload.github.com/consistence/consistence-jms-serializer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230479864,"owners_count":18232630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-29T06:14:11.602Z","updated_at":"2024-12-19T18:17:51.497Z","avatar_url":"https://github.com/consistence.png","language":"PHP","readme":"Integration of Consistence library with JMS Serializer\n======================================================\n\nThis library provides integration of [Consistence](https://github.com/consistence/consistence) value objects for [JMS Serializer](http://jmsyst.com/libs/serializer) so that you can use them in your serialization mappings.\n\nFor now, the only integration which is needed is for [Enums](https://github.com/consistence/consistence/blob/master/docs/Enum/enums.md), see the examples below.\n\nUsage\n-----\n\n[Enums](https://github.com/consistence/consistence/blob/master/docs/Enum/enums.md) represent predefined set of values and of course, you will want to serialize and deserialize these values as well. Since [`Enums`](https://github.com/consistence/consistence/blob/master/src/Enum/Enum.php) are objects and you only want to (de)serialize represented value, there has to be some mapping.\n\nYou can see it in this example where you want to (de)serialize sex for your `User`s:\n\n```php\n\u003c?php\n\nnamespace Consistence\\JmsSerializer\\Example\\User;\n\nclass Sex extends \\Consistence\\Enum\\Enum\n{\n\n\tpublic const FEMALE = 'female';\n\tpublic const MALE = 'male';\n\n}\n```\n\nNow you can use the `Sex` enum in your `User` object. Type for (de)serialization is specified as `enum\u003cYour\\Enum\\Class\u003e`:\n\n```php\n\u003c?php\n\nnamespace Consistence\\JmsSerializer\\Example\\User;\n\nuse JMS\\Serializer\\Annotation as JMS;\n\nclass User extends \\Consistence\\ObjectPrototype\n{\n\n\t// ...\n\n\t/**\n\t * @JMS\\Type(\"enum\u003cConsistence\\JmsSerializer\\Example\\User\\Sex\u003e\")\n\t * @var \\Consistence\\JmsSerializer\\Example\\User\\Sex|null\n\t */\n\tprivate $sex;\n\n\t// ...\n\n\tpublic function __construct(\n\t\t// ...\n\t\tSex $sex = null\n\t\t// ...\n\t)\n\t{\n\t\t// ...\n\t\t$this-\u003esex = $sex;\n\t\t// ...\n\t}\n\n}\n```\n\nNow everything is ready to be used, when you serialize the object, only `female` will be returned as the value representing the enum:\n\n```php\n\u003c?php\n\nnamespace Consistence\\JmsSerializer\\Example\\User;\n\n/** @var \\JMS\\Serializer\\Serializer $serializer */\n$user = new User(Sex::get(Sex::FEMALE));\nvar_dump($serializer-\u003eserialize($user, 'json'));\n\n/*\n\n{\n   \"sex\": \"female\"\n}\n\n*/\n```\n\nAnd when you deserialize the object, you will receive the `Sex` enum object again:\n\n```php\n\u003c?php\n\nnamespace Consistence\\JmsSerializer\\Example\\User;\n\n/** @var \\JMS\\Serializer\\Serializer $serializer */\nvar_dump($serializer-\u003edeserialize('{\n   \"sex\": \"female\"\n}', User::class, 'json'));\n\n/*\n\nclass Consistence\\JmsSerializer\\Example\\User\\User#46 (1) {\n  private $sex =\u003e\n  class Consistence\\JmsSerializer\\Example\\User\\Sex#5 (1) {\n    private $value =\u003e\n    string(6) \"female\"\n  }\n}\n\n*/\n```\n\nThis means that the objects API is symmetrical (you get the same type as you set) and you can start benefiting from Enums advantages such as being sure, that what you get is already a valid value and having the possibility to define methods on top of the represented values.\n\n### Nullable by default\n\nBoth serialization and deserialization will accept `null` values, there is no special mapping for that (by `Jms Serializer`s convention), so if you are expecting a non-null value you have to enforce this by other means - either by restricting this in the API of your objects or by validation (needed especially for deserialization).\n\n### Invalid values\n\nWhile serializing, there should be no invalid values, because [Enums](https://github.com/consistence/consistence/blob/master/docs/Enum/enums.md) guarantee that the instance contains only valid values.\n\nWhile deserializing, there can be an invalid value given, an exception will be thrown:\n\n```php\n\u003c?php\n\nnamespace Consistence\\JmsSerializer\\Example\\User;\n\n/** @var \\JMS\\Serializer\\Serializer $serializer */\nvar_dump($serializer-\u003edeserialize('{\n   \"sex\": \"FOO\"\n}', User::class, 'json'));\n\n// \\Consistence\\Enum\\InvalidEnumValueException: FOO [string] is not a valid value, accepted values: female, male\n```\n\nIf you are using this in an API, make sure you will catch this exception and send the consumer a response detailing this error, you can also write a custom message, the available values are listed in `InvalidEnumValueException::getAvailableValues()`.\n\n### XML support\n\nUnlike in JSON, in XML value types cannot be inferred directly from the values. So if you need to deserialize XML, you have to provide this type manually. You can do this by writing the type in the type definition - for the above example it would be `string`:\n\n```php\n\u003c?php\n\nnamespace Consistence\\JmsSerializer\\Example\\User;\n\nuse JMS\\Serializer\\Annotation as JMS;\n\nclass User extends \\Consistence\\ObjectPrototype\n{\n\n\t// ...\n\n\t/**\n\t * @JMS\\Type(\"enum\u003cConsistence\\JmsSerializer\\Example\\User\\Sex, string\u003e\")\n\t * @var \\Consistence\\JmsSerializer\\Example\\User\\Sex|null\n\t */\n\tprivate $sex;\n\n\t// ...\n\n}\n```\n\n### Special support for mapped MultiEnums\n\nSince the (de)serialization works only with the value the enum is representing, then in case of [MultiEnums](https://github.com/consistence/consistence/blob/master/docs/Enum/multi-enums.md) this would mean outputting the value of the internal bit mask. This could be useful if both the client and server use the same Enum objects, but otherwise this breaks the abstraction and is less readable for a human consumer as well.\n\nIf you are using a [MultiEum mapped to a single Enum](https://github.com/consistence/consistence/blob/master/docs/Enum/multi-enums.md#mapping-a-multienum-to-a-single-enum) there is a handy solution provided, if you add to your mapping `enum\u003cYour\\Enum\\Class, as_single\u003e` - notice the new `as_single` parameter, then the value of `MultiEnum` will be serialized as a collection of single `Enum` values:\n\n```php\n\u003c?php\n\nnamespace Consistence\\JmsSerializer\\Example\\User;\n\nuse Consistence\\Type\\ArrayType\\ArrayType;\n\nuse JMS\\Serializer\\Annotation as JMS;\n\nclass RoleEnum extends \\Consistence\\Enum\\Enum\n{\n\n\tpublic const USER = 'user';\n\tpublic const EMPLOYEE = 'employee';\n\tpublic const ADMIN = 'admin';\n\n}\n\nclass RolesEnum extends \\Consistence\\Enum\\MultiEnum\n{\n\n\t/** @var int[] format: single Enum value (string) =\u003e MultiEnum value (int) */\n\tprivate static $singleMultiMap = [\n\t\tRoleEnum::USER =\u003e 1,\n\t\tRoleEnum::EMPLOYEE =\u003e 2,\n\t\tRoleEnum::ADMIN =\u003e 4,\n\t];\n\n\tpublic static function getSingleEnumClass(): string\n\t{\n\t\treturn RoleEnum::class;\n\t}\n\n\t/**\n\t * Converts value representing a value from single Enum to MultiEnum counterpart\n\t *\n\t * @param string $singleEnumValue\n\t * @return int\n\t */\n\tprotected static function convertSingleEnumValueToValue($singleEnumValue): int\n\t{\n\t\treturn ArrayType::getValue(self::$singleMultiMap, $singleEnumValue);\n\t}\n\n\t/**\n\t * Converts value representing a value from MultiEnum to single Enum counterpart\n\t *\n\t * @param int $value\n\t * @return string\n\t */\n\tprotected static function convertValueToSingleEnumValue(int $value): string\n\t{\n\t\treturn ArrayType::getKey(self::$singleMultiMap, $value);\n\t}\n\n}\n\nclass User extends \\Consistence\\ObjectPrototype\n{\n\n\t// ...\n\n\t/**\n\t * @JMS\\Type(\"enum\u003cConsistence\\JmsSerializer\\Example\\User\\RolesEnum, as_single\u003e\")\n\t * @var \\Consistence\\JmsSerializer\\Example\\User\\RolesEnum\n\t */\n\tprivate $roles;\n\n\t// ...\n\n\tpublic function __construct(\n\t\t// ...\n\t\tRolesEnum $roles\n\t\t// ...\n\t)\n\t{\n\t\t// ...\n\t\t$this-\u003eroles = $roles;\n\t\t// ...\n\t}\n\n}\n\n$user = new User(RolesEnum::getMultiByEnums([\n\tRoleEnum::get(RoleEnum::USER),\n\tRoleEnum::get(RoleEnum::ADMIN),\n]));\n\n/** @var \\JMS\\Serializer\\Serializer $serializer */\nvar_dump($serializer-\u003eserialize($user, 'json'));\n\n/*\n\n{\n   \"roles\": [\n      \"user\",\n      \"admin\"\n   ]\n}\n\n*/\n```\n\nDeserialization then again works symmetrically - giving an array of single `Enum` values will produce a `MultiEnum` instance:\n\n```php\n\u003c?php\n\nnamespace Consistence\\JmsSerializer\\Example\\User;\n\n/** @var \\JMS\\Serializer\\Serializer $serializer */\nvar_dump($serializer-\u003edeserialize('{\n   \"roles\": [\n      \"user\",\n      \"admin\"\n   ]\n}', User::class, 'json'));\n\n/*\n\nclass Consistence\\JmsSerializer\\Example\\User\\User#48 (1) {\n  private $roles =\u003e\n  class Consistence\\JmsSerializer\\Example\\User\\RolesEnum#37 (1) {\n    private $value =\u003e\n    int(5)\n  }\n}\n\n*/\n```\n\nInstallation\n------------\n\n\u003e If you are using Symfony, you can use [`consistence/consistence-jms-serializer-symfony`](https://github.com/consistence/consistence-jms-serializer-symfony), which will take care of the integration.\n\n1) Install package [`consistence/consistence-jms-serializer`](https://packagist.org/packages/consistence/consistence-jms-serializer) with [Composer](https://getcomposer.org/):\n\n```bash\ncomposer require consistence/consistence-jms-serializer\n```\n\n2) Register [serialization handler](http://jmsyst.com/libs/serializer/master/handlers#subscribing-handlers):\n\n```php\n\u003c?php\n\nuse Consistence\\JmsSerializer\\Enum\\EnumSerializerHandler;\n\nuse JMS\\Serializer\\Handler\\HandlerRegistry;\nuse JMS\\Serializer\\SerializerBuilder;\n\n$serializer = SerializerBuilder::create()\n\t-\u003econfigureHandlers(function (HandlerRegistry $registry) {\n\t\t$registry-\u003eregisterSubscribingHandler(new EnumSerializerHandler());\n\t})\n\t-\u003ebuild();\n```\n\nThat's all, you are good to go!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconsistence%2Fconsistence-jms-serializer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconsistence%2Fconsistence-jms-serializer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconsistence%2Fconsistence-jms-serializer/lists"}