Merge pull request #4 from KurtThiemann/backed-enums

Support serializing and deserializing backed enums

Author: JulianVennen

README.md

@@ -9,12 +9,15 @@ A PHP library for (de-)serialization using attributes and reflection.
   - [Required](#required)
   - [Allow Null](#allow-null)
   - [Item Type](#item-type)
+  - [Serializer and Deserializer](#serializer-and-deserializer)
+  - [Item Serializer and Item Deserializer](#item-serializer-and-item-deserializer)
 - [Exceptions](#exceptions)
   - [SerializationException](#serializationexception)
   - [InvalidInputException](#invalidinputexception)
   - [MissingPropertyException](#missingpropertyexception)
   - [IncorrectTypeException](#incorrecttypeexception)
   - [UnsupportedTypeException](#unsupportedtypeexception)
+  - [InvalidEnumBackingException](#invalidenumbackingexception)
 - [Custom Serializers](#custom-serializers)
 
 ### Installation
@@ -70,6 +73,9 @@ $example = ExampleClass::tryFromJson('{ "name": "John", "age": 25, "last_name":
 > [!NOTE]
 > Deserialization is not supported for intersection types as there is no way to determine the correct type.
 
+> [!NOTE]
+> Serialization and deserialization of enums is only supported for backed enums.
+
 If you prefer you can also serialize and deserialize manually.
 
 ```php
@@ -206,6 +212,7 @@ Both of these exceptions extend [InvalidInputException](#invalidinputexception).
 
 During deserialization, the following additional exceptions may be thrown:
 - [UnsupportedTypeException](#unsupportedtypeexception)
+- [InvalidEnumBackingException](#invalidenumbackingexception)
 - [JsonException](https://www.php.net/manual/en/class.jsonexception.php)
 
 JsonException is a built-in PHP exception that is thrown when an error occurs during JSON encoding or decoding.
@@ -234,6 +241,11 @@ As noted above, deserializing intersection types is not supported.
 If an intersection type is encountered during deserialization, this exception is thrown.
 It's also thrown if a php built-in type is encountered that is not yet supported by the library.
 
+#### InvalidEnumBackingException
+This exception is thrown if an enum is deserialized with an invalid backing value.
+This can happen if the value that is deserialized is not scalar,
+or if the target enum does not have a matching case.
+
 ### Custom Serializers
 If you want to write a serializer for a different format, you can use the ArraySerializer and ArrayDeserializer class.
 These convert the object to an associative array and vice versa.

src/ArrayDeserializer.php

@@ -2,18 +2,21 @@
 
 namespace Aternos\Serializer;
 
+use Aternos\Serializer\Exceptions\InvalidEnumBackingException;
 use Aternos\Serializer\Exceptions\SerializationException;
 use Aternos\Serializer\Exceptions\IncorrectTypeException;
 use Aternos\Serializer\Exceptions\MissingPropertyException;
 use Aternos\Serializer\Exceptions\UnsupportedTypeException;
 use InvalidArgumentException;
 use ReflectionClass;
+use ReflectionEnum;
 use ReflectionException;
 use ReflectionIntersectionType;
 use ReflectionNamedType;
 use ReflectionProperty;
 use ReflectionUnionType;
 use TypeError;
+use ValueError;
 
 /**
  * Deserializes arrays into objects using the Serialize attribute.
@@ -48,22 +51,29 @@ public function __construct(
      * @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
+     * @throws InvalidEnumBackingException if the target class is an enum, but the serialized data is not a valid backing value
      */
     public function deserialize(
         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;
         } catch (ReflectionException) {
             throw new InvalidArgumentException("Class '" . $this->class . "' does not exist.");
         }
 
+        if ($reflectionClass->isEnum()) {
+            return $this->parseEnum($data, $path);
+        }
+
+        if (!is_array($data)) {
+            throw new IncorrectTypeException($path, $this->class, $data);
+        }
+
+        $result = new $this->class;
+
         foreach ($reflectionClass->getProperties() as $property) {
             $this->deserializeProperty($data, $path, $property, $result);
         }
@@ -81,6 +91,7 @@ public function deserialize(
      * @throws IncorrectTypeException if the type of the property is incorrect
      * @throws MissingPropertyException if the property is required but missing
      * @throws UnsupportedTypeException if the type of the property is unsupported
+     * @throws InvalidEnumBackingException if the target class is an enum, but the serialized data is not a valid backing value
      */
     protected function deserializeProperty(
         array $data,
@@ -208,6 +219,7 @@ protected function parseUnionType(ReflectionUnionType $unionType, mixed $value,
      * @throws IncorrectTypeException if the type of the property is incorrect
      * @throws UnsupportedTypeException if the type of the property is unsupported
      * @throws MissingPropertyException if a required property is missing
+     * @throws InvalidEnumBackingException if the target class is an enum, but the serialized data is not a valid backing value
      */
     protected function  parseNamedType(
         ReflectionNamedType $type,
@@ -226,10 +238,6 @@ protected function  parseNamedType(
             return $value;
         }
 
-        if (!is_array($value)) {
-            throw new IncorrectTypeException($propertyPath, $type->getName(), $value);
-        }
-
         if ($type->getName() === "self") {
             $deserializer = $this;
         } else {
@@ -261,4 +269,33 @@ protected function isBuiltInTypeValid(string $type, mixed $value, string $path):
             default => throw new UnsupportedTypeException($path, $type),
         };
     }
+
+    /**
+     * @param mixed $value
+     * @param string $path
+     * @return mixed
+     * @throws InvalidEnumBackingException
+     * @throws UnsupportedTypeException
+     * @noinspection PhpDocMissingThrowsInspection
+     */
+    protected function parseEnum(mixed $value, string $path): mixed
+    {
+        /** @noinspection PhpUnhandledExceptionInspection - It has already been verified that the enum exists */
+        $reflectionEnum = new ReflectionEnum($this->class);
+
+        if (!$reflectionEnum->isBacked()) {
+            throw new UnsupportedTypeException($path, $this->class, "Enums must be backed by a scalar type.");
+        }
+
+        $backingType = $reflectionEnum->getBackingType();
+        if (!$backingType->isBuiltin() || !$this->isBuiltInTypeValid($backingType->getName(), $value, $path)) {
+            throw new InvalidEnumBackingException($this->class, $backingType->getName(), $value);
+        }
+
+        try {
+            return $this->class::from($value);
+        } catch (ValueError) {
+            throw new InvalidEnumBackingException($this->class, $backingType->getName(), $value);
+        }
+    }
 }

src/ArraySerializer.php

@@ -71,6 +71,11 @@ public function serialize(object $item): array
                 $value = $customSerializer->serialize($value);
             } else if ($value instanceof JsonSerializable) {
                 $value = $value->jsonSerialize();
+            } else if ($value instanceof \UnitEnum) {
+                if (!$value instanceof \BackedEnum) {
+                    throw new IncorrectTypeException($property->getName(), "BackedEnum", $value);
+                }
+                $value = $value->value;
             } else if (is_object($value)) {
                 $value = $this->serialize($value);
             } else if (is_array($value) && $customSerializer = $attribute->getItemSerializer()) {

src/Exceptions/InvalidEnumBackingException.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Aternos\Serializer\Exceptions;
+
+class InvalidEnumBackingException extends InvalidInputException
+{
+    /**
+     * @param class-string $enumType
+     * @param string $backingType
+     * @param mixed $actualValue
+     */
+    public function __construct(
+        protected string $enumType,
+        protected string $backingType,
+        protected mixed $actualValue
+    )
+    {
+        $options = [];
+        foreach ($enumType::cases() as $case) {
+            $options[] = $case->value;
+        }
+
+        parent::__construct("Invalid backing value for enum '" . $enumType . "' expected: type '" . $backingType .
+            "' (" . implode(", ", $options) . ") found: "
+            . var_export($actualValue, true));
+    }
+
+    /**
+     * @return string
+     */
+    public function getEnumType(): string
+    {
+        return $this->enumType;
+    }
+
+    /**
+     * @return string
+     */
+    public function getBackingType(): string
+    {
+        return $this->backingType;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getActualValue(): mixed
+    {
+        return $this->actualValue;
+    }
+}

tests/src/BackedEnumTestClass.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Aternos\Serializer\Test\Src;
+
+use Aternos\Serializer\Serialize;
+
+class BackedEnumTestClass
+{
+    #[Serialize]
+    protected TestBackedEnum $enum = TestBackedEnum::A;
+
+    public function getEnum(): TestBackedEnum
+    {
+        return $this->enum;
+    }
+}

tests/src/EnumTestClass.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Aternos\Serializer\Test\Src;
+
+use Aternos\Serializer\Serialize;
+
+class EnumTestClass
+{
+    #[Serialize]
+    protected TestEnum $enum = TestEnum::A;
+
+    public function getEnum(): TestEnum
+    {
+        return $this->enum;
+    }
+}

tests/src/TestBackedEnum.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Aternos\Serializer\Test\Src;
+
+enum TestBackedEnum : string
+{
+    case A = "a";
+    case B = "b";
+    case C = "c";
+}

tests/src/TestEnum.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Aternos\Serializer\Test\Src;
+
+enum TestEnum
+{
+    case A;
+    case B;
+    case C;
+}

tests/tests/DeserializerTest.php

@@ -4,19 +4,23 @@
 
 use Aternos\Serializer\ArrayDeserializer;
 use Aternos\Serializer\Exceptions\IncorrectTypeException;
+use Aternos\Serializer\Exceptions\InvalidEnumBackingException;
 use Aternos\Serializer\Exceptions\MissingPropertyException;
 use Aternos\Serializer\Exceptions\UnsupportedTypeException;
 use Aternos\Serializer\Json\JsonDeserializer;
 use Aternos\Serializer\Serialize;
 use Aternos\Serializer\Test\Src\ArrayDeserializerAccessor;
 use Aternos\Serializer\Test\Src\ArrayTests;
+use Aternos\Serializer\Test\Src\BackedEnumTestClass;
 use Aternos\Serializer\Test\Src\BuiltInTypeTestClass;
 use Aternos\Serializer\Test\Src\CustomSerializerInvalidTypeTestClass;
 use Aternos\Serializer\Test\Src\CustomSerializerTestClass;
 use Aternos\Serializer\Test\Src\DefaultValueTestClass;
+use Aternos\Serializer\Test\Src\EnumTestClass;
 use Aternos\Serializer\Test\Src\IntersectionTestClass;
 use Aternos\Serializer\Test\Src\SecondTestClass;
 use Aternos\Serializer\Test\Src\SerializerTestClass;
+use Aternos\Serializer\Test\Src\TestBackedEnum;
 use Aternos\Serializer\Test\Src\TestClass;
 use Aternos\Serializer\Test\Src\UnionIntersectionTestClass;
 use InvalidArgumentException;
@@ -30,6 +34,7 @@
 #[UsesClass(MissingPropertyException::class)]
 #[UsesClass(UnsupportedTypeException::class)]
 #[UsesClass(JsonDeserializer::class)]
+#[UsesClass(InvalidEnumBackingException::class)]
 class DeserializerTest extends TestCase
 {
     public function testDeserialize(): void
@@ -489,8 +494,7 @@ public function testUnknownBuiltInType(): void
     public function testArrayDeserializerArgumentIsNotAnArray(): void
     {
         $deserializer = new ArrayDeserializerAccessor(TestClass::class);
-        $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage("Data must be an array.");
+        $this->expectException(IncorrectTypeException::class);
         $deserializer->deserialize("not-an-array");
     }
 
@@ -512,4 +516,34 @@ public function testCustomDeserializerReturnsInvalidType(): void
         $this->expectExceptionMessage("Expected '.testClass' to be 'Aternos\Serializer\Test\Src\TestClass' found: \Aternos\Serializer\Test\Src\BuiltInTypeTestClass::");
         $deserializer->deserialize('{"testClass":"Tzo0ODoiQXRlcm5vc1xTZXJpYWxpemVyXFRlc3RcU3JjXEJ1aWx0SW5UeXBlVGVzdENsYXNzIjo4OntzOjM6ImludCI7TjtzOjU6ImZsb2F0IjtOO3M6Njoic3RyaW5nIjtOO3M6NToiYXJyYXkiO047czo2OiJvYmplY3QiO047czo0OiJzZWxmIjtOO3M6NToiZmFsc2UiO047czo0OiJ0cnVlIjtOO30="}');
     }
+
+    public function testDeserializeBackedEnum(): void
+    {
+        $deserializer = new ArrayDeserializerAccessor(BackedEnumTestClass::class);
+        $this->assertEquals(TestBackedEnum::A, $deserializer->deserialize(["enum" => "a"])->getEnum());
+    }
+
+    public function testDeserializeUnbackedEnum(): void
+    {
+        $deserializer = new ArrayDeserializerAccessor(EnumTestClass::class);
+        $this->expectException(UnsupportedTypeException::class);
+        $this->expectExceptionMessage("Unsupported type 'Aternos\Serializer\Test\Src\TestEnum' for property '.enum': Enums must be backed by a scalar type.");
+        $deserializer->deserialize(["enum" => "a"]);
+    }
+
+    public function testDeserializeEnumWithInvalidBackingValue(): void
+    {
+        $deserializer = new ArrayDeserializerAccessor(BackedEnumTestClass::class);
+        $this->expectException(InvalidEnumBackingException::class);
+        $this->expectExceptionMessage("Invalid backing value for enum 'Aternos\Serializer\Test\Src\TestBackedEnum' expected: type 'string' (a, b, c) found: 'd'");
+        $deserializer->deserialize(["enum" => "d"]);
+    }
+
+    public function testDeserializeEnumWithInvalidBackingType(): void
+    {
+        $deserializer = new ArrayDeserializerAccessor(TestBackedEnum::class);
+        $this->expectException(InvalidEnumBackingException::class);
+        $this->expectExceptionMessage("Invalid backing value for enum 'Aternos\Serializer\Test\Src\TestBackedEnum' expected: type 'string' (a, b, c) found: 0");
+        $this->assertEquals(TestBackedEnum::A, $deserializer->deserialize(0));
+    }
 }