Serialize associative arrays (maps) as objects instead of arrays

README.md

@@ -60,6 +60,7 @@ resolving steps using [code generation](#maximizing-performance).
     - [**Creating your own property casters**](#creating-your-own-property-casters)
     - [**Static constructors**](#static-constructors)
     - [**Key formatters**](#key-formatters)
+    - [**Serializing maps as objects**](#serializing-maps-as-objects)
 - [**Maximizing performance**](#maximizing-performance)
 
 ## Design goals
@@ -598,6 +599,59 @@ $payload = $mapper->serializeObject(new Shout('Hello, World!');
 $payload['what'] === 'HELLO, WORLD!';
 ```
 
+### Serializing maps as objects
+By default, associative arrays are serialized as arrays in the payload. Since associative arrays represent 
+unstructured key-value maps that are typically treated as objects in many data formats, you may want to serialize 
+them as objects for better cross-platform compatibility.
+
+You can configure the mapper to serialize associative arrays as objects by enabling the `serializeMapsAsObjects` option:
+
+```php
+use EventSauce\ObjectHydrator\DefinitionProvider;
+use EventSauce\ObjectHydrator\ObjectMapperUsingReflection;
+
+$mapper = new ObjectMapperUsingReflection(
+    new DefinitionProvider(serializeMapsAsObjects: true),
+);
+```
+
+Maps are serialized as objects based on their doc-comment type hints. Arrays with `array<string, T>` type hints 
+are treated as maps and serialized as objects.
+
+```php
+class ExampleCommand
+{
+    /**
+     * @param array<string, mixed> $changedFields
+     */
+    public function __construct(
+        public readonly array $changedFields,
+    ) {}
+
+    /**
+     * @return array<string, string>
+     */
+    public function metadata(): array
+    {
+        return [
+            'source' => 'api',
+        ];
+    }
+}
+
+$command = new ExampleCommand(['email' => '[email protected]', 'name' => 'John']);
+
+$payload = $mapper->serializeObject($command);
+```
+
+Serialized payload:
+```
+[
+    'changed_fields' => {"email": "[email protected]", "name": "John"},
+    'metadata' => {"source": "api"}
+]
+```
+
 ## Symmetrical conversion
 
 If configured consistently, hydration and serialization can be used to translate an object to raw data

composer.json

@@ -5,7 +5,8 @@
     "license": "MIT",
     "require": {
         "php": "^8.0",
-        "ext-fileinfo": "*"
+        "ext-fileinfo": "*",
+        "symfony/polyfill-php81": "^1.3"
     },
     "require-dev": {
         "phpunit/phpunit": "^9.5.11",

src/ConcreteType.php

@@ -14,6 +14,8 @@
  */
 final class ConcreteType
 {
+    public bool $associative = false;
+
     public function __construct(public string $name, public bool $isBuiltIn)
     {
     }

src/DefinitionProvider.php

@@ -146,6 +146,7 @@ private function stringifyConstructor(ReflectionMethod $constructor): string
     public function provideSerializationDefinition(string $className): ClassSerializationDefinition
     {
         $reflection = new ReflectionClass($className);
+        $constructor = $this->constructorResolver->resolveConstructor($reflection);
         $objectSettings = $this->resolveObjectSettings($reflection);
         $classAttributes = $reflection->getAttributes();
         $properties = [];
@@ -173,7 +174,7 @@ public function provideSerializationDefinition(string $className): ClassSerializ
                 PropertySerializationDefinition::TYPE_METHOD,
                 $methodName,
                 $this->resolveSerializers($returnType, $attributes),
-                PropertyType::fromReflectionType($returnType),
+                $this->propertyTypeResolver->typeFromMethod($method),
                 $returnType->allowsNull(),
                 $this->resolveKeys($key, $attributes),
                 $typeSpecifier?->key,
@@ -204,7 +205,7 @@ public function provideSerializationDefinition(string $className): ClassSerializ
                 PropertySerializationDefinition::TYPE_PROPERTY,
                 $property->getName(),
                 $serializers,
-                PropertyType::fromReflectionType($propertyType),
+                $this->propertyTypeResolver->typeFromProperty($property, $constructor),
                 $propertyType->allowsNull(),
                 $this->resolveKeys($key, $attributes),
                 $typeSpecifier?->key,

src/Fixtures/ClassThatHasMultipleCastersOnMapProperty.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace EventSauce\ObjectHydrator\Fixtures;
+
+use EventSauce\ObjectHydrator\PropertyCasters\CastToArrayWithKey;
+use EventSauce\ObjectHydrator\PropertyCasters\CastToType;
+
+final class ClassThatHasMultipleCastersOnMapProperty
+{
+    /**
+     * @param array<string, array<string, string>> $map
+     */
+    public function __construct(
+        #[CastToType('array')]
+        #[CastToArrayWithKey('second_level')]
+        #[CastToArrayWithKey('first_level')]
+        public array $map,
+    ) {
+    }
+}

src/Fixtures/ClassThatSpecifiesArrayWithIntegerKeys.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace EventSauce\ObjectHydrator\Fixtures;
+
+final class ClassThatSpecifiesArrayWithIntegerKeys
+{
+    /**
+     * @param array<int, string> $arrayWithIntegerKeys
+     */
+    public function __construct(
+        public array $arrayWithIntegerKeys,
+    ) {
+    }
+}

src/Fixtures/ClassThatSpecifiesArraysWithDocComments.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace EventSauce\ObjectHydrator\Fixtures;
+
+use EventSauce\ObjectHydrator\Fixtures\ClassWithCamelCaseProperty as CamelClass;
+
+final class ClassThatSpecifiesArraysWithDocComments
+{
+    /**
+     * @param array<string, CamelClass> $mapWithObjects
+     * @param array<string, int> $mapWithScalars
+     * @param array<string, array<string, string>> $mapWithAssociativeArrays
+     * @param array<int, string> $listWithTypeHint
+     */
+    public function __construct(
+        public array $mapWithObjects,
+        public array $mapWithScalars,
+        public array $mapWithAssociativeArrays,
+        public array $listWithoutTypeHint,
+        public array $listWithTypeHint,
+    ) {
+    }
+
+    /**
+     * @return array<string, CamelClass>
+     */
+    public function methodMapWithObjects(): array
+    {
+        return $this->mapWithObjects;
+    }
+
+    /**
+     * @return array<string, int>
+     */
+    public function methodMapWithScalars(): array
+    {
+        return $this->mapWithScalars;
+    }
+
+    /**
+     * @return array<string, array<string, string>>
+     */
+    public function methodMapWithAssociativeArrays(): array
+    {
+        return $this->mapWithAssociativeArrays;
+    }
+
+    public function methodListWithoutTypeHint(): array
+    {
+        return $this->listWithoutTypeHint;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    public function methodListWithTypeHint(): array
+    {
+        return $this->listWithTypeHint;
+    }
+}