From 96802d1671c90d81b83df6bf34c618a1cb3e6437 Mon Sep 17 00:00:00 2001
From: Dmytro Liashko <dmlyashko@gmail.com>
Date: Wed, 24 Sep 2025 22:13:44 +0200
Subject: [PATCH] [Serializer] Support preserving array keys with XmlEncoder

---
 serializer/encoders.rst | 42 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/serializer/encoders.rst b/serializer/encoders.rst
index c3fb2e26b50..3087dcaddd4 100644
--- a/serializer/encoders.rst
+++ b/serializer/encoders.rst
@@ -211,6 +211,8 @@ These are the options available on the :ref:`serializer context <serializer-cont
     require it. Example: ``'/(firstname|lastname)/'``
 ``ignore_empty_attributes`` (default: ``false``)
     If set to true, ignores all attributes with empty values in the generated XML
+``preserve_numeric_keys`` (default: ``false``)
+    If set to true, it keeps numeric array indexes instead of collapsing them into ``<item>`` nodes.
 
 .. versionadded:: 7.1
 
@@ -224,6 +226,8 @@ These are the options available on the :ref:`serializer context <serializer-cont
 
     The ``cdata_wrapping_name_pattern`` option was introduced in Symfony 7.4.
 
+    The ``preserve_numeric_keys`` option was introduced in Symfony 7.4.
+
 Example with a custom ``context``::
 
     use Symfony\Component\Serializer\Encoder\XmlEncoder;
@@ -254,6 +258,44 @@ Example with a custom ``context``::
     //   <date>2019-10-24</date>
     // </track>
 
+Example with ``preserve_numeric_keys``::
+
+    use Symfony\Component\Serializer\Encoder\XmlEncoder;
+
+    $data = [
+        'person' => [
+            ['firstname' => 'Benjamin', 'lastname' => 'Alexandre'],
+            ['firstname' => 'Damien', 'lastname' => 'Clay'],
+        ],
+    ];
+
+    $xmlEncoder->encode($data, 'xml', ['preserve_numeric_keys' => false]);
+    // outputs:
+    //<response>
+    //  <person>
+    //    <firstname>Benjamin</firstname>
+    //    <lastname>Alexandre</lastname>
+    //  </person>
+    //  <person>
+    //    <firstname>Damien</firstname>
+    //    <lastname>Clay</lastname>
+    //  </person>
+    //</response>
+    $xmlEncoder->encode($data, 'xml', ['preserve_numeric_keys' => true]);
+    // outputs:
+    //<response>
+    //  <person>
+    //    <item key="0">
+    //        <firstname>Benjamin</firstname>
+    //        <lastname>Alexandre</lastname>
+    //    </item>
+    //      <item key="1">
+    //        <firstname>Damien</firstname>
+    //        <lastname>Clay</lastname>
+    //      </item>
+    //  </person>
+    //</response>
+
 The ``YamlEncoder``
 -------------------