Feature: Allow to normalize and denormalize custom serialized objects.

Author: zolex

docs/VOM.md

@@ -19,7 +19,7 @@ The Versatile Object Mapper - or in short VOM - is a PHP library to transform an
 <!-- toc -->
 
 - [The Object Mapper](#the-object-mapper)
-  * [Without Framework](#without-framework)
+  * [Without Framework](#plain-old-php)
   * [Laravel Framework](#laravel-framework)
   * [Symfony Framework](#symfony-framework)
   * [Denormalization](#denormalization)
@@ -322,6 +322,33 @@ class ConstructorArguments
 > [!NOTE]
 > When using the [`object_to_populate` context](#object-to-populate), the constructor arguments and constructor property promotion will be skipped.
 
+#### Serialized Objects
+
+In case the source data is a serialized representation of the model, the constructor (or factory) can have a single string argument with the `serialized` option set to `true`.
+
+See [Custom serialization](#custom-serialization) to implement the equivalent normalizer.
+
+```php
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class SerializedObject
+{
+    private int $id;
+    private string $name;
+
+    public function __construct(
+        #[VOM\Argument(serialized: true)]
+        string $data,
+    ) {
+        [$this->id, $this->name] = explode(':', $data);
+    }
+}
+```
+
+```php
+$objectMapper->denormalize('123:test', SerializedObject::class);
+```
 
 ### Constructor Property Promotion
 
@@ -642,6 +669,30 @@ class Calls
 }
 ```
 
+##### Custom serialization
+
+The normalizer attribute can be added on the `__toString()` method. Note that in this case it must be the only normalizer on the model and return a string representation of the object.
+
+See [Serialized Objects](#serialized-objects) to implement the equivalent denormalizer.
+
+```php
+use Symfony\Component\Serializer\Attribute\Groups;
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class SerializedObject
+{
+    public int $id;
+    public string $name;
+
+    #[VOM\Mormalizer]
+    public function __toString(): string
+    {
+        return $this->id . ':' . $this->name;
+    }
+}
+```
+
 > [!CAUTION]
 > It is possible to normalize data and denormalize a model while maintaining the exact same results, no matter how often you repeat this process.
 > If this is one of your requirements, and you are using Normalizer and Denormalizer methods, you have to be careful how you store the injected data

src/Laravel/Providers/VersatileObjectMapperProvider.php

@@ -40,8 +40,7 @@ class VersatileObjectMapperProvider extends ServiceProvider
 {
     public function register(): void
     {
-        $this->app->singleton(VersatileObjectMapper::class, function(Application $app): VersatileObjectMapper
-        {
+        $this->app->singleton(VersatileObjectMapper::class, function (Application $app): VersatileObjectMapper {
             return VersatileObjectMapperFactory::create();
         });
     }

src/Mapping/AbstractProperty.php

@@ -25,6 +25,7 @@ public function __construct(
         private ?string $defaultOrder = null,
         private ?string $dateTimeFormat = null,
         private ?array $map = null,
+        private bool $serialized = false,
     ) {
     }
 
@@ -87,4 +88,9 @@ public function getMap(): ?array
     {
         return $this->map;
     }
+
+    public function isSerialized(): bool
+    {
+        return $this->serialized;
+    }
 }

src/Metadata/Factory/ModelMetadataFactory.php

@@ -118,6 +118,8 @@ public function getMetadataFor(string|\ReflectionClass $class, ?ModelMetadata $m
             throw new MissingMetadataException(\sprintf('The class "%s" does not have the "VOM\Model" attribute.', $class->getName()));
         }
 
+        $hasSerializer = false;
+        $normalizerCount = 0;
         foreach ($class->getMethods() as $reflectionMethod) {
             if ($reflectionMethod->isConstructor()) {
                 continue;
@@ -127,7 +129,12 @@ public function getMetadataFor(string|\ReflectionClass $class, ?ModelMetadata $m
                 $attribute = $reflectionAttribute->newInstance();
 
                 if ($attribute instanceof Normalizer) {
-                    $modelMetadata->addNormalizer($this->createNormalizerMetadata($class, $reflectionMethod, $attribute));
+                    ++$normalizerCount;
+                    $normalizer = $this->createNormalizerMetadata($class, $reflectionMethod, $attribute);
+                    if ('__toString' === $normalizer->getMethod()) {
+                        $hasSerializer = true;
+                    }
+                    $modelMetadata->addNormalizer($normalizer);
                     continue;
                 }
 
@@ -143,6 +150,10 @@ public function getMetadataFor(string|\ReflectionClass $class, ?ModelMetadata $m
             }
         }
 
+        if ($hasSerializer && $normalizerCount > 1) {
+            throw new MappingException(\sprintf('The "__toString()" method on model "%s" is configured as a normalizer. There must be no additional normalizer methods.', $class->getName()));
+        }
+
         foreach ($class->getProperties() as $reflectionProperty) {
             if ($modelMetadata->isConstructorArgumentPromoted($reflectionProperty->getName())) {
                 continue;
@@ -180,10 +191,12 @@ private function createNormalizerMetadata(
             throw new MappingException(\sprintf('Normalizer method %s::%s() should not be static.', $reflectionClass->getName(), $reflectionMethod->getName()));
         }
 
-        if (preg_match('/^(get|has|is|normalize)(.+)$/i', $reflectionMethod->getName(), $matches)) {
+        if ('__toString' === $reflectionMethod->getName()) {
+            $virtualPropertyName = null;
+        } elseif (preg_match('/^(get|has|is|normalize)(.+)$/i', $reflectionMethod->getName(), $matches)) {
             $virtualPropertyName = lcfirst($matches[2]);
         } else {
-            throw new MappingException(\sprintf('Normalizer on "%s::%s()" cannot be added. Normalizer can only be added on methods beginning with "get", "has", "is" or "normalize".', $reflectionClass->getName(), $reflectionMethod->getName()));
+            throw new MappingException(\sprintf('Normalizer on "%s::%s()" cannot be added. Normalizer can only be added on methods beginning with "get", "has", "is" or "normalize" or on the "__toString" method.', $reflectionClass->getName(), $reflectionMethod->getName()));
         }
 
         return new NormalizerMetadata($reflectionClass->getName(), $reflectionMethod->getName(), $virtualPropertyName, $normalizer);

src/Metadata/NormalizerMetadata.php

@@ -20,7 +20,7 @@ class NormalizerMetadata extends AbstractCallableMetadata
     public function __construct(
         string $class,
         string $method,
-        private readonly string $virtualPropertyName,
+        private readonly ?string $virtualPropertyName,
         private readonly Normalizer $attribute,
     ) {
         parent::__construct($class, $method);

src/Metadata/PropertyMetadata.php

@@ -139,6 +139,11 @@ public function hasMap(): bool
         return $this->attribute->hasMap();
     }
 
+    public function isSerialized(): bool
+    {
+        return $this->attribute->isSerialized();
+    }
+
     public function getMappedValue(mixed $value): mixed
     {
         $map = $this->attribute->getMap();

src/Serializer/Normalizer/ObjectNormalizer.php

@@ -101,6 +101,7 @@ public function getSupportedTypes(?string $format): array
     {
         return [
             'object' => true,
+            '*' => true,
         ];
     }
 
@@ -119,7 +120,7 @@ public function supportsDenormalization(mixed $data, string $type, ?string $form
             return false;
         }
 
-        return \is_array($data) || \is_object($data);
+        return \is_array($data) || \is_object($data) || \is_string($data);
     }
 
     /**
@@ -209,7 +210,7 @@ public function denormalize(mixed $data, string $type, ?string $format = null, a
      * @throws FactoryException              When at least one factory method is configured but failed to instantiate the model
      * @throws ExceptionInterface            For any other type of exception
      */
-    protected function createInstance(array &$data, string $class, array &$context, ?string $format): object
+    protected function createInstance(array|string &$data, string $class, array &$context, ?string $format): object
     {
         if (null !== $object = $this->extractObjectToPopulate($class, $context, self::OBJECT_TO_POPULATE)) {
             return $object;
@@ -286,6 +287,10 @@ private function denormalizeProperty(string $type, mixed $data, PropertyMetadata
             $data = &$context[self::ROOT_DATA];
         }
 
+        if (\is_string($data) && $property->isSerialized()) {
+            return $data;
+        }
+
         if ($accessor = $property->getAccessor()) {
             $value = $this->propertyAccessor->getValue($data, $accessor);
         } else {
@@ -478,13 +483,17 @@ public function supportsNormalization(mixed $data, ?string $format = null, array
             return false;
         }
 
+        if (!\is_object($data)) {
+            return false;
+        }
+
         try {
             $this->modelMetadataFactory->getMetadataFor($data::class);
         } catch (MissingMetadataException) {
             return false;
         }
 
-        return \is_object($data);
+        return true;
     }
 
     /**
@@ -599,7 +608,9 @@ public function normalize(mixed $object, ?string $format = null, array $context
                 throw new BadMethodCallException(\sprintf('Bad normalizer method call: %s', $e->getMessage()), 0, $e);
             }
 
-            if (null !== $accessor = $normalizer->getAccessor()) {
+            if ('__toString' === $normalizer->getMethod()) {
+                return $normalized;
+            } elseif (null !== $accessor = $normalizer->getAccessor()) {
                 $this->propertyAccessor->setValue($data, $accessor, $normalized);
             } else {
                 if (!\is_array($normalized)) {

tests/Fixtures/SerializedObject.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the VOM package.
+ *
+ * (c) Andreas Linden <zlx@gmx.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zolex\VOM\Test\Fixtures;
+
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class SerializedObject
+{
+    public string $filename;
+    public string $tag;
+    public string $description;
+
+    public function __construct(
+        #[VOM\Argument(serialized: true)]
+        string $data,
+    ) {
+        $parts = explode(',', $data);
+        $this->filename = array_shift($parts);
+        foreach ($parts as $part) {
+            [$key, $value] = explode(':', $part);
+            if (property_exists($this, $key)) {
+                $this->{$key} = $value;
+            }
+        }
+    }
+
+    #[VOM\Normalizer]
+    public function __toString(): string
+    {
+        return $this->filename.',tag:'.$this->tag.',description:'.$this->description;
+    }
+}

tests/Fixtures/SerializedObjectArray.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the VOM package.
+ *
+ * (c) Andreas Linden <zlx@gmx.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zolex\VOM\Test\Fixtures;
+
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class SerializedObjectArray
+{
+    /**
+     * @var SerializedObject[]
+     */
+    #[VOM\Property]
+    public array $images;
+}

tests/Fixtures/SerializedObjectWithAdditionalNormalizer.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the VOM package.
+ *
+ * (c) Andreas Linden <zlx@gmx.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zolex\VOM\Test\Fixtures;
+
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class SerializedObjectWithAdditionalNormalizer
+{
+    #[VOM\Normalizer]
+    public function __toString(): string
+    {
+        return 'serialized object';
+    }
+
+    #[VOM\Normalizer(accessor: 'something')]
+    public function getSomething(): string
+    {
+        return 'something';
+    }
+}