Merge pull request #2 from KurtThiemann/custom-property-serializer

Add custom serializers and deserializers for individual properties

Author: JulianVennen

README.md

@@ -176,6 +176,18 @@ protected array $otherExamples;
 // ^ items in the array will not be converted
 ```
 
+#### Serializer and Deserializer
+A custom Serializer and Deserializer can be specified for a property.
+This can be useful if you want to serialize a specific property in a different way.
+
+```php
+#[Serialize(serializer: new Base64Serializer(), deserializer: new Base64Deserializer(TestClass::class))]
+protected TestClass $example;
+```
+
+Note that the custom Deserializer is responsible for returning the correct type.
+If an incompatible type is returned, an IncorrectTypeException is thrown.
+
 ### Exceptions
 The following exceptions may be thrown during serialization or deserialization:
 - [MissingPropertyException](#missingpropertyexception)

src/ArrayDeserializer.php

@@ -13,6 +13,7 @@
 use ReflectionNamedType;
 use ReflectionProperty;
 use ReflectionUnionType;
+use TypeError;
 
 /**
  * Deserializes arrays into objects using the Serialize attribute.
@@ -26,7 +27,7 @@
  * @see Serialize
  * @template T
  */
-class ArrayDeserializer
+class ArrayDeserializer implements DeserializerInterface
 {
 
     /**
@@ -49,10 +50,13 @@ public function __construct(
      * @throws UnsupportedTypeException if the type of the property is unsupported
      */
     public function deserialize(
-        array $data,
+        mixed $data,
         string $path = "",
     ): object
     {
+        if (!is_array($data)) {
+            throw new InvalidArgumentException("Data must be an array.");
+        }
         try {
             $reflectionClass = new ReflectionClass($this->class);
             $result = new $this->class;
@@ -112,6 +116,15 @@ protected function deserializeProperty(
         }
 
         $value = $data[$name];
+        if ($customDeserializer = $attribute->getDeserializer()) {
+            $value = $customDeserializer->deserialize($value, $path);
+            try {
+                $property->setValue($result, $value);
+            } catch (TypeError) {
+                throw new IncorrectTypeException($path . "." . $name, $type, $value);
+            }
+            return;
+        }
 
         $nullable = $attribute->allowsNull() ?? $type?->allowsNull() ?? true;
         if ($value === null) {

src/ArraySerializer.php

@@ -25,7 +25,7 @@
  * @see Serialize
  * @see JsonSerializer
  */
-class ArraySerializer
+class ArraySerializer implements SerializerInterface
 {
     /**
      * Create a serializer from an object
@@ -67,7 +67,9 @@ public function serialize(object $item): array
             $name = $attribute->getName() ?? $property->getName();
             $value = $property->getValue($item);
 
-            if ($value instanceof JsonSerializable) {
+            if ($customSerializer = $attribute->getSerializer()) {
+                $value = $customSerializer->serialize($value);
+            } else if ($value instanceof JsonSerializable) {
                 $value = $value->jsonSerialize();
             } elseif (is_object($value)) {
                 $value = $this->serialize($value);
@@ -78,4 +80,4 @@ public function serialize(object $item): array
 
         return $serializedProperties;
     }
-}
+}

src/DeserializerInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Aternos\Serializer;
+
+use Aternos\Serializer\Exceptions\IncorrectTypeException;
+use Aternos\Serializer\Exceptions\MissingPropertyException;
+use Aternos\Serializer\Exceptions\UnsupportedTypeException;
+
+/**
+ * @template T
+ */
+interface DeserializerInterface
+{
+    /**
+     * Create a deserializer for a class
+     *
+     * @param class-string<T> $class the class to deserialize into
+     */
+    public function __construct(string $class);
+
+    /**
+     * Deserialize the data into an object
+     *
+     * @return T
+     * @throws IncorrectTypeException if the type of the property is incorrect
+     * @throws MissingPropertyException if a required property is missing
+     * @throws UnsupportedTypeException if the type of the property is unsupported
+     */
+    public function deserialize(mixed $data, string $path = ""): object;
+}

src/Json/JsonDeserializer.php

@@ -3,9 +3,11 @@
 namespace Aternos\Serializer\Json;
 
 use Aternos\Serializer\ArrayDeserializer;
+use Aternos\Serializer\DeserializerInterface;
 use Aternos\Serializer\Exceptions\IncorrectTypeException;
 use Aternos\Serializer\Exceptions\MissingPropertyException;
 use Aternos\Serializer\Exceptions\UnsupportedTypeException;
+use InvalidArgumentException;
 use JsonException;
 
 /**
@@ -20,7 +22,7 @@
  * @see Serialize
  * @template T
  */
-class JsonDeserializer
+class JsonDeserializer implements DeserializerInterface
 {
     protected ArrayDeserializer $arrayDeserializer;
 
@@ -45,7 +47,7 @@ public function __construct(
      * @throws UnsupportedTypeException if the type of the property is unsupported
      * @throws JsonException if the data is invalid json
      */
-    public function deserialize(array|string $data, string $path = ""): object
+    public function deserialize(mixed $data, string $path = ""): object
     {
         if (is_string($data)) {
             $data = json_decode($data, true, flags: JSON_THROW_ON_ERROR);
@@ -54,6 +56,10 @@ public function deserialize(array|string $data, string $path = ""): object
             }
         }
 
+        if (!is_array($data)) {
+            throw new InvalidArgumentException("Data must be a string or an array.");
+        }
+
         return $this->arrayDeserializer->deserialize($data, $path);
     }
-}
+}

src/Json/JsonSerializer.php

@@ -5,6 +5,7 @@
 use Aternos\Serializer\ArraySerializer;
 use Aternos\Serializer\Exceptions\IncorrectTypeException;
 use Aternos\Serializer\Exceptions\MissingPropertyException;
+use Aternos\Serializer\SerializerInterface;
 
 /**
  * A class that serializes objects using the Serialize attribute.
@@ -18,7 +19,7 @@
  * @see ArraySerializer
  * @see PropertyJsonSerializer
  */
-class JsonSerializer
+class JsonSerializer implements SerializerInterface
 {
     protected ArraySerializer $arraySerializer;
 
@@ -38,4 +39,4 @@ public function serialize(object $item): string
     {
         return json_encode($this->arraySerializer->serialize($item));
     }
-}
+}

src/Serialize.php

@@ -26,12 +26,16 @@ public static function getAttribute(ReflectionProperty $property): ?self
      * @param bool|null $required Whether the field is required
      * @param bool|null $allowNull Whether the field can be null
      * @param class-string|null $itemType The type of the items in the array
+     * @param SerializerInterface|null $serializer A custom serializer for this field
+     * @param DeserializerInterface|null $deserializer A custom deserializer for this field
      */
     public function __construct(
         protected ?string $name = null,
         protected ?bool   $required = null,
         protected ?bool   $allowNull = null,
         protected ?string $itemType = null,
+        protected ?SerializerInterface $serializer = null,
+        protected ?DeserializerInterface $deserializer = null,
     )
     {
     }
@@ -58,4 +62,20 @@ public function getItemType(): ?string
     {
         return $this->itemType;
     }
-}
+
+    /**
+     * @return SerializerInterface|null
+     */
+    public function getSerializer(): ?SerializerInterface
+    {
+        return $this->serializer;
+    }
+
+    /**
+     * @return DeserializerInterface|null
+     */
+    public function getDeserializer(): ?DeserializerInterface
+    {
+        return $this->deserializer;
+    }
+}

src/SerializerInterface.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Aternos\Serializer;
+
+interface SerializerInterface
+{
+    /**
+     * Serialize an object into a scalar value or an array.
+     *
+     * @param object $item
+     * @return int|float|string|array|null
+     */
+    public function serialize(object $item): int|float|string|array|null;
+}

tests/src/Base64Deserializer.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Aternos\Serializer\Test\Src;
+
+use Aternos\Serializer\DeserializerInterface;
+
+class Base64Deserializer implements DeserializerInterface
+{
+
+    /**
+     * @inheritDoc
+     */
+    public function __construct(protected string $class)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function deserialize(mixed $data, string $path = ""): object
+    {
+        return unserialize(base64_decode($data));
+    }
+}

tests/src/Base64Serializer.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Aternos\Serializer\Test\Src;
+
+use Aternos\Serializer\SerializerInterface;
+
+class Base64Serializer implements SerializerInterface
+{
+    /**
+     * @inheritDoc
+     */
+    public function serialize(object $item): int|float|string|array|null
+    {
+        return base64_encode(serialize($item));
+    }
+}