minor #7231 Add documentation for XmlEncoder context param (amoiraud, javiereguiluz)

javiereguiluz · javiereguiluz · commit aa036af893fd · 2018-01-05T11:30:33.000+01:00
This PR was submitted for the master branch but it was merged into the 3.3 branch instead (closes #7231). Discussion ---------- Add documentation for XmlEncoder context param Add documentation for XmlEncoder context param Related to : symfony/symfony#20524 This fixes #7227 Commits ------- 5e23045 Minor tweaks adbc7b2 Minor rewords 2dc6ed3 Minor syntax issue 6050370 Minor syntax issues and some rewordings 2f3cf02 Correcting my bad english with a bilingual friend 60c7657 Add XmlEncoder documentation with $context available options 04af434 erratum c83e59d Add XmlEncoder documentation with $context available options
diff --git a/components/serializer.rst b/components/serializer.rst
@@ -857,6 +857,63 @@ you indicate that you're expecting an array instead of a single object.
     $data = ...; // The serialized data from the previous example
     $persons = $serializer->deserialize($data, 'Acme\Person[]', '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`` encodes this object as follows:
+
+.. code-block:: xml
+
+    <?xml version="1.0"?>
+    <response>
+        <foo>1</foo>
+        <foo>2</foo>
+        <bar>1</bar>
+    </response>
+
+The array keys beginning with ``@`` are considered XML attributes::
+
+    array('foo' => array('@bar' => 'value'));
+
+    // is encoded as follows:
+    // <?xml version="1.0"?>
+    // <response>
+    //     <foo bar="value" />
+    // </response>
+
+Context
+~~~~~~~
+
+The ``encode()`` method defines a third optional parameter called ``context``
+which defines the configuration options for the XmlEncoder an associative array::
+
+    $xmlEncoder->encode($array, 'xml', $context);
+
+These are the options available:
+
+``xml_format_output``
+    If set to true, formats the generated XML with line breaks and indentation.
+
+``xml_version``
+    Sets the XML version attribute (default: ``1.1``).
+
+``xml_encoding``
+    Sets the XML encoding attribute (default: ``utf-8``).
+
+``xml_standalone``
+    Adds standalone attribute in the generated XML (default: ``true``).
+
+``xml_root_node_name``
+    Sets the root node name (default: ``response``).
+
+``remove_empty_tags``
+    If set to true, removes all empty tags in the generated XML.
+
 Recursive Denormalization and Type Safety
 -----------------------------------------
 
@@ -924,6 +981,47 @@ When a ``PropertyTypeExtractor`` is available, the normalizer will also check th
 matches the type of the property (even for primitive types). For instance, if a ``string`` is provided, but
 the type of the property is ``int``, an :class:`Symfony\\Component\\Serializer\\Exception\\UnexpectedValueException`
 will be thrown.
+=======
+
+=======
+
+>>>>>>> Minor rewords
+Context
+~~~~~~~
+
+The ``encode()`` method defines a third optional parameter called ``context``
+which defines the configuration options for the XmlEncoder an associative array::
+
+    $xmlEncoder->encode($array, 'xml', $context);
+
+These are the options available:
+<<<<<<< HEAD
+
+=======
+
+>>>>>>> Minor rewords
+``xml_format_output``
+    If set to true, formats the generated XML with line breaks and indentation.
+
+``xml_version``
+    Sets the XML version attribute (default: ``1.1``).
+
+``xml_encoding``
+    Sets the XML encoding attribute (default: ``utf-8``).
+
+``xml_standalone``
+    Adds standalone attribute in the generated XML (default: ``true``).
+
+``xml_root_node_name``
+    Sets the root node name (default: ``response``).
+
+``remove_empty_tags``
+<<<<<<< HEAD
+    If set to true, remove all empty tags in the XML output.
+>>>>>>> Minor syntax issues and some rewordings
+=======
+    If set to true, removes all empty tags in the generated XML.
+>>>>>>> Minor rewords
 
 Learn more
 ----------
