From 3895fc927b7dc14590469870dd4584e35a5fb1f5 Mon Sep 17 00:00:00 2001 From: dantleech Date: Fri, 27 May 2016 11:19:34 +0100 Subject: [PATCH 01/16] Documentation for YAML flags added in 3.1 --- components/yaml/introduction.rst | 98 +++++++++++++++++++++++--------- 1 file changed, 71 insertions(+), 27 deletions(-) diff --git a/components/yaml/introduction.rst b/components/yaml/introduction.rst index 3a1f313cf2c..d884ba5f734 100644 --- a/components/yaml/introduction.rst +++ b/components/yaml/introduction.rst @@ -127,17 +127,6 @@ error occurred: .. _components-yaml-dump: -Objects for Mappings -.................... - -Yaml :ref:`mappings ` are basically associative -arrays. You can instruct the parser to return mappings as objects (i.e. -``\stdClass`` instances) by setting the fourth argument to ``true``:: - - $object = Yaml::parse('{"foo": "bar"}', false, false, true); - echo get_class($object); // stdClass - echo $object->foo; // bar - Writing YAML Files ~~~~~~~~~~~~~~~~~~ @@ -214,30 +203,27 @@ changed using the third argument as follows:: foo: bar bar: baz -Invalid Types and Object Serialization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default the YAML component will encode any "unsupported" type (i.e. -resources and objects) as ``null``. +Advanced Usage: Flags +--------------------- -Instead of encoding as ``null`` you can choose to throw an exception if an invalid -type is encountered in either the dumper or parser as follows:: +.. versionadded:: 3.1 + Flags were introduced in Symfony 3.1 and replaced the earlier boolean + arguments. - // throw an exception if a resource or object is encountered - Yaml::dump($data, 2, 4, true); +Object Parsing and Dumping +~~~~~~~~~~~~~~~~~~~~~~~~~~ - // throw an exception if an encoded object is found in the YAML string - Yaml::parse($yaml, true); - -However, you can activate object support using the next argument:: +You can dump objects by using the ``DUMP_OBJECT`` flag:: $object = new \stdClass(); $object->foo = 'bar'; - $dumped = Yaml::dump($object, 2, 4, false, true); - // !!php/object:O:8:"stdClass":1:{s:5:"foo";s:7:"bar";} + $dumped = Yaml::dump($object, 2, 4, Yaml::DUMP_OBJECT); + // !php/object:O:8:"stdClass":1:{s:5:"foo";s:7:"bar";} + +And parse them by using the ``PARSE_OBJECT`` flag:: - $parsed = Yaml::parse($dumped, false, true); + $parsed = Yaml::parse($dumped, Yaml::PARSE_OBJECT); var_dump(is_object($parsed)); // true echo $parsed->foo; // bar @@ -250,6 +236,64 @@ representation of the object. parsers will likely not recognize the ``php/object`` tag and non-PHP implementations certainly won't - use with discretion! +.. _invalid-types-and-object-serialization: + +Handling Invalid Types +~~~~~~~~~~~~~~~~~~~~~~ + +By default the parser will encode invalid types as ``null``. You can make the +parser throw exceptions by using the ``PARSE_EXCEPTION_ON_INVALID_TYPE`` +flag:: + + $yaml = '!php/object:O:8:"stdClass":1:{s:5:"foo";s:7:"bar";}'; + Yaml::parse($yaml, Yaml::PARSE_EXCEPTION_ON_INVALID_TYPE); // throws an exception + +Similarly you can use ``DUMP_EXCEPTION_ON_INVALID_TYPE`` when dumping:: + + $data = new \stdClass(); // by default objects are invalid. + Yaml::parse($data, Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE); // throws an exception + +.. _objects-for-mappings: + + echo $yaml; // { foo: bar } + +Date Handling +~~~~~~~~~~~~~ + +By default the YAML parser will convert unquoted strings which look like a +date or a date-time into a Unix timestamp; for example ``2016-05-27`` or +``2016-05-27T02:59:43.1Z`` (ISO-8601_):: + + Yaml::parse('2016-05-27'); // 1464307200 + +You can make it convert to a ``DateTime`` instance by using the ``PARSE_DATETIME`` +flag:: + + $date = Yaml::parse('2016-05-27', Yaml::PARSE_DATETIME); + var_dump(get_class($date)); // DateTime + +Dumping Multi-line Literal Blocks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In YAML multiple lines can be represented as literal blocks, by default the +dumper will encode multiple lines as an inline string:: + + $string = array("string" => "Multiple\nLine\nString"); + $yaml = Yaml::dump($string); + echo $yaml; // string: "Multiple\nLine\nString" + +You can make it use a literal block with the ``DUMP_MULTI_LINE_LITERAL_BLOCK`` +flag:: + + $string = array("string" => "Multiple\nLine\nString"); + $yaml = Yaml::dump($string, 2, 4, Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK); + echo $yaml; + // string: | + // Multiple + // Line + // String + .. _YAML: http://yaml.org/ .. _Packagist: https://packagist.org/packages/symfony/yaml .. _`YAML 1.2 version specification`: http://yaml.org/spec/1.2/spec.html +.. _ISO-8601: http://www.iso.org/iso/iso8601 From dbdbf68deb7186354fc214f01c37173d6be95b95 Mon Sep 17 00:00:00 2001 From: Ener-Getick Date: Sun, 26 Jun 2016 11:08:10 +0200 Subject: [PATCH 02/16] [Serializer] Document the encoders --- components/index.rst | 2 +- components/map.rst.inc | 5 +- components/serializer/encoders.rst | 63 ++++++++++++ components/serializer/index.rst | 8 ++ .../introduction.rst} | 14 ++- cookbook/index.rst | 2 +- cookbook/map.rst.inc | 5 +- cookbook/serializer/custom_encoders.rst | 97 +++++++++++++++++++ cookbook/serializer/index.rst | 8 ++ .../introduction.rst} | 6 +- redirection_map | 2 + reference/dic_tags.rst | 4 +- 12 files changed, 200 insertions(+), 16 deletions(-) create mode 100644 components/serializer/encoders.rst create mode 100644 components/serializer/index.rst rename components/{serializer.rst => serializer/introduction.rst} (98%) create mode 100644 cookbook/serializer/custom_encoders.rst create mode 100644 cookbook/serializer/index.rst rename cookbook/{serializer.rst => serializer/introduction.rst} (98%) diff --git a/components/index.rst b/components/index.rst index 43aa14e5e40..8f8cdc08f35 100644 --- a/components/index.rst +++ b/components/index.rst @@ -28,7 +28,7 @@ The Components property_access/index routing/index security/index - serializer + serializer/index stopwatch templating/index translation/index diff --git a/components/map.rst.inc b/components/map.rst.inc index ee9c34ba884..a7dd126cb9b 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -140,9 +140,10 @@ * :doc:`/components/security/authorization` * :doc:`/components/security/secure_tools` -* **Serializer** +* :doc:`/components/serializer/index` - * :doc:`/components/serializer` + * :doc:`/components/serializer/introduction` + * :doc:`/components/serializer/encoders` * **Stopwatch** diff --git a/components/serializer/encoders.rst b/components/serializer/encoders.rst new file mode 100644 index 00000000000..9b268273d35 --- /dev/null +++ b/components/serializer/encoders.rst @@ -0,0 +1,63 @@ +.. index:: + single: Serializer, Encoders + +Encoders +======== + +Encoders basically turn **arrays** into **formats** and vice versa. +They implement +:class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface` for +encoding (array to format) and +:class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface` for +decoding (format to array). + +You can add new encoders to a Serializer instance by using its second constructor argument:: + + use Symfony\Component\Serializer\Serializer; + use Symfony\Component\Serializer\Encoder\XmlEncoder; + use Symfony\Component\Serializer\Encoder\JsonEncoder; + + $encoders = array(new XmlEncoder(), new JsonEncoder()); + $serializer = new Serializer(array(), $encoders); + +Built-in Encoders +----------------- + +Two encoders are used in the example above: + +* :class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder` to encode/decode XML +* :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` to encode/decode JSON + +The ``XmlEncoder`` +~~~~~~~~~~~~~~~~~~ + +This encoder transforms arrays into XML and vice versa. + +For example, take an object normalized as following:: + + array('foo' => array(1, 2), 'bar' => true); + +The ``XmlEncoder`` will encode this object like that:: + + + + 1 + 2 + 1 + + +Be aware that this encoder will consider keys beginning with ``@`` as attributes:: + + $encoder = new XmlEncoder(); + $encoder->encode(array('foo' => array('@bar' => 'value'))); + // will return: + // + // + // + // + +The ``JsonEncoder`` +~~~~~~~~~~~~~~~~~~~ + +The ``JsonEncoder`` is much simpler and is based on the PHP +:phpfunction:`json_encode` and :phpfunction:`json_decode` functions. diff --git a/components/serializer/index.rst b/components/serializer/index.rst new file mode 100644 index 00000000000..d2493f383ed --- /dev/null +++ b/components/serializer/index.rst @@ -0,0 +1,8 @@ +Serializer +========== + +.. toctree:: + :maxdepth: 2 + + introduction + encoders diff --git a/components/serializer.rst b/components/serializer/introduction.rst similarity index 98% rename from components/serializer.rst rename to components/serializer/introduction.rst index c8354d9713e..d67bcbdaca0 100644 --- a/components/serializer.rst +++ b/components/serializer/introduction.rst @@ -44,7 +44,7 @@ Usage Using the Serializer component is really simple. You just need to set up the :class:`Symfony\\Component\\Serializer\\Serializer` specifying -which Encoders and Normalizer are going to be available:: +which encoders and normalizers are going to be available:: use Symfony\Component\Serializer\Serializer; use Symfony\Component\Serializer\Encoder\XmlEncoder; @@ -57,10 +57,14 @@ which Encoders and Normalizer are going to be available:: $serializer = new Serializer($normalizers, $encoders); The preferred normalizer is the -:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`, but other -normalizers are available. -To read more about them, refer to the `Normalizers`_ section of this page. All -the examples shown below use the ``ObjectNormalizer``. +:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`, +but other normalizers are available. All the examples shown below use +the ``ObjectNormalizer``. + +.. seealso:: + + Read the dedicated sections to learn more about :doc:`/components/serializer/encoders` + and `Normalizers`_. Serializing an Object --------------------- diff --git a/cookbook/index.rst b/cookbook/index.rst index f6ee4386b87..687e9fb7933 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -26,7 +26,7 @@ The Cookbook request/index routing/index security/index - serializer + serializer/index service_container/index session/index symfony1 diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index bbef8f68661..207ab5c1334 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -187,9 +187,10 @@ * :doc:`/cookbook/security/securing_services` * :doc:`/cookbook/security/access_control` -* **Serializer** +* :doc:`/cookbook/serializer/index` - * :doc:`/cookbook/serializer` + * :doc:`/cookbook/serializer/introduction` + * :doc:`/cookbook/serializer/custom_encoders` * :doc:`/cookbook/service_container/index` diff --git a/cookbook/serializer/custom_encoders.rst b/cookbook/serializer/custom_encoders.rst new file mode 100644 index 00000000000..5cacea05984 --- /dev/null +++ b/cookbook/serializer/custom_encoders.rst @@ -0,0 +1,97 @@ +.. index:: + single: Serializer; Custom encoders + +How to Create your Custom Encoder +================================= + +The :doc:`Serializer Component ` uses Normalizers +to transform any data to an array that can be then converted in whatever +data-structured language you want thanks to Encoders. + +The Component provides several built-in encoders that are described +:doc:`in their own section ` but you may want +to use another language not supported. + +Creating a new encoder +---------------------- + +Imagine you want to serialize and deserialize Yaml. For that you'll have to +create your own encoder that may use the +:doc:`Yaml Component `:: + + namespace AppBundle\Encoder; + + use Symfony\Component\Serializer\Encoder\DecoderInterface; + use Symfony\Component\Serializer\Encoder\EncoderInterface; + use Symfony\Component\Yaml\Yaml; + + class YamlEncoder implements EncoderInterface, DecoderInterface + { + public function encode($data, $format, array $context = array()) + { + return Yaml::dump($data); + } + + public function supportsEncoding($format) + { + return 'yaml' === $format; + } + + public function decode($data, $format, array $context = array()) + { + return Yaml::parse($data); + } + + public function supportsDecoding($format) + { + return 'yaml' === $format; + } + } + +Registering it in your app +-------------------------- + +If you use the Symfony Framework then you probably want to register this encoder +as a service in your app. Then you only need to tag it as `serializer.encoder` and it will be +injected in the Serializer. + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/services.yml + services: + app.encoder.yaml: + class: AppBundle\Encoder\YamlEncoder + tags: + - { name: serializer.encoder } + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/services.php + $container + ->register( + 'app.encoder.yaml', + 'AppBundle\Encoder\YamlEncoder' + ) + ->addTag('serializer.encoder') + ; + +Now you'll be able to serialize and deserialize Yaml! + +.. _tracker: https://github.com/symfony/symfony/issues diff --git a/cookbook/serializer/index.rst b/cookbook/serializer/index.rst new file mode 100644 index 00000000000..7578be22c61 --- /dev/null +++ b/cookbook/serializer/index.rst @@ -0,0 +1,8 @@ +Serializer +========== + +.. toctree:: + :maxdepth: 2 + + introduction + custom_encoders diff --git a/cookbook/serializer.rst b/cookbook/serializer/introduction.rst similarity index 98% rename from cookbook/serializer.rst rename to cookbook/serializer/introduction.rst index 00e8d70f939..74d9cb77183 100644 --- a/cookbook/serializer.rst +++ b/cookbook/serializer/introduction.rst @@ -1,16 +1,16 @@ .. index:: - single: Serializer + single: Serializer; Introduction How to Use the Serializer ========================= Serializing and deserializing to and from objects and different formats (e.g. JSON or XML) is a very complex topic. Symfony comes with a -:doc:`Serializer Component `, which gives you some +:doc:`Serializer Component `, which gives you some tools that you can leverage for your solution. In fact, before you start, get familiar with the serializer, normalizers -and encoders by reading the :doc:`Serializer Component `. +and encoders by reading the :doc:`Serializer Component `. Activating the Serializer ------------------------- diff --git a/redirection_map b/redirection_map index faf3e0fd638..cfa75bed667 100644 --- a/redirection_map +++ b/redirection_map @@ -10,6 +10,7 @@ /cookbook/email /cookbook/email/email /cookbook/gmail /cookbook/email/gmail /cookbook/console /components/console +/cookbook/serializer /cookbook/serializer/introduction /cookbook/tools/autoloader /components/class_loader /cookbook/tools/finder /components/finder /cookbook/service_container/parentservices /components/dependency_injection/parentservices @@ -26,6 +27,7 @@ /components/yaml /components/yaml/introduction /components/templating /components/templating/introduction /components/filesystem /components/filesystem/introduction +/components/serializer /components/serializer/introduction /cmf/reference/configuration/block /cmf/bundles/block/configuration /cmf/reference/configuration/content /cmf/bundles/content/configuration /cmf/reference/configuration/core /cmf/bundles/core/configuration diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index 2d847f0a1aa..0dbaf95b312 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -946,7 +946,7 @@ serializer.encoder The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface` and :class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface`. -For more details, see :doc:`/cookbook/serializer`. +For more details, see :doc:`/cookbook/serializer/introduction`. .. _reference-dic-tags-serializer-normalizer: @@ -958,7 +958,7 @@ serializer.normalizer The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface` and :class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface`. -For more details, see :doc:`/cookbook/serializer`. +For more details, see :doc:`/cookbook/serializer/introduction`. swiftmailer.default.plugin -------------------------- From 3b39d871ac16d62d3a84b19aee8f9db90d1fb12f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 2 Sep 2016 08:36:19 +0200 Subject: [PATCH 03/16] Fixed indentation issues in alias_private article --- service_container/alias_private.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/service_container/alias_private.rst b/service_container/alias_private.rst index 00b94fe42ae..6912918c375 100644 --- a/service_container/alias_private.rst +++ b/service_container/alias_private.rst @@ -30,9 +30,9 @@ to be *not* public (i.e. private): .. code-block:: yaml services: - foo: - class: Example\Foo - public: false + foo: + class: Example\Foo + public: false .. code-block:: xml @@ -87,11 +87,11 @@ services. .. code-block:: yaml services: - app.phpmailer: - class: AppBundle\Mail\PhpMailer + app.phpmailer: + class: AppBundle\Mail\PhpMailer - app.mailer: - alias: app.phpmailer + app.mailer: + alias: app.phpmailer .. code-block:: xml From 2fecab535897aaeaecfcac017bc1e80316196a55 Mon Sep 17 00:00:00 2001 From: Kevin T'Syen Date: Tue, 6 Sep 2016 14:53:20 +0200 Subject: [PATCH 04/16] Update tags.rst I think there is a typo with acme_mailer.transport, this should be app.mail_transport since you are using the app.mail_transport on any other place. --- service_container/tags.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index 93e2d8214c8..6ab22faf53a 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -195,7 +195,7 @@ Create a Compiler Pass ~~~~~~~~~~~~~~~~~~~~~~ You can now use a :ref:`compiler pass ` to ask the -container for any services with the ``acme_mailer.transport`` tag:: +container for any services with the ``app.mail_transport`` tag:: // src/AppBundle/DependencyInjection/Compiler/MailTransportPass.php namespace AppBundle\DependencyInjection\Compiler; From 8b28f02cd6e507594a2738d5910cfc78aa983928 Mon Sep 17 00:00:00 2001 From: Andrei Chugunov Date: Tue, 6 Sep 2016 18:25:49 +0400 Subject: [PATCH 05/16] Typo in the class name. --- reference/constraints/UserPassword.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/UserPassword.rst b/reference/constraints/UserPassword.rst index caa792b8776..594027ec889 100644 --- a/reference/constraints/UserPassword.rst +++ b/reference/constraints/UserPassword.rst @@ -24,7 +24,7 @@ password, but needs to enter their old password for security. Basic Usage ----------- -Suppose you have a ``PasswordChange`` class, that's used in a form where +Suppose you have a ``ChangePassword`` class, that's used in a form where the user can change their password by entering their old password and a new password. This constraint will validate that the old password matches the user's current password: From a2bf25bab811ac0dd36e7313336d515dd3b0a19a Mon Sep 17 00:00:00 2001 From: Sven Luijten Date: Tue, 13 Sep 2016 16:15:05 +0200 Subject: [PATCH 06/16] fix typo --- components/validator/resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/validator/resources.rst b/components/validator/resources.rst index da0698b9184..37581c0c2ed 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -42,7 +42,7 @@ In this example, the validation metadata is retrieved executing the { protected $name; - public static function loadValidatorMatadata(ClassMetadata $metadata) + public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('name', new Assert\NotBlank()); $metadata->addPropertyConstraint('name', new Asert\Length(array( From 20b3b378d3014e218bc6211b2f66d8045011775a Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 17 Sep 2016 14:42:37 -0400 Subject: [PATCH 07/16] [#6622] Fixing bad placement of anchor --- components/yaml.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/yaml.rst b/components/yaml.rst index a2e8656bfda..df811f1004f 100644 --- a/components/yaml.rst +++ b/components/yaml.rst @@ -210,6 +210,8 @@ Advanced Usage: Flags Flags were introduced in Symfony 3.1 and replaced the earlier boolean arguments. +.. _objects-for-mappings: + Object Parsing and Dumping ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -253,8 +255,6 @@ Similarly you can use ``DUMP_EXCEPTION_ON_INVALID_TYPE`` when dumping:: $data = new \stdClass(); // by default objects are invalid. Yaml::parse($data, Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE); // throws an exception -.. _objects-for-mappings: - echo $yaml; // { foo: bar } Date Handling From f2e29144f17aef46807dc869142753b3791aeabe Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 17 Sep 2016 14:47:12 -0400 Subject: [PATCH 08/16] [#6622] Changing line from parse() to dump() --- components/yaml.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/yaml.rst b/components/yaml.rst index df811f1004f..e26f7c70736 100644 --- a/components/yaml.rst +++ b/components/yaml.rst @@ -253,7 +253,7 @@ flag:: Similarly you can use ``DUMP_EXCEPTION_ON_INVALID_TYPE`` when dumping:: $data = new \stdClass(); // by default objects are invalid. - Yaml::parse($data, Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE); // throws an exception + Yaml::dump($data, Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE); // throws an exception echo $yaml; // { foo: bar } From 3c1ae4a9eeb3d73de378163e86e49776ab2c20bb Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 18 Sep 2016 16:13:58 -0400 Subject: [PATCH 09/16] [#6649] Changing a note to a caution - this *is* a gotcha --- forms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/forms.rst b/forms.rst index fa48db276d1..91012b646c8 100644 --- a/forms.rst +++ b/forms.rst @@ -573,7 +573,7 @@ the correct values of a number of field options. guessed from the validation constraints (if ``Length`` or ``Range`` is used) or from the Doctrine metadata (via the field's length). -.. note:: +.. caution:: These field options are *only* guessed if you're using Symfony to guess the field type (i.e. omit or pass ``null`` as the second argument to ``add()``). From 33e5b768b3da3164472724877ee667c26c21b8d6 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 18 Sep 2016 16:26:11 -0400 Subject: [PATCH 10/16] Moving files into the new structure --- .../{serializer/introduction.rst => serializer.rst} | 7 +------ components/serializer/index.rst | 8 -------- serializer.rst | 10 ++++++++-- .../serializer => serializer}/custom_encoders.rst | 0 {components/serializer => serializer}/encoders.rst | 0 5 files changed, 9 insertions(+), 16 deletions(-) rename components/{serializer/introduction.rst => serializer.rst} (99%) delete mode 100644 components/serializer/index.rst rename {cookbook/serializer => serializer}/custom_encoders.rst (100%) rename {components/serializer => serializer}/encoders.rst (100%) diff --git a/components/serializer/introduction.rst b/components/serializer.rst similarity index 99% rename from components/serializer/introduction.rst rename to components/serializer.rst index b704d1d3891..4d37c9d16d5 100644 --- a/components/serializer/introduction.rst +++ b/components/serializer.rst @@ -44,7 +44,7 @@ Usage Using the Serializer component is really simple. You just need to set up the :class:`Symfony\\Component\\Serializer\\Serializer` specifying -which encoders and normalizers are going to be available:: +which encoders and normalizer are going to be available:: use Symfony\Component\Serializer\Serializer; use Symfony\Component\Serializer\Encoder\XmlEncoder; @@ -61,11 +61,6 @@ The preferred normalizer is the but other normalizers are available. All the examples shown below use the ``ObjectNormalizer``. -.. seealso:: - - Read the dedicated sections to learn more about :doc:`/components/serializer/encoders` - and `Normalizers`_. - Serializing an Object --------------------- diff --git a/components/serializer/index.rst b/components/serializer/index.rst deleted file mode 100644 index d2493f383ed..00000000000 --- a/components/serializer/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Serializer -========== - -.. toctree:: - :maxdepth: 2 - - introduction - encoders diff --git a/serializer.rst b/serializer.rst index 097a13cfcc5..005455f590a 100644 --- a/serializer.rst +++ b/serializer.rst @@ -226,8 +226,8 @@ A service leveraging `APCu`_ (and APC for PHP < 5.5) is built-in. ), )); -Going Further with the Serializer Component -------------------------------------------- +Going Further with the Serializer +--------------------------------- `ApiPlatform`_ provides an API system supporting `JSON-LD`_ and `Hydra Core Vocabulary`_ hypermedia formats. It is built on top of the Symfony Framework and its Serializer @@ -237,6 +237,12 @@ and a caching system. If you want to leverage the full power of the Symfony Serializer component, take a look at how this bundle works. +.. toctree:: + :maxdepth: 1 + :glob: + + serializer/* + .. _`APCu`: https://github.com/krakjoe/apcu .. _`ApiPlatform`: https://github.com/api-platform/core .. _`JSON-LD`: http://json-ld.org diff --git a/cookbook/serializer/custom_encoders.rst b/serializer/custom_encoders.rst similarity index 100% rename from cookbook/serializer/custom_encoders.rst rename to serializer/custom_encoders.rst diff --git a/components/serializer/encoders.rst b/serializer/encoders.rst similarity index 100% rename from components/serializer/encoders.rst rename to serializer/encoders.rst From 73172c6d6e7366e300d33a9cd138b48a130ea1d6 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 18 Sep 2016 16:31:55 -0400 Subject: [PATCH 11/16] updating links --- serializer/custom_encoders.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/serializer/custom_encoders.rst b/serializer/custom_encoders.rst index 5cacea05984..4991b41fbf7 100644 --- a/serializer/custom_encoders.rst +++ b/serializer/custom_encoders.rst @@ -4,12 +4,12 @@ How to Create your Custom Encoder ================================= -The :doc:`Serializer Component ` uses Normalizers +The :doc:`Serializer Component ` uses Normalizers to transform any data to an array that can be then converted in whatever data-structured language you want thanks to Encoders. The Component provides several built-in encoders that are described -:doc:`in their own section ` but you may want +:doc:`in their own section ` but you may want to use another language not supported. Creating a new encoder @@ -17,7 +17,7 @@ Creating a new encoder Imagine you want to serialize and deserialize Yaml. For that you'll have to create your own encoder that may use the -:doc:`Yaml Component `:: +:doc:`Yaml Component `:: namespace AppBundle\Encoder; From f99663a3ee5842f2ebd600d7dec52b1ff9783d4f Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 18 Sep 2016 16:32:36 -0400 Subject: [PATCH 12/16] removing cookbook entries --- cookbook/serializer/index.rst | 8 - cookbook/serializer/introduction.rst | 241 --------------------------- 2 files changed, 249 deletions(-) delete mode 100644 cookbook/serializer/index.rst delete mode 100644 cookbook/serializer/introduction.rst diff --git a/cookbook/serializer/index.rst b/cookbook/serializer/index.rst deleted file mode 100644 index 7578be22c61..00000000000 --- a/cookbook/serializer/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Serializer -========== - -.. toctree:: - :maxdepth: 2 - - introduction - custom_encoders diff --git a/cookbook/serializer/introduction.rst b/cookbook/serializer/introduction.rst deleted file mode 100644 index 74d9cb77183..00000000000 --- a/cookbook/serializer/introduction.rst +++ /dev/null @@ -1,241 +0,0 @@ -.. index:: - single: Serializer; Introduction - -How to Use the Serializer -========================= - -Serializing and deserializing to and from objects and different formats (e.g. -JSON or XML) is a very complex topic. Symfony comes with a -:doc:`Serializer Component `, which gives you some -tools that you can leverage for your solution. - -In fact, before you start, get familiar with the serializer, normalizers -and encoders by reading the :doc:`Serializer Component `. - -Activating the Serializer -------------------------- - -.. versionadded:: 2.3 - The Serializer has always existed in Symfony, but prior to Symfony 2.3, - you needed to build the ``serializer`` service yourself. - -The ``serializer`` service is not available by default. To turn it on, activate -it in your configuration: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - # ... - serializer: - enabled: true - - .. code-block:: xml - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'serializer' => array( - 'enabled' => true, - ), - )); - -Using the Serializer Service ----------------------------- - -Once enabled, the ``serializer`` service can be injected in any service where -you need it or it can be used in a controller like the following:: - - // src/AppBundle/Controller/DefaultController.php - namespace AppBundle\Controller; - - use Symfony\Bundle\FrameworkBundle\Controller\Controller; - - class DefaultController extends Controller - { - public function indexAction() - { - $serializer = $this->get('serializer'); - - // ... - } - } - -Adding Normalizers and Encoders -------------------------------- - -.. versionadded:: 2.7 - The :class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer` - is enabled by default in Symfony 2.7. In prior versions, you needed to load - your own normalizer. - -Once enabled, the ``serializer`` service will be available in the container -and will be loaded with two :ref:`encoders ` -(:class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` and -:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`) and the -:ref:`ObjectNormalizer normalizer `. - -You can load normalizers and/or encoders by tagging them as -:ref:`serializer.normalizer ` and -:ref:`serializer.encoder `. It's also -possible to set the priority of the tag in order to decide the matching order. - -Here is an example on how to load the -:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/services.yml - services: - get_set_method_normalizer: - class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer - tags: - - { name: serializer.normalizer } - - .. code-block:: xml - - - - - - - - - .. code-block:: php - - // app/config/services.php - use Symfony\Component\DependencyInjection\Definition; - - $definition = new Definition( - 'Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer' - )); - $definition->addTag('serializer.normalizer'); - $container->setDefinition('get_set_method_normalizer', $definition); - -.. _cookbook-serializer-using-serialization-groups-annotations: - -Using Serialization Groups Annotations --------------------------------------- - -.. versionadded:: 2.7 - Support for serialization groups was introduced in Symfony 2.7. - -Enable :ref:`serialization groups annotation ` -with the following configuration: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - # ... - serializer: - enable_annotations: true - - .. code-block:: xml - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'serializer' => array( - 'enable_annotations' => true, - ), - )); - -Next, add the :ref:`@Groups annotations ` -to your class and choose which groups to use when serializing:: - - $serializer = $this->get('serializer'); - $json = $serializer->serialize( - $someObject, - 'json', array('groups' => array('group1')) - ); - -In addition to the ``@Groups`` annotation, the Serializer component also -supports Yaml or XML files. These files are automatically loaded when being -stored in one of the following locations: - -* The ``serialization.yml`` or ``serialization.xml`` file in - the ``Resources/config/`` directory of a bundle; -* All ``*.yml`` and ``*.xml`` files in the ``Resources/config/serialization/`` - directory of a bundle. - -.. _cookbook-serializer-enabling-metadata-cache: - -Enabling the Metadata Cache ---------------------------- - -.. versionadded:: 2.7 - Serializer metadata and the ability to cache them were introduced in - Symfony 2.7. - -Metadata used by the Serializer component such as groups can be cached to -enhance application performance. Any service implementing the ``Doctrine\Common\Cache\Cache`` -interface can be used. - -A service leveraging `APCu`_ (and APC for PHP < 5.5) is built-in. - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config_prod.yml - framework: - # ... - serializer: - cache: serializer.mapping.cache.apc - - .. code-block:: xml - - - - - - - - .. code-block:: php - - // app/config/config_prod.php - $container->loadFromExtension('framework', array( - // ... - 'serializer' => array( - 'cache' => 'serializer.mapping.cache.apc', - ), - )); - -Going Further with the Serializer Component -------------------------------------------- - -`ApiPlatform`_ provides an API system supporting `JSON-LD`_ and `Hydra Core Vocabulary`_ -hypermedia formats. It is built on top of the Symfony Framework and its Serializer -component. It provides custom normalizers and a custom encoder, custom metadata -and a caching system. - -If you want to leverage the full power of the Symfony Serializer component, -take a look at how this bundle works. - -.. _`APCu`: https://github.com/krakjoe/apcu -.. _`ApiPlatform`: https://github.com/api-platform/core -.. _`JSON-LD`: http://json-ld.org -.. _`Hydra Core Vocabulary`: http://hydra-cg.com From 10b2fa33b6a734ee3624b685572fbe5824d97e67 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 18 Sep 2016 16:37:27 -0400 Subject: [PATCH 13/16] Minor language tweaks --- serializer/custom_encoders.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/serializer/custom_encoders.rst b/serializer/custom_encoders.rst index 4991b41fbf7..7c573ec2527 100644 --- a/serializer/custom_encoders.rst +++ b/serializer/custom_encoders.rst @@ -5,18 +5,18 @@ How to Create your Custom Encoder ================================= The :doc:`Serializer Component ` uses Normalizers -to transform any data to an array that can be then converted in whatever -data-structured language you want thanks to Encoders. +to transform any data to an array. Then, by leveraging *Encoders*, that data can +be convereted into any data-structure (e.g. JSON). The Component provides several built-in encoders that are described :doc:`in their own section ` but you may want -to use another language not supported. +to use another structure that's not supported. Creating a new encoder ---------------------- Imagine you want to serialize and deserialize Yaml. For that you'll have to -create your own encoder that may use the +create your own encoder that uses the :doc:`Yaml Component `:: namespace AppBundle\Encoder; @@ -51,9 +51,9 @@ create your own encoder that may use the Registering it in your app -------------------------- -If you use the Symfony Framework then you probably want to register this encoder -as a service in your app. Then you only need to tag it as `serializer.encoder` and it will be -injected in the Serializer. +If you use the Symfony Framework. then you probably want to register this encoder +as a service in your app. Then, you only need to tag it with ``serializer.encoder`` +to inject your custom encoder into the Serializer. .. configuration-block:: From e151754b07d30abeeb8b867e30550ae5ffeb2a9a Mon Sep 17 00:00:00 2001 From: Charcosset Johnny Date: Mon, 29 Aug 2016 10:58:17 +0200 Subject: [PATCH 14/16] Method "$this->getMock()" is depreciated --- form/unit_testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/form/unit_testing.rst b/form/unit_testing.rst index 00d4eeefd5c..276fb0fc386 100644 --- a/form/unit_testing.rst +++ b/form/unit_testing.rst @@ -132,7 +132,7 @@ make sure the ``FormRegistry`` uses the created instance:: protected function setUp() { // mock any dependencies - $this->entityManager = $this->getMock('Doctrine\Common\Persistence\ObjectManager'); + $this->entityManager = $this->getMockBuilder('Doctrine\Common\Persistence\ObjectManager')->getMock(); parent::setUp(); } From c52839a6461c1cadb41b98497efd56bcd8bfa3f9 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 18 Sep 2016 19:32:07 -0400 Subject: [PATCH 15/16] [#6925] Removing more instances of the deprecated getMock() --- create_framework/unit_testing.rst | 10 +++++----- form/unit_testing.rst | 2 +- testing/database.rst | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/create_framework/unit_testing.rst b/create_framework/unit_testing.rst index 82efc2f0fef..3a852745141 100644 --- a/create_framework/unit_testing.rst +++ b/create_framework/unit_testing.rst @@ -89,7 +89,7 @@ We are now ready to write our first test:: private function getFrameworkForException($exception) { - $matcher = $this->getMock('Symfony\Component\Routing\Matcher\UrlMatcherInterface'); + $matcher = $this->createMock('Symfony\Component\Routing\Matcher\UrlMatcherInterface'); $matcher ->expects($this->once()) ->method('match') @@ -98,9 +98,9 @@ We are now ready to write our first test:: $matcher ->expects($this->once()) ->method('getContext') - ->will($this->returnValue($this->getMock('Symfony\Component\Routing\RequestContext'))) + ->will($this->returnValue($this->createMock('Symfony\Component\Routing\RequestContext'))) ; - $resolver = $this->getMock('Symfony\Component\HttpKernel\Controller\ControllerResolverInterface'); + $resolver = $this->createMock('Symfony\Component\HttpKernel\Controller\ControllerResolverInterface'); return new Framework($matcher, $resolver); } @@ -144,7 +144,7 @@ Response:: public function testControllerResponse() { - $matcher = $this->getMock('Symfony\Component\Routing\Matcher\UrlMatcherInterface'); + $matcher = $this->createMock('Symfony\Component\Routing\Matcher\UrlMatcherInterface'); $matcher ->expects($this->once()) ->method('match') @@ -159,7 +159,7 @@ Response:: $matcher ->expects($this->once()) ->method('getContext') - ->will($this->returnValue($this->getMock('Symfony\Component\Routing\RequestContext'))) + ->will($this->returnValue($this->createMock('Symfony\Component\Routing\RequestContext'))) ; $resolver = new ControllerResolver(); diff --git a/form/unit_testing.rst b/form/unit_testing.rst index 3638a9f7cac..b5302a446c5 100644 --- a/form/unit_testing.rst +++ b/form/unit_testing.rst @@ -185,7 +185,7 @@ allows you to return a list of extensions to register:: { protected function getExtensions() { - $validator = $this->getMock('\Symfony\Component\Validator\Validator\ValidatorInterface'); + $validator = $this->createMock('\Symfony\Component\Validator\Validator\ValidatorInterface'); $validator->method('validate')->will($this->returnValue(new ConstraintViolationList())); return array( diff --git a/testing/database.rst b/testing/database.rst index b252cfc0640..5eeb90ffd00 100644 --- a/testing/database.rst +++ b/testing/database.rst @@ -66,7 +66,7 @@ it's easy to pass a mock object within a test:: public function testCalculateTotalSalary() { // First, mock the object to be used in the test - $employee = $this->getMock('\AppBundle\Entity\Employee'); + $employee = $this->createMock('\AppBundle\Entity\Employee'); $employee->expects($this->once()) ->method('getSalary') ->will($this->returnValue(1000)); From f767fb792fd558cfabaa9438a3deff99185cc6a6 Mon Sep 17 00:00:00 2001 From: Charles Sarrazin Date: Mon, 19 Sep 2016 19:54:27 +0200 Subject: [PATCH 16/16] Updated LDAP documentation for Symfony 3.1 --- components/ldap.rst | 83 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 70 insertions(+), 13 deletions(-) diff --git a/components/ldap.rst b/components/ldap.rst index b1f51043dd4..08caf908fb0 100644 --- a/components/ldap.rst +++ b/components/ldap.rst @@ -20,10 +20,10 @@ You can install the component in 2 different ways: Usage ----- -The :class:`Symfony\\Component\\Ldap\\LdapClient` class provides methods +The :class:`Symfony\\Component\\Ldap\\Ldap` class provides methods to authenticate and query against an LDAP server. -The :class:`Symfony\\Component\\Ldap\\LdapClient` class can be configured +The :class:`Symfony\\Component\\Ldap\\Ldap` class can be configured using the following options: ``host`` @@ -35,11 +35,11 @@ using the following options: ``version`` The version of the LDAP protocol to use -``useSsl`` - Whether or not to secure the connection using SSL +``encryption`` + Your encryption mechanism (``ssl``, ``tls`` or ``none``) -``useStartTls`` - Whether or not to secure the connection using StartTLS +``connection_string`` + You may use this option instead of ``optReferrals`` Specifies whether to automatically follow referrals @@ -47,26 +47,83 @@ using the following options: For example, to connect to a start-TLS secured LDAP server:: - use Symfony\Component\Ldap\LdapClient; + use Symfony\Component\Ldap\Ldap; - $ldap = new LdapClient('my-server', 389, 3, false, true); + $ldap = Ldap::create('ext_ldap', array( + 'host' => 'my-server', + 'encryption' => 'ssl', + )); -The :method:`Symfony\\Component\\Ldap\\LdapClient::bind` method +Or you could directly specify a connection string:: + + use Symfony\Component\Ldap\Ldap; + + $ldap = Ldap::create('ext_ldap', array('connection_string' => 'ldaps://my-server:636')); + +The :method:`Symfony\\Component\\Ldap\\Ldap::bind` method authenticates a previously configured connection using both the distinguished name (DN) and the password of a user:: - use Symfony\Component\Ldap\LdapClient; + use Symfony\Component\Ldap\Ldap; // ... $ldap->bind($dn, $password); Once bound (or if you enabled anonymous authentication on your LDAP server), you may query the LDAP server using the -:method:`Symfony\\Component\\Ldap\\LdapClient::find` method:: +:method:`Symfony\\Component\\Ldap\\Ldap::query` method:: + + use Symfony\Component\Ldap\Ldap; + // ... + + $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))'); + $results = $query->execute(); + + foreach ($results as $entry) { + // Do something with the results + } + +By default, LDAP entries are lazy-loaded. If you wish to fetch +all entries in a single call and do something with the results' +array, you may use the +:method:`Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\Collection::toArray` method:: + + use Symfony\Component\Ldap\Ldap; + // ... + + $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))'); + $results = $query->execute()->toArray(); + + // Do something with the results array + +Creating or updating entries +---------------------------- + +Since version 3.1, The Ldap component provides means to create +new LDAP entries, update or even delete existing ones:: - use Symfony\Component\Ldap\LdapClient; + use Symfony\Component\Ldap\Ldap; + use Symfony\Component\Ldap\Entry; // ... - $ldap->find('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))'); + $entry = new Entry('cn=Fabien Potencier,dc=symfony,dc=com', array( + 'sn' => array('fabpot'), + 'objectClass' => array('inetOrgPerson'), + )); + + $em = $ldap->getEntryManager(); + + // Creating a new entry + $em->add($entry); + + // Finding and updating an existing entry + $query = $ldap->query('dc=symfony,dc=com', '(&(objectclass=person)(ou=Maintainers))'); + $result = $query->execute(); + $entry = $result[0]; + $entry->addAttribute('email', array('fabpot@symfony.com')); + $em->update($entry); + + // Removing an existing entry + $em->remove(new Entry('cn=Test User,dc=symfony,dc=com')); .. _Packagist: https://packagist.org/packages/symfony/ldap