Add support for dynamic handlers

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 # 3.x
 
+# 3.2.0 (unreleased)
+
+* Add support for handlers to modify the way a (third-party) class is (de-)serialized at compile time
+
 # 3.1.0
 
 * Add enum support

README.md

@@ -114,6 +114,100 @@ setting the `allow_generic_arrays` value to `true` via the `options` argument.
 Note: This will only work if the contents of that array are only primitive
 types (string, int, float, boolean and nested arrays with only these types).
 
+### Handlers
+
+Handlers let you modify how specific classes are (de-)serialized. This is useful for value objects such as UUIDs or 
+any third-party class where you cannot directly add JMS attributes. 
+
+Once registered, a handler is automatically applied to every property of the supported type, regardless of where in the
+(de-)serialized model it appears.
+
+#### When to use a handler vs. a virtual property
+
+**Use a virtual property** (`#[Serializer\VirtualProperty]`) when you want to use a different value than the class you 
+have at hand, and you have control over that class. Virtual properties are defined on the model itself and only affect 
+that model.
+
+**Use a handler** when a custom type needs to be (de-)serialized the same way wherever it appears. In most cases a 
+virtual property should be preferred. Handlers should mainly be used if you use third-party classes that have 
+to be (de-)serialized in a specific way.
+
+#### Implementing a handler
+
+Implement `SerializerHandlerInterface` for serialization and/or `DeserializerHandlerInterface` for deserialization. 
+Both return **PHP code expressions** (strings) that are embedded directly into the generated code — not values.
+
+A common example where such a handler makes sense is, when you want to (de-)serialize UUID objects. The serialized value
+is actually a string (e.g. `dfbd707c-3945-4a90-a6e7-e4e58846ebe7`) while the deserialized value is again the UUID object
+from your preferred library.
+
+In the following example we use the UUID implementation from the [symfony/uid package](https://packagist.org/packages/symfony/uid).
+
+```php
+use Liip\Serializer\DeserializerHandlerInterface;
+use Liip\Serializer\SerializerHandlerInterface;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Component\Uid\UuidV1;
+use Symfony\Component\Uid\UuidV3;
+use Symfony\Component\Uid\UuidV4;
+use Symfony\Component\Uid\UuidV5;
+use Symfony\Component\Uid\UuidV6;
+use Symfony\Component\Uid\UuidV7;
+use Symfony\Component\Uid\UuidV8;
+
+/**
+ * We write a single handler for both serialization and deserialization.
+ */
+class UuidHandler implements SerializerHandlerInterface, DeserializerHandlerInterface
+{
+    private const SUPPORTED_CLASSES = [
+        Uuid::class,
+        UuidV1::class,
+        UuidV3::class,
+        UuidV4::class,
+        UuidV5::class,
+        UuidV6::class,
+        UuidV7::class,
+        UuidV8::class,
+    ];
+
+    public function generateSerializeExpression(string $className, string $modelPath): string
+    {
+        // $modelPath is a PHP expression for the property value, e.g. "$model->id"
+        return $modelPath.'->toString()';
+    }
+
+    public function generateDeserializeExpression(string $className, string $arrayPath): string
+    {
+        // $arrayPath is a PHP expression for the raw array value, e.g. "$array['id']"
+        return '\\'.$className.'::fromString('.$arrayPath.')';
+    }
+
+    public function getSerializationClasses(string $className): array
+    {
+        return self::SUPPORTED_CLASSES;
+    }
+
+    public function getDeserializationClasses(string $className): array
+    {
+        return self::SUPPORTED_CLASSES;
+    }
+}
+```
+
+#### Registering handlers
+
+You can register one or multiple handlers via the `handlers` key inside `options` when creating a `GeneratorConfiguration`:
+
+```php
+$configuration = GeneratorConfiguration::createFromArray([
+    'options' => [
+        'handlers' => [new UuidHandler()],
+    ],
+    // ...
+]);
+```
+
 ## Serialize using the generated code
 In this example, we serialize an object of class `Product` for version 2:
 

src/Configuration/GeneratorConfiguration.php

@@ -4,6 +4,8 @@
 
 namespace Liip\Serializer\Configuration;
 
+use Liip\Serializer\DeserializerHandlerInterface;
+use Liip\Serializer\SerializerHandlerInterface;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
 /**
@@ -151,6 +153,34 @@ public function shouldAllowGenericArrays(): bool
         return $this->options['allow_generic_arrays'];
     }
 
+    /**
+     * @param class-string $className
+     */
+    public function findSerializerHandlerForClass(string $className): ?SerializerHandlerInterface
+    {
+        foreach ($this->options['handlers'] as $handler) {
+            if ($handler instanceof SerializerHandlerInterface && $this->supportsClass($handler->getSerializationClasses(), $className)) {
+                return $handler;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * @param class-string $className
+     */
+    public function findDeserializerHandlerForClass(string $className): ?DeserializerHandlerInterface
+    {
+        foreach ($this->options['handlers'] as $handler) {
+            if ($handler instanceof DeserializerHandlerInterface && $this->supportsClass($handler->getDeserializationClasses(), $className)) {
+                return $handler;
+            }
+        }
+
+        return null;
+    }
+
     public function getIterator(): \Traversable
     {
         return new \ArrayIterator($this->classesToGenerate);
@@ -166,10 +196,27 @@ private function resolveOptions(array $options): array
         $resolver = new OptionsResolver();
         $resolver->setDefaults([
             'allow_generic_arrays' => false,
+            'handlers' => [],
         ]);
 
         $resolver->setAllowedTypes('allow_generic_arrays', 'boolean');
+        $resolver->setAllowedTypes('handlers', 'array');
 
         return $resolver->resolve($options);
     }
+
+    /**
+     * @param class-string[] $supportedClasses
+     * @param class-string   $actualClass
+     */
+    private function supportsClass(array $supportedClasses, string $actualClass): bool
+    {
+        foreach ($supportedClasses as $supportedClass) {
+            if (is_a($actualClass, $supportedClass, true)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

src/DeserializerGenerator.php

@@ -92,12 +92,19 @@ private function generateCodeForClass(
         ModelPath $modelPath,
         array $stack = [],
     ): string {
+        /** @var class-string $className */
+        $className = $classMetadata->getClassName();
+        $handler = $this->configuration->findDeserializerHandlerForClass($className);
+        if (null !== $handler) {
+            return $this->templating->renderAssignJsonDataToField((string) $modelPath, $handler->generateDeserializeExpression($className, (string) $arrayPath));
+        }
+
         $discriminatorMetadata = $classMetadata->getDiscriminatorMetadata();
-        if (null !== $discriminatorMetadata && $discriminatorMetadata->baseClass == $classMetadata->getClassName()) {
+        if (null !== $discriminatorMetadata && $discriminatorMetadata->baseClass == $className) {
             return $this->generateCodeForDiscriminatorClass($classMetadata, $arrayPath, $modelPath, $stack);
         }
 
-        $stack[$classMetadata->getClassName()] = ($stack[$classMetadata->getClassName()] ?? 0) + 1;
+        $stack[$className] = ($stack[$className] ?? 0) + 1;
 
         $constructorArgumentNames = [];
         $overwrittenNames = [];
@@ -136,7 +143,7 @@ private function generateCodeForClass(
                 continue;
             }
             if ($definition->isRequired()) {
-                $msg = \sprintf('Unknown constructor argument "%s". Class %s only has properties that tell how to handle %s.', $definition->getName(), $classMetadata->getClassName(), implode(', ', array_keys($constructorArgumentNames)));
+                $msg = \sprintf('Unknown constructor argument "%s". Class %s only has properties that tell how to handle %s.', $definition->getName(), $className, implode(', ', array_keys($constructorArgumentNames)));
                 if ($overwrittenNames) {
                     $msg .= \sprintf(' Multiple definitions for fields %s seen - the last one overwrites previous ones.', implode(', ', array_keys($overwrittenNames)));
                 }
@@ -148,7 +155,7 @@ private function generateCodeForClass(
             $code .= $this->templating->renderUnset(array_values($constructorArgumentNames));
         }
 
-        return $this->templating->renderClass((string) $modelPath, $classMetadata->getClassName(), $constructorArguments, $code, $initCode);
+        return $this->templating->renderClass((string) $modelPath, $className, $constructorArguments, $code, $initCode);
     }
 
     /**

src/DeserializerHandlerInterface.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Liip\Serializer;
+
+interface DeserializerHandlerInterface
+{
+    /**
+     * Generate the PHP code to deserialize the object from the value.
+     *
+     * This method is called while generating the code for the deserializer, not at runtime of deserialization. You need
+     * to generate PHP code that can be included into the deserialization function generated by the Liip serializer.
+     * Use the $arrayPath to access the data structure that the object was serialized to. Use $className to know which
+     * object to instantiate.
+     *
+     * @param class-string $className
+     * @param string       $arrayPath Contains a PHP expression for the property value, e.g. "$model->id"
+     */
+    public function generateDeserializeExpression(string $className, string $arrayPath): string;
+
+    /**
+     * @return class-string[]
+     */
+    public function getDeserializationClasses(): array;
+}

src/SerializerGenerator.php

@@ -122,12 +122,19 @@ private function generateCodeForClass(
         string $modelPath,
         array $stack = [],
     ): string {
+        /** @var class-string $className */
+        $className = $classMetadata->getClassName();
+        $handler = $this->configuration->findSerializerHandlerForClass($className);
+        if (null !== $handler) {
+            return $this->templating->renderAssign($arrayPath, $handler->generateSerializeExpression($className, $modelPath));
+        }
+
         $discriminatorMetadata = $classMetadata->getDiscriminatorMetadata();
-        if (null !== $discriminatorMetadata && $discriminatorMetadata->baseClass == $classMetadata->getClassName()) {
+        if (null !== $discriminatorMetadata && $discriminatorMetadata->baseClass == $className) {
             return $this->generateCodeForDiscriminatorClass($classMetadata, $apiVersion, $serializerGroups, $arrayPath, $modelPath, $stack);
         }
 
-        $stack[$classMetadata->getClassName()] = ($stack[$classMetadata->getClassName()] ?? 0) + 1;
+        $stack[$className] = ($stack[$className] ?? 0) + 1;
 
         $code = '';
         foreach ($classMetadata->getProperties() as $propertyMetadata) {

src/SerializerHandlerInterface.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Liip\Serializer;
+
+interface SerializerHandlerInterface
+{
+    /**
+     * Generate the PHP code to serialize the value from the object.
+     *
+     * This method is called while generating the code for the serializer, not at runtime of serialization. You need
+     * to generate PHP code that can be included into the serialization function generated by the Liip serializer.
+     * Use the $modelPath to access the object and return the value for the json array. Use $className to know which
+     * class is serialized.
+     *
+     * @param class-string $className
+     * @param string       $modelPath Contains a PHP expression for the raw array value, e.g. $array['id']
+     */
+    public function generateSerializeExpression(string $className, string $modelPath): string;
+
+    /**
+     * @return class-string[]
+     */
+    public function getSerializationClasses(): array;
+}

tests/Fixtures/CustomType.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Liip\Serializer\Fixtures;
+
+class CustomType
+{
+    public string $key = 'static value';
+
+    public function __construct(public readonly string $value)
+    {
+    }
+
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+
+    public static function fromString(string $value): self
+    {
+        return new self($value);
+    }
+}

tests/Fixtures/CustomTypeHandler.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Liip\Serializer\Fixtures;
+
+use Liip\Serializer\DeserializerHandlerInterface;
+use Liip\Serializer\SerializerHandlerInterface;
+
+class CustomTypeHandler implements SerializerHandlerInterface, DeserializerHandlerInterface
+{
+    public function generateSerializeExpression(string $className, string $modelPath): string
+    {
+        return $modelPath.'->getValue()';
+    }
+
+    public function generateDeserializeExpression(string $className, string $arrayPath): string
+    {
+        return '\\'.CustomType::class.'::fromString('.$arrayPath.')';
+    }
+
+    public function getDeserializationClasses(): array
+    {
+        return [CustomType::class];
+    }
+
+    public function getSerializationClasses(): array
+    {
+        return [CustomType::class];
+    }
+}

tests/Fixtures/ModelWithCustomType.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Liip\Serializer\Fixtures;
+
+use JMS\Serializer\Annotation as Serializer;
+
+class ModelWithCustomType
+{
+    public ?CustomType $value = null;
+
+    #[Serializer\Type('array<'.CustomType::class.'>')]
+    public ?array $values = null;
+}