Merge pull request #13 from nuxtifyts/feature/with-normalizers-and-with-serializer-attributes

Fa-BRAIK · web-flow · commit 5ba9880fafec · 2024-12-31T19:30:00.000-05:00
Add support for normalizers via attributes
diff --git a/clover.xml b/clover.xml
diff --git a/docs/Normalizers.md b/docs/Normalizers.md
@@ -77,7 +77,21 @@ final readonly class GoalTodoNormalizer extends Normalizer
 }
 ```
 
-Next step is to add this new normalizer to the todo class:
+Next step is to add this new normalizer to the todo class, either using 
+an attribute:
+
+```php
+use Nuxtifyts\PhpDto\Data;
+use Nuxtifyts\PhpDto\Attributes\Class\WithNormalizer;
+
+#[WithNormalizer(GoalTodoNormalizer::class)]
+final readonly class TodoData extends Data
+{
+    // ...
+}
+```
+
+Or using a method:
 
 ```php
 use Nuxtifyts\PhpDto\Data;
diff --git a/src/Attributes/Class/WithNormalizer.php b/src/Attributes/Class/WithNormalizer.php
@@ -0,0 +1,30 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Attributes\Class;
+
+use Attribute;
+use InvalidArgumentException;
+use Nuxtifyts\PhpDto\Normalizers\Normalizer;
+use Nuxtifyts\PhpDto\Support\Arr;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class WithNormalizer
+{
+    /** @var array<array-key, class-string<Normalizer>> */
+    public array $classStrings;
+
+    /**
+     * @param class-string<Normalizer> $classString
+     * @param class-string<Normalizer> ...$classStrings
+     */
+    public function __construct(string $classString, string ...$classStrings)
+    {
+        $arrOfClassStrings = [$classString, ...$classStrings];
+
+        if (!Arr::isArrayOfClassStrings($arrOfClassStrings, Normalizer::class)) {
+            throw new InvalidArgumentException('expects a list of class strings of normalizers');
+        }
+
+        $this->classStrings = $arrOfClassStrings;
+    }
+}
diff --git a/src/Concerns/BaseData.php b/src/Concerns/BaseData.php
@@ -22,16 +22,16 @@ trait BaseData
     final public static function create(mixed ...$args): static
     {
         try {
-            $value = static::normalizeValue($args, static::class)
-                ?: static::normalizeValue($args[0] ?? [], static::class);
+            /** @var ClassContext<static> $context */
+            $context = ClassContext::getInstance(static::class);
+
+            $value = static::normalizeValue($args, static::class, $context->normalizers)
+                ?: static::normalizeValue($args[0] ?? [], static::class, $context->normalizers);
 
             if ($value === false) {
                 throw DataCreationException::invalidParamsPassed(static::class);
             }
 
-            /** @var ClassContext<static> $context */
-            $context = ClassContext::getInstance(new ReflectionClass(static::class));
-
             $data = DeserializePipeline::createFromArray()
                 ->sendThenReturn(new DeserializePipelinePassable(
                     classContext: $context,
@@ -51,15 +51,15 @@ classContext: $context,
     final public static function from(mixed $value): static
     {
         try {
-            $value = static::normalizeValue($value, static::class);
+            /** @var ClassContext<static> $context */
+            $context = ClassContext::getInstance(static::class);
+
+            $value = static::normalizeValue($value, static::class, $context->normalizers);
 
             if ($value === false) {
                 throw DeserializeException::invalidValue();
             }
 
-            /** @var ClassContext<static> $context */
-            $context = ClassContext::getInstance(new ReflectionClass(static::class));
-
             $data = DeserializePipeline::hydrateFromArray()
                 ->sendThenReturn(new DeserializePipelinePassable(
                     classContext: $context,
@@ -126,7 +126,7 @@ protected static function instanceWithConstructorCallFrom(ClassContext $context,
     final public function jsonSerialize(): array
     {
         try {
-            $context = ClassContext::getInstance(new ReflectionClass($this));
+            $context = ClassContext::getInstance($this::class);
 
             $serializedData = [];
             foreach ($context->properties as $propertyContext) {
diff --git a/src/Concerns/CloneableData.php b/src/Concerns/CloneableData.php
@@ -22,16 +22,16 @@ public function with(mixed ...$args): static
                 throw DataCreationException::invalidParamsPassed(static::class);
             }
 
-            $value = static::normalizeValue($args, static::class)
-                ?: static::normalizeValue($args[0], static::class);
+            /** @var ClassContext<static> $context */
+            $context = ClassContext::getInstance(static::class);
+
+            $value = static::normalizeValue($args, static::class, $context->normalizers)
+                ?: static::normalizeValue($args[0], static::class, $context->normalizers);
 
             if ($value === false) {
                 throw DataCreationException::invalidParamsPassed(static::class);
             }
 
-            /** @var ClassContext<static> $context */
-            $context = ClassContext::getInstance(new ReflectionClass(static::class));
-
             return $context->hasComputedProperties
                 ? $this->cloneInstanceWithConstructorCall($context, $value)
                 : $this->cloneInstanceWithoutConstructorCall($context, $value);
diff --git a/src/Concerns/EmptyData.php b/src/Concerns/EmptyData.php
@@ -16,7 +16,7 @@ public static function empty(): static
     {
         try {
             /** @var ClassContext<static> $classContext */
-            $classContext = ClassContext::getInstance(new ReflectionClass(static::class));
+            $classContext = ClassContext::getInstance(static::class);
 
             return $classContext->emptyValue();
         } catch (Throwable $t) {
diff --git a/src/Contexts/ClassContext.php b/src/Contexts/ClassContext.php
@@ -2,9 +2,12 @@
 
 namespace Nuxtifyts\PhpDto\Contexts;
 
+use Nuxtifyts\PhpDto\Attributes\Class\WithNormalizer;
 use Nuxtifyts\PhpDto\Data;
 use Nuxtifyts\PhpDto\Exceptions\DataCreationException;
 use Nuxtifyts\PhpDto\Exceptions\UnsupportedTypeException;
+use Nuxtifyts\PhpDto\Normalizers\Normalizer;
+use ReflectionAttribute;
 use ReflectionException;
 use ReflectionParameter;
 use ReflectionClass;
@@ -30,6 +33,9 @@ class ClassContext
     /** @var list<string> List of param names  */
     public readonly array $constructorParams;
 
+    /** @var array<array-key, class-string<Normalizer>> */
+    private(set) array $normalizers = [];
+
     /**
      * @param ReflectionClass<T> $reflection
      *
@@ -43,6 +49,7 @@ final private function __construct(
             static fn (ReflectionParameter $param) => $param->getName(),
             $this->reflection->getConstructor()?->getParameters() ?? [],
         );
+        $this->syncClassAttributes();
     }
 
     public bool $hasComputedProperties {
@@ -55,22 +62,33 @@ final private function __construct(
     }
 
     /**
-     * @param ReflectionClass<T> $reflectionClass
+     * @param ReflectionClass<T>|class-string<T> $reflectionClass
      *
      * @throws UnsupportedTypeException
+     * @throws ReflectionException
      */
-    final public static function getInstance(ReflectionClass $reflectionClass): static
+    final public static function getInstance(string|ReflectionClass $reflectionClass): static
     {
+        $instance = self::$_instances[self::getKey($reflectionClass)] ?? null;
+
+        if ($instance) {
+            return $instance;
+        }
+
+        if (is_string($reflectionClass)) {
+            $reflectionClass = new ReflectionClass($reflectionClass);
+        }
+
         return self::$_instances[self::getKey($reflectionClass)]
-            ??= new static($reflectionClass);
+            = new static($reflectionClass);
     }
 
     /**
-     * @param ReflectionClass<T> $reflectionClass
+     * @param ReflectionClass<T>|class-string<T> $reflectionClass
      */
-    private static function getKey(ReflectionClass $reflectionClass): string
+    private static function getKey(string|ReflectionClass $reflectionClass): string
     {
-        return $reflectionClass->getName();
+        return is_string($reflectionClass) ? $reflectionClass : $reflectionClass->getName();
     }
 
     /**
@@ -91,6 +109,17 @@ private static function getPropertyContexts(ReflectionClass $reflectionClass): a
         return $properties;
     }
 
+    private function syncClassAttributes(): void
+    {
+        foreach ($this->reflection->getAttributes(WithNormalizer::class) as $withNormalizerAttribute) {
+            /** @var ReflectionAttribute<WithNormalizer> $withNormalizerAttribute */
+            $this->normalizers = array_values([
+                ...$this->normalizers,
+                ...$withNormalizerAttribute->newInstance()->classStrings
+            ]);
+        }
+    }
+
     /**
      * @throws ReflectionException
      *
diff --git a/src/Normalizers/Concerns/HasNormalizers.php b/src/Normalizers/Concerns/HasNormalizers.php
@@ -3,22 +3,28 @@
 namespace Nuxtifyts\PhpDto\Normalizers\Concerns;
 
 use Nuxtifyts\PhpDto\Configuration\DataConfiguration;
+use Nuxtifyts\PhpDto\Contexts\ClassContext;
 use Nuxtifyts\PhpDto\Data;
 use Nuxtifyts\PhpDto\Exceptions\DataConfigurationException;
 use Nuxtifyts\PhpDto\Normalizers\Normalizer;
+use ReflectionClass;
 
 trait HasNormalizers
 {
     /**
      * @param class-string<Data> $class
+     * @param array<array-key, class-string<Normalizer>> $classNormalizers
      *
      * @return array<string, mixed>|false
      *
      * @throws DataConfigurationException
      */
-    protected static function normalizeValue(mixed $value, string $class): array|false
-    {
-        foreach (static::allNormalizer() as $normalizer) {
+    protected static function normalizeValue(
+        mixed $value,
+        string $class,
+        array $classNormalizers = []
+    ): array|false {
+        foreach (static::allNormalizer($classNormalizers) as $normalizer) {
             $normalized = new $normalizer($value, $class)->normalize();
 
             if ($normalized !== false) {
@@ -30,13 +36,16 @@ protected static function normalizeValue(mixed $value, string $class): array|fal
     }
 
     /**
+     * @param array<array-key, class-string<Normalizer>> $classNormalizers
+     *
      * @return list<class-string<Normalizer>>
      *
      * @throws DataConfigurationException
      */
-    final protected static function allNormalizer(): array
+    final protected static function allNormalizer(array $classNormalizers = []): array
     {
         return array_values(array_unique([
+            ...$classNormalizers,
             ...static::normalizers(),
             ...DataConfiguration::getInstance()->normalizers->baseNormalizers,
         ]));
diff --git a/tests/Dummies/DummyWithNormalizerData.php b/tests/Dummies/DummyWithNormalizerData.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Dummies;
+
+use Nuxtifyts\PhpDto\Attributes\Class\WithNormalizer;
+use Nuxtifyts\PhpDto\Data;
+use Nuxtifyts\PhpDto\Tests\Dummies\Normalizers\DummyNormalizer;
+
+#[WithNormalizer(DummyNormalizer::class)]
+final readonly class DummyWithNormalizerData extends Data
+{
+    public function __construct() {
+    }
+}
diff --git a/tests/Dummies/NonData/Human.php b/tests/Dummies/NonData/Human.php
@@ -0,0 +1,12 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Dummies\NonData;
+
+class Human
+{
+    public function __construct(
+        public string $name,
+        public string $surname
+    ) {
+    }
+}
diff --git a/tests/Dummies/Normalizers/HumanToPersonNormalizer.php b/tests/Dummies/Normalizers/HumanToPersonNormalizer.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Dummies\Normalizers;
+
+use Nuxtifyts\PhpDto\Tests\Dummies\NonData\Human;
+use Nuxtifyts\PhpDto\Normalizers\Normalizer;
+
+final readonly class HumanToPersonNormalizer extends Normalizer
+{
+    /**
+     * @return array<string, mixed>|false
+     */
+    public function normalize(): array|false
+    {
+        return $this->value instanceof Human
+            ? [
+                'firstName' => $this->value->name,
+                'lastName' => $this->value->surname
+            ]
+            : false;
+    }
+}
diff --git a/tests/Dummies/PersonData.php b/tests/Dummies/PersonData.php
@@ -2,10 +2,15 @@
 
 namespace Nuxtifyts\PhpDto\Tests\Dummies;
 
+use Nuxtifyts\PhpDto\Tests\Dummies\Normalizers\DummyNormalizer;
+use Nuxtifyts\PhpDto\Tests\Dummies\Normalizers\HumanToPersonNormalizer;
+use Nuxtifyts\PhpDto\Attributes\Class\WithNormalizer;
 use Nuxtifyts\PhpDto\Attributes\Property\Aliases;
 use Nuxtifyts\PhpDto\Attributes\Property\Computed;
 use Nuxtifyts\PhpDto\Data;
 
+#[WithNormalizer(DummyNormalizer::class)]
+#[WithNormalizer(HumanToPersonNormalizer::class)]
 final readonly class PersonData extends Data
 {
     #[Computed]
diff --git a/tests/Unit/Attributes/WithNormalizerTest.php b/tests/Unit/Attributes/WithNormalizerTest.php
diff --git a/tests/Unit/Contexts/ClassContextTest.php b/tests/Unit/Contexts/ClassContextTest.php

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ public static function empty(): static`
`16`	`16`	`{`
`17`	`17`	`try {`
`18`	`18`	`/** @var ClassContext<static> $classContext */`
`19`		`- $classContext = ClassContext::getInstance(new ReflectionClass(static::class));`
	`19`	`+ $classContext = ClassContext::getInstance(static::class);`
`20`	`20`
`21`	`21`	`return $classContext->emptyValue();`
`22`	`22`	`} catch (Throwable $t) {`