From b59b752f5f66ce981b03b70105f05c289360145d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Sat, 27 Dec 2014 23:05:42 +0100 Subject: [PATCH 1/6] [Serializer] Name Converter --- components/serializer.rst | 125 +++++++++++++++++++++++++++++++------- 1 file changed, 102 insertions(+), 23 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index 0d26457d0aa..035fe6f88c7 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -162,38 +162,117 @@ needs three parameters: 2. The name of the class this information will be decoded to 3. The encoder used to convert that information into an array -Using Camelized Method Names for Underscored Attributes -------------------------------------------------------- +Converting Property Names when Serializing and Deserializing +------------------------------------------------------------ -.. versionadded:: 2.3 - The :method:`GetSetMethodNormalizer::setCamelizedAttributes` - method was introduced in Symfony 2.3. +.. versionadded:: 2.7 + The :class:`Symfony\\Component\\Serializer\\NameConverter\\NameConverterInterface` + interface was introduced in Symfony 2.7. -Sometimes property names from the serialized content are underscored (e.g. -``first_name``). Normally, these attributes will use get/set methods like -``getFirst_name``, when ``getFirstName`` method is what you really want. To -change that behavior use the -:method:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setCamelizedAttributes` -method on the normalizer definition:: +Sometimes serialized attributes must be named differently than PHP class' +properties or getter and setter methods. - $encoder = new JsonEncoder(); - $normalizer = new GetSetMethodNormalizer(); - $normalizer->setCamelizedAttributes(array('first_name')); +The Serializer Component provides a handy way to translate or map PHP field +names to serialized names: the Name Converter System. - $serializer = new Serializer(array($normalizer), array($encoder)); +Given you have the following object:: + + namespace Acme; + + class Company + { + public name; + public address; + } + + +And in the serialized form, all attributes must be prefixed by ``org_`` like +the following:: + + {"org_name": "Les-Tilleuls.coop", "org_address": "Euratechnologies, 2 rue Hegel, 59160 Lomme, France"} + +A custom Name Converter can handle such cases:: + + namespace MySerializer; + + use Symfony\Component\Serializer\NameConverter\NameConverterInterface; + + class OrgPrefixNameConverter implements NameConverterInterface + { + public function normalize($propertyName) + { + return 'org_'.$propertyName; + } + + public function denormalize($propertyName) + { + return substr($propertyName, 4) + } + } + +The custom normalizer can be used by passing it as second parameter of any +class extending :class:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer`, +including :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` +and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`:: + + use Acme\Company; + use Symfony\Component\Serializer\Encoder\JsonEncoder + use Symfony\Component\Serializer\Normalizer\PropertyNormalizer; + use Symfony\Component\Serializer\Serializer; + use MySerializer\OrgPrefixNameConverter; + + $nameConverter = new OrgPrefixNameConverter(); + $normalizer = new PropertyNormalizer(null, $nameConverter); + + $serializer = new Serializer(array(new JsonEncoder()), array($normalizer)); + + $obj = new Company(); + $obj->name = 'Les-Tilleuls.coop'; + $obj->address = 'Euratechnologies, 2 rue Hegel, 59160 Lomme, France'; + + $json = $serializer->serialize($obj); + $objCopy = $serializer->deserialize($json); + +CamelCase to Underscore +~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.7 +The :class:`Symfony\\Component\\Serializer\\NameConverter\\CamelCaseToUnderscoreNameConverter` + interface was introduced in Symfony 2.7. + +It's common in many formats to use underscores to separate words. However, +PSR-2 specify that the preferred style for PHP properties and methods is +CamelCase. - $json = <<givenName = $givenName; + } + + public function getGivenName() + { + return $this->givenName; + } } - EOT; - $person = $serializer->deserialize($json, 'Acme\Person', 'json'); + $kevin = new Person('Kévin'); + $normalizer->normalize($kevin); + // ['given_name' => 'Kévin']; -As a final result, the deserializer uses the ``first_name`` attribute as if -it were ``firstName`` and uses the ``getFirstName`` and ``setFirstName`` methods. + $anne = $normalizer->denormalize(array('given_name' => 'Anne'), 'Person'); Serializing Boolean Attributes ------------------------------ From 4ecc706dbbed33dd1c3d2e91bd5f17b7c0375e84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Sun, 28 Dec 2014 22:21:17 +0100 Subject: [PATCH 2/6] [Serializer] Name Converter corrections. --- components/serializer.rst | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index 035fe6f88c7..e91a10c150f 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -169,16 +169,14 @@ Converting Property Names when Serializing and Deserializing The :class:`Symfony\\Component\\Serializer\\NameConverter\\NameConverterInterface` interface was introduced in Symfony 2.7. -Sometimes serialized attributes must be named differently than PHP class' -properties or getter and setter methods. +Sometimes serialized attributes must be named differently than properties +or getter and setter methods of PHP classes. The Serializer Component provides a handy way to translate or map PHP field -names to serialized names: the Name Converter System. +names to serialized names: The Name Converter System. Given you have the following object:: - namespace Acme; - class Company { public name; @@ -193,8 +191,6 @@ the following:: A custom Name Converter can handle such cases:: - namespace MySerializer; - use Symfony\Component\Serializer\NameConverter\NameConverterInterface; class OrgPrefixNameConverter implements NameConverterInterface @@ -206,7 +202,7 @@ A custom Name Converter can handle such cases:: public function denormalize($propertyName) { - return substr($propertyName, 4) + return substr($propertyName, 4); } } @@ -215,11 +211,9 @@ class extending :class:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNorm including :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`:: - use Acme\Company; use Symfony\Component\Serializer\Encoder\JsonEncoder use Symfony\Component\Serializer\Normalizer\PropertyNormalizer; use Symfony\Component\Serializer\Serializer; - use MySerializer\OrgPrefixNameConverter; $nameConverter = new OrgPrefixNameConverter(); $normalizer = new PropertyNormalizer(null, $nameConverter); @@ -231,21 +225,25 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`:: $obj->address = 'Euratechnologies, 2 rue Hegel, 59160 Lomme, France'; $json = $serializer->serialize($obj); + // {"org_name": "Les-Tilleuls.coop", "org_address": "Euratechnologies, 2 rue Hegel, 59160 Lomme, France"} $objCopy = $serializer->deserialize($json); + // Same data as $obj + +.. _using-camelized-method-names-for-underscored-attributes: -CamelCase to Underscore +CamelCase to snake_case ~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.7 -The :class:`Symfony\\Component\\Serializer\\NameConverter\\CamelCaseToUnderscoreNameConverter` + The :class:`Symfony\\Component\\Serializer\\NameConverter\\CamelCaseToUnderscoreNameConverter` interface was introduced in Symfony 2.7. -It's common in many formats to use underscores to separate words. However, -PSR-2 specify that the preferred style for PHP properties and methods is -CamelCase. +In many formats, it's common to use underscores to separate words (also know +as snake_case). However, PSR-1 specifies that the preferred style for PHP +properties and methods is CamelCase. Symfony provides a built-in Name Converter designed to translate between -underscored and CamelCased styles during serialization and deserialization +snake_case and CamelCased styles during serialization and deserialization processes:: use Symfony\Component\Serializer\NameConverter\CamelCaseToUnderscoreNameConverter; @@ -273,6 +271,7 @@ processes:: // ['given_name' => 'Kévin']; $anne = $normalizer->denormalize(array('given_name' => 'Anne'), 'Person'); + // Person object with givenName: 'Anne' Serializing Boolean Attributes ------------------------------ From 24d0320301caa22eebe80b4130d05b33f33c67ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Sun, 28 Dec 2014 22:42:47 +0100 Subject: [PATCH 3/6] [Serializer] Use firtName and snake_case --- components/serializer.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index e91a10c150f..d65839fcebb 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -202,7 +202,8 @@ A custom Name Converter can handle such cases:: public function denormalize($propertyName) { - return substr($propertyName, 4); + // remove org_ prefix + return 'org_' === substr($propertyName, 0, 4) ? substr($propertyName, 4) : $propertyName; } } @@ -246,32 +247,32 @@ Symfony provides a built-in Name Converter designed to translate between snake_case and CamelCased styles during serialization and deserialization processes:: - use Symfony\Component\Serializer\NameConverter\CamelCaseToUnderscoreNameConverter; + use Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter; use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer; - $normalizer = new GetSetMethodNormalizer(null, new CamelCaseToUnderscoreNameConverter()); + $normalizer = new GetSetMethodNormalizer(null, new CamelCaseToSnakeCaseNameConverter()); class Person { - private $givenName; + private $firstName; - public function __construct($givenName) + public function __construct($firstName) { - $this->givenName = $givenName; + $this->firstName = $firstName; } - public function getGivenName() + public function getFirstName() { - return $this->givenName; + return $this->firstName; } } $kevin = new Person('Kévin'); $normalizer->normalize($kevin); - // ['given_name' => 'Kévin']; + // ['first_name' => 'Kévin']; - $anne = $normalizer->denormalize(array('given_name' => 'Anne'), 'Person'); - // Person object with givenName: 'Anne' + $anne = $normalizer->denormalize(array('first_name' => 'Anne'), 'Person'); + // Person object with firstName: 'Anne' Serializing Boolean Attributes ------------------------------ From 57e6c94a9a8fc34dbf9f752f4117c9d704970429 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Mon, 29 Dec 2014 21:02:54 +0100 Subject: [PATCH 4/6] [Serializer] Name Converter fixes --- components/serializer.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index d65839fcebb..e57a06ade33 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -170,7 +170,7 @@ Converting Property Names when Serializing and Deserializing interface was introduced in Symfony 2.7. Sometimes serialized attributes must be named differently than properties -or getter and setter methods of PHP classes. +or getter / setter methods of PHP classes. The Serializer Component provides a handy way to translate or map PHP field names to serialized names: The Name Converter System. @@ -187,7 +187,7 @@ Given you have the following object:: And in the serialized form, all attributes must be prefixed by ``org_`` like the following:: - {"org_name": "Les-Tilleuls.coop", "org_address": "Euratechnologies, 2 rue Hegel, 59160 Lomme, France"} + {"org_name": "Acme SARL", "org_address": "Euratechnologies, 59000 Lille, France"} A custom Name Converter can handle such cases:: @@ -222,11 +222,11 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`:: $serializer = new Serializer(array(new JsonEncoder()), array($normalizer)); $obj = new Company(); - $obj->name = 'Les-Tilleuls.coop'; - $obj->address = 'Euratechnologies, 2 rue Hegel, 59160 Lomme, France'; + $obj->name = 'Acme SARL'; + $obj->address = 'Euratechnologies, 59000 Lille, France'; $json = $serializer->serialize($obj); - // {"org_name": "Les-Tilleuls.coop", "org_address": "Euratechnologies, 2 rue Hegel, 59160 Lomme, France"} + // {"org_name": "Acme SARL", "org_address": "Euratechnologies, 59000 Lille, France"} $objCopy = $serializer->deserialize($json); // Same data as $obj @@ -239,11 +239,11 @@ CamelCase to snake_case The :class:`Symfony\\Component\\Serializer\\NameConverter\\CamelCaseToUnderscoreNameConverter` interface was introduced in Symfony 2.7. -In many formats, it's common to use underscores to separate words (also know +In many formats, it's common to use underscores to separate words (also known as snake_case). However, PSR-1 specifies that the preferred style for PHP properties and methods is CamelCase. -Symfony provides a built-in Name Converter designed to translate between +Symfony provides a built-in name converter designed to transform between snake_case and CamelCased styles during serialization and deserialization processes:: From 044275258de92ffbc8258a69aca2cc79a8da30f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Mon, 29 Dec 2014 21:17:09 +0100 Subject: [PATCH 5/6] [Serializer] Acme things --- components/serializer.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index e57a06ade33..d04335364f2 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -187,7 +187,7 @@ Given you have the following object:: And in the serialized form, all attributes must be prefixed by ``org_`` like the following:: - {"org_name": "Acme SARL", "org_address": "Euratechnologies, 59000 Lille, France"} + {"org_name": "Acme Inc.", "org_address": "123 Main Street, Big City"} A custom Name Converter can handle such cases:: @@ -222,11 +222,11 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`:: $serializer = new Serializer(array(new JsonEncoder()), array($normalizer)); $obj = new Company(); - $obj->name = 'Acme SARL'; - $obj->address = 'Euratechnologies, 59000 Lille, France'; + $obj->name = 'Acme Inc.'; + $obj->address = '123 Main Street, Big City'; $json = $serializer->serialize($obj); - // {"org_name": "Acme SARL", "org_address": "Euratechnologies, 59000 Lille, France"} + // {"org_name": "Acme Inc.", "org_address": "123 Main Street, Big City"} $objCopy = $serializer->deserialize($json); // Same data as $obj From d335005f50779b2afb9014e47b4854ecbad2ef0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Wed, 11 Mar 2015 22:05:37 +0100 Subject: [PATCH 6/6] [Serializer] Fix CS --- components/serializer.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/components/serializer.rst b/components/serializer.rst index d04335364f2..c0ec038623c 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -170,7 +170,7 @@ Converting Property Names when Serializing and Deserializing interface was introduced in Symfony 2.7. Sometimes serialized attributes must be named differently than properties -or getter / setter methods of PHP classes. +or getter/setter methods of PHP classes. The Serializer Component provides a handy way to translate or map PHP field names to serialized names: The Name Converter System. @@ -183,13 +183,12 @@ Given you have the following object:: public address; } - And in the serialized form, all attributes must be prefixed by ``org_`` like the following:: {"org_name": "Acme Inc.", "org_address": "123 Main Street, Big City"} -A custom Name Converter can handle such cases:: +A custom name converter can handle such cases:: use Symfony\Component\Serializer\NameConverter\NameConverterInterface;