add upcaster extension

phpstan-baseline.neon

@@ -198,6 +198,18 @@ parameters:
 			count: 1
 			path: tests/Unit/Extension/Cryptography/Fixture/ChildWithSensitiveDataWithIdentifierDto.php
 
+		-
+			message: '#^Binary operation "\." between mixed and '' '' results in an error\.$#'
+			identifier: binaryOp.invalid
+			count: 1
+			path: tests/Unit/Extension/Upcast/UpcastMiddlewareTest.php
+
+		-
+			message: '#^Binary operation "\." between non\-falsy\-string and mixed results in an error\.$#'
+			identifier: binaryOp.invalid
+			count: 1
+			path: tests/Unit/Extension/Upcast/UpcastMiddlewareTest.php
+
 		-
 			message: '#^Method Patchlevel\\Hydrator\\Tests\\Unit\\Fixture\\DtoWithHooks\:\:postHydrate\(\) is unused\.$#'
 			identifier: method.unused

src/CoreExtension.php

@@ -12,7 +12,7 @@ final class CoreExtension implements Extension
 {
     public function configure(StackHydratorBuilder $builder): void
     {
-        $builder->addMiddleware(new TransformMiddleware(), -64);
+        $builder->addMiddleware(new TransformMiddleware(), Extension::PRIORITY_TRANSFORM);
         $builder->addGuesser(new BuiltInGuesser(), -64);
     }
 }

src/Extension.php

@@ -7,5 +7,17 @@
 /** @experimental */
 interface Extension
 {
+    /** Reshape the raw stored payload before its values are decoded. */
+    public const PRIORITY_BEFORE_ENCODING = 64;
+
+    /** Encode or decode individual field values, the shape stays the same. */
+    public const PRIORITY_ENCODING = 32;
+
+    /** Last structural step before the array becomes an object. */
+    public const PRIORITY_BEFORE_TRANSFORM = 0;
+
+    /** Build the object from the array and deconstruct it again. */
+    public const PRIORITY_TRANSFORM = -64;
+
     public function configure(StackHydratorBuilder $builder): void;
 }

src/Extension/Cryptography/CryptographyExtension.php

@@ -21,7 +21,7 @@
     public function configure(StackHydratorBuilder $builder): void
     {
         $builder->addMetadataEnricher(new CryptographyMetadataEnricher(), 64);
-        $builder->addMiddleware(new CryptographyMiddleware($this->cryptography), 64);
+        $builder->addMiddleware(new CryptographyMiddleware($this->cryptography), Extension::PRIORITY_ENCODING);
 
         if ($this->legacyMetadataMapping) {
             $builder->addMetadataEnricher(new LegacyCryptographyMetadataEnricher(), 63);
@@ -31,6 +31,10 @@
             return;
         }
 
-        $builder->addMiddleware(new LegacyCryptographyDecryptMiddleware($this->legacyCryptographer), 65);
+        // the legacy decrypt has to run before the regular decryption
+        $builder->addMiddleware(
+            new LegacyCryptographyDecryptMiddleware($this->legacyCryptographer),
+            Extension::PRIORITY_ENCODING + 1,
+        );
     }
 }

src/Extension/Lifecycle/LifecycleExtension.php

@@ -12,7 +12,7 @@
 {
     public function configure(StackHydratorBuilder $builder): void
     {
-        $builder->addMiddleware(new LifecycleMiddleware());
+        $builder->addMiddleware(new LifecycleMiddleware(), Extension::PRIORITY_BEFORE_TRANSFORM);
         $builder->addMetadataEnricher(new LifecycleMetadataEnricher());
     }
 }

src/Extension/Upcast/CallbackUpcaster.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Upcast;
+
+use Closure;
+use Patchlevel\Hydrator\Metadata\ClassMetadata;
+
+/** @experimental */
+final class CallbackUpcaster implements Upcaster
+{
+    /** @var Closure(array<string, mixed>, array<string, mixed>): array<string, mixed> */
+    private readonly Closure $callback;
+
+    /**
+     * @param class-string                                                               $className
+     * @param callable(array<string, mixed>, array<string, mixed>): array<string, mixed> $callback
+     */
+    public function __construct(private readonly string $className, callable $callback)
+    {
+        $this->callback = Closure::fromCallable($callback);
+    }
+
+    /**
+     * @param class-string                                                               $className
+     * @param callable(array<string, mixed>, array<string, mixed>): array<string, mixed> $callback
+     */
+    public static function forClass(string $className, callable $callback): self
+    {
+        return new self($className, $callback);
+    }
+
+    /**
+     * @param ClassMetadata<T>     $metadata
+     * @param array<string, mixed> $data
+     * @param array<string, mixed> $context
+     *
+     * @return array<string, mixed>
+     *
+     * @template T of object
+     */
+    public function upcast(ClassMetadata $metadata, array $data, array $context): array
+    {
+        if ($metadata->className !== $this->className) {
+            return $data;
+        }
+
+        return ($this->callback)($data, $context);
+    }
+}

src/Extension/Upcast/UpcastExtension.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Upcast;
+
+use Patchlevel\Hydrator\Extension;
+use Patchlevel\Hydrator\StackHydratorBuilder;
+
+/** @experimental */
+final readonly class UpcastExtension implements Extension
+{
+    /**
+     * @param list<Upcaster> $beforeEncoding  upcasters that reshape the raw stored payload before its values are decoded
+     * @param list<Upcaster> $beforeTransform upcasters that run after value decoding, right before the object is built
+     */
+    public function __construct(
+        private array $beforeEncoding = [],
+        private array $beforeTransform = [],
+    ) {
+    }
+
+    public function configure(StackHydratorBuilder $builder): void
+    {
+        if ($this->beforeEncoding !== []) {
+            $builder->addMiddleware(
+                new UpcastMiddleware($this->beforeEncoding),
+                Extension::PRIORITY_BEFORE_ENCODING,
+            );
+        }
+
+        if ($this->beforeTransform === []) {
+            return;
+        }
+
+        $builder->addMiddleware(
+            new UpcastMiddleware($this->beforeTransform),
+            Extension::PRIORITY_BEFORE_TRANSFORM,
+        );
+    }
+}

src/Extension/Upcast/UpcastMiddleware.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Upcast;
+
+use Patchlevel\Hydrator\Metadata\ClassMetadata;
+use Patchlevel\Hydrator\Middleware\Middleware;
+use Patchlevel\Hydrator\Middleware\Stack;
+
+/** @experimental */
+final readonly class UpcastMiddleware implements Middleware
+{
+    /** @param list<Upcaster> $upcasters */
+    public function __construct(
+        private array $upcasters,
+    ) {
+    }
+
+    /**
+     * @param ClassMetadata<T>     $metadata
+     * @param array<string, mixed> $data
+     * @param array<string, mixed> $context
+     *
+     * @return T
+     *
+     * @template T of object
+     */
+    public function hydrate(ClassMetadata $metadata, array $data, array $context, Stack $stack): object
+    {
+        foreach ($this->upcasters as $upcaster) {
+            $data = $upcaster->upcast($metadata, $data, $context);
+        }
+
+        return $stack->next()->hydrate($metadata, $data, $context, $stack);
+    }
+
+    /**
+     * @param ClassMetadata<T>     $metadata
+     * @param T                    $object
+     * @param array<string, mixed> $context
+     *
+     * @return array<string, mixed>
+     *
+     * @template T of object
+     */
+    public function extract(ClassMetadata $metadata, object $object, array $context, Stack $stack): array
+    {
+        return $stack->next()->extract($metadata, $object, $context, $stack);
+    }
+}

src/Extension/Upcast/Upcaster.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Extension\Upcast;
+
+use Patchlevel\Hydrator\Metadata\ClassMetadata;
+
+/** @experimental */
+interface Upcaster
+{
+    /**
+     * @param ClassMetadata<T>     $metadata
+     * @param array<string, mixed> $data
+     * @param array<string, mixed> $context
+     *
+     * @return array<string, mixed>
+     *
+     * @template T of object
+     */
+    public function upcast(ClassMetadata $metadata, array $data, array $context): array;
+}

src/StackHydratorBuilder.php

@@ -35,7 +35,7 @@ final class StackHydratorBuilder
     private CacheItemPoolInterface|CacheInterface|null $cache = null;
 
     /** @return $this */
-    public function addMiddleware(Middleware $middleware, int $priority = 0): static
+    public function addMiddleware(Middleware $middleware, int $priority = Extension::PRIORITY_BEFORE_TRANSFORM): static
     {
         $this->middlewares[$priority][] = $middleware;
 

tests/Unit/Extension/Upcast/CallbackUpcasterTest.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Tests\Unit\Extension\Upcast;
+
+use Patchlevel\Hydrator\Extension\Upcast\CallbackUpcaster;
+use Patchlevel\Hydrator\Metadata\AttributeMetadataFactory;
+use Patchlevel\Hydrator\Tests\Unit\Extension\Lifecycle\Fixture\LifecycleFixture;
+use Patchlevel\Hydrator\Tests\Unit\Extension\Upcast\Fixture\UpcastFixture;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+use function assert;
+use function is_string;
+
+#[CoversClass(CallbackUpcaster::class)]
+final class CallbackUpcasterTest extends TestCase
+{
+    public function testUpcast(): void
+    {
+        $metadata = (new AttributeMetadataFactory())->metadata(UpcastFixture::class);
+        $upcaster = CallbackUpcaster::forClass(
+            UpcastFixture::class,
+            static function (array $data, array $context): array {
+                $prefix = $context['prefix'] ?? '';
+                $name = $data['name'] ?? '';
+                assert(is_string($prefix));
+                assert(is_string($name));
+
+                $data['name'] = $prefix . $name;
+
+                return $data;
+            },
+        );
+
+        self::assertSame(
+            ['name' => 'Upcast: foo'],
+            $upcaster->upcast($metadata, ['name' => 'foo'], ['prefix' => 'Upcast: ']),
+        );
+    }
+
+    public function testSkipDifferentClass(): void
+    {
+        $metadata = (new AttributeMetadataFactory())->metadata(LifecycleFixture::class);
+        $upcaster = CallbackUpcaster::forClass(
+            UpcastFixture::class,
+            static fn (array $data): array => ['name' => 'changed'],
+        );
+
+        self::assertSame(['name' => 'foo'], $upcaster->upcast($metadata, ['name' => 'foo'], []));
+    }
+}

tests/Unit/Extension/Upcast/Fixture/UpcastFixture.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Tests\Unit\Extension\Upcast\Fixture;
+
+final class UpcastFixture
+{
+    public function __construct(
+        public string $name,
+    ) {
+    }
+}