feature symfony#60228 [Serializer] Support preserving array keys with XmlEncoder (Maximilian Ruta)

This PR was merged into the 7.4 branch.

Discussion
----------

[Serializer] Support preserving array keys with `XmlEncoder`

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        |
| License       | MIT

### Feature: Add Support for preserving array keys as Child `<item>` Elements in XML Encoder

This PR introduces a new option to the Symfony Serializer's `XmlEncoder` that allows indexed arrays to be encoded as `<item>` elements under a single parent element, rather than repeating the parent element for each array item.

#### Motivation

Currently, encoding an array like:

```php
['person' => [
    ['firstname' => 'Benjamin', 'lastname' => 'Alexandre'],
    ['firstname' => 'Damien', 'lastname' => 'Clay'],
]]
```

produces the following XML:

```xml
<response>
    <person>
        <firstname>Benjamin</firstname>
        <lastname>Alexandre</lastname>
    </person>
    <person>
        <firstname>Damien</firstname>
        <lastname>Clay</lastname>
    </person>
</response>
```

This structure is not ideal when a clear container-child relationship is required, such as when interoperating with systems that expect such XML structures.

#### New Behavior

With the new `XmlEncoder::PRESERVE_NUMERIC_KEYS` option enabled, the same data now encodes to:

```xml
<response>
    <person>
        <item key="0">
            <firstname>Benjamin</firstname>
            <lastname>Alexandre</lastname>
        </item>
        <item key="1">
            <firstname>Damien</firstname>
            <lastname>Clay</lastname>
        </item>
    </person>
</response>
```

#### Usage

```php
$xml = $encoder->encode($data, 'xml', [
    XmlEncoder::PRESERVE_NUMERIC_KEYS => true,
]);
```

Commits
-------

d89d08f [Serializer] Add `XmlEncoder::PRESERVE_NUMERIC_KEYS` context option

Author: fabpot

src/Symfony/Component/Serializer/CHANGELOG.md

@@ -9,6 +9,7 @@ CHANGELOG
  * Add `CDATA_WRAPPING_NAME_PATTERN` support to `XmlEncoder`
  * Add support for `can*()` methods to `AttributeLoader`
  * Make `AttributeMetadata` and `ClassMetadata` final
+ * Add `XmlEncoder::PRESERVE_NUMERIC_KEYS` context option
  * Deprecate class aliases in the `Annotation` namespace, use attributes instead
  * Deprecate getters in attribute classes in favor of public properties
  * Deprecate `ClassMetadataFactoryCompiler`

src/Symfony/Component/Serializer/Context/Encoder/XmlEncoderContextBuilder.php

@@ -168,4 +168,12 @@ public function withIgnoreEmptyAttributes(?bool $ignoreEmptyAttributes): static
     {
         return $this->with(XmlEncoder::IGNORE_EMPTY_ATTRIBUTES, $ignoreEmptyAttributes);
     }
+
+    /**
+     * Configures whether to preserve numeric keys in array.
+     */
+    public function withPreserveNumericKeys(?bool $preserveNumericKeys): static
+    {
+        return $this->with(XmlEncoder::PRESERVE_NUMERIC_KEYS, $preserveNumericKeys);
+    }
 }

src/Symfony/Component/Serializer/Encoder/XmlEncoder.php

@@ -62,6 +62,7 @@ class XmlEncoder implements EncoderInterface, DecoderInterface, NormalizationAwa
     public const CDATA_WRAPPING_NAME_PATTERN = 'cdata_wrapping_name_pattern';
     public const CDATA_WRAPPING_PATTERN = 'cdata_wrapping_pattern';
     public const IGNORE_EMPTY_ATTRIBUTES = 'ignore_empty_attributes';
+    public const PRESERVE_NUMERIC_KEYS = 'preserve_numeric_keys';
 
     private array $defaultContext = [
         self::AS_COLLECTION => false,
@@ -76,6 +77,7 @@ class XmlEncoder implements EncoderInterface, DecoderInterface, NormalizationAwa
         self::CDATA_WRAPPING_NAME_PATTERN => false,
         self::CDATA_WRAPPING_PATTERN => '/[<>&]/',
         self::IGNORE_EMPTY_ATTRIBUTES => false,
+        self::PRESERVE_NUMERIC_KEYS => false,
     ];
 
     public function __construct(array $defaultContext = [])
@@ -347,6 +349,7 @@ private function buildXml(\DOMNode $parentNode, mixed $data, string $format, arr
     {
         $append = true;
         $removeEmptyTags = $context[self::REMOVE_EMPTY_TAGS] ?? $this->defaultContext[self::REMOVE_EMPTY_TAGS] ?? false;
+        $preserveNumericKeys = $context[self::PRESERVE_NUMERIC_KEYS] ?? $this->defaultContext[self::PRESERVE_NUMERIC_KEYS] ?? false;
         $encoderIgnoredNodeTypes = $context[self::ENCODER_IGNORED_NODE_TYPES] ?? $this->defaultContext[self::ENCODER_IGNORED_NODE_TYPES];
 
         if (\is_array($data) || ($data instanceof \Traversable && (null === $this->serializer || !$this->serializer->supportsNormalization($data, $format)))) {
@@ -373,9 +376,9 @@ private function buildXml(\DOMNode $parentNode, mixed $data, string $format, arr
                     if (!\in_array(\XML_COMMENT_NODE, $encoderIgnoredNodeTypes, true)) {
                         $append = $this->appendComment($parentNode, $data);
                     }
-                } elseif (\is_array($data) && false === is_numeric($key)) {
+                } elseif (\is_array($data) && !is_numeric($key)) {
                     // Is this array fully numeric keys?
-                    if (ctype_digit(implode('', array_keys($data)))) {
+                    if (!$preserveNumericKeys && null === array_find_key($data, static fn ($v, $k) => is_string($k))) {
                         /*
                          * Create nodes to append to $parentNode based on the $key of this array
                          * Produces <xml><item>0</item><item>1</item></xml>

src/Symfony/Component/Serializer/Mapping/Loader/schema/serialization.schema.json

@@ -326,6 +326,10 @@
           "type": "boolean",
           "description": "Whether to ignore empty attributes (XmlEncoder)"
         },
+        "preserve_numeric_keys": {
+          "type": "boolean",
+          "description": "Whether to preserve numeric keys in array (XmlEncoder)"
+        },
         "inline_threshold": {
           "type": "integer",
           "description": "Threshold to switch to inline YAML (YamlEncoder)"

src/Symfony/Component/Serializer/Tests/Encoder/XmlEncoderTest.php

@@ -1033,4 +1033,48 @@ public function testEncodeIgnoringEmptyAttribute()
 
         $this->assertEquals($expected, $this->encoder->encode($data, 'xml', ['ignore_empty_attributes' => true]));
     }
+
+    public function testEncodeArrayAsItem()
+    {
+        $expected = <<<'XML'
+            <?xml version="1.0"?>
+            <response><person><item key="0"><firstname>Benjamin</firstname><lastname>Alexandre</lastname></item><item key="1"><firstname>Damien</firstname><lastname>Clay</lastname></item></person></response>
+
+            XML;
+        $source = ['person' => [
+            ['@key' => 0, 'firstname' => 'Benjamin', 'lastname' => 'Alexandre'],
+            ['@key' => 1, 'firstname' => 'Damien', 'lastname' => 'Clay'],
+        ]];
+
+        $this->assertSame($expected, $this->encoder->encode($source, 'xml', [
+            XmlEncoder::PRESERVE_NUMERIC_KEYS => true,
+        ]));
+    }
+
+    public function testDecodeArrayAsItem()
+    {
+        $source = <<<'XML'
+            <?xml version="1.0"?>
+            <response>
+                <person>
+                    <item key="0">
+                        <firstname>Benjamin</firstname>
+                        <lastname>Alexandre</lastname>
+                    </item>
+                    <item key="1">
+                        <firstname>Damien</firstname>
+                        <lastname>Clay</lastname>
+                    </item>
+                </person>
+            </response>
+            XML;
+        $expected = ['person' => [
+            ['@key' => 0, 'firstname' => 'Benjamin', 'lastname' => 'Alexandre', ],
+            ['@key' => 1, 'firstname' => 'Damien', 'lastname' => 'Clay', ],
+        ]];
+
+        $this->assertSame($expected, $this->encoder->decode($source, 'xml', [
+            XmlEncoder::PRESERVE_NUMERIC_KEYS => true,
+        ]));
+    }
 }