Extension API with Hydrator Builder

phpstan-baseline.neon

@@ -103,7 +103,7 @@ parameters:
 			path: tests/Unit/Metadata/AttributeMetadataFactoryTest.php
 
 		-
-			message: '#^Parameter \#1 \$class of method Patchlevel\\Hydrator\\MetadataHydrator\:\:hydrate\(\) expects class\-string\<Unknown\>, string given\.$#'
+			message: '#^Parameter \#1 \$class of method Patchlevel\\Hydrator\\Hydrator\:\:hydrate\(\) expects class\-string\<Unknown\>, string given\.$#'
 			identifier: argument.type
 			count: 1
 			path: tests/Unit/MetadataHydratorTest.php

src/CoreExtension.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator;
+
+use Patchlevel\Hydrator\Guesser\BuiltInGuesser;
+use Patchlevel\Hydrator\Middleware\TransformMiddleware;
+
+final class CoreExtension implements Extension
+{
+    public function configure(HydratorBuilder $builder): void
+    {
+        $builder->addMiddleware(new TransformMiddleware(), -64);
+        $builder->addGuesser(new BuiltInGuesser(), -64);
+    }
+}

src/Cryptography/CryptographyExtension.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Cryptography;
+
+use Patchlevel\Hydrator\Extension;
+use Patchlevel\Hydrator\HydratorBuilder;
+
+final class CryptographyExtension implements Extension
+{
+    public function __construct(
+        private readonly PayloadCryptographer $cryptography,
+    ) {
+    }
+
+    public function configure(HydratorBuilder $builder): void
+    {
+        $builder->addMetadataEnricher(new CryptographyMetadataEnricher(), 64);
+        $builder->addMiddleware(new CryptographyMiddleware($this->cryptography), 64);
+    }
+}

src/Cryptography/CryptographyMetadataFactory.php → src/Cryptography/CryptographyMetadataEnricher.php

@@ -7,25 +7,18 @@
 use Patchlevel\Hydrator\Attribute\DataSubjectId;
 use Patchlevel\Hydrator\Attribute\SensitiveData;
 use Patchlevel\Hydrator\Metadata\ClassMetadata;
-use Patchlevel\Hydrator\Metadata\MetadataFactory;
+use Patchlevel\Hydrator\Metadata\MetadataEnricher;
 use ReflectionProperty;
 
 use function array_key_exists;
 
-final class CryptographyMetadataFactory implements MetadataFactory
+final class CryptographyMetadataEnricher implements MetadataEnricher
 {
-    public function __construct(
-        private readonly MetadataFactory $metadataFactory,
-    ) {
-    }
-
-    public function metadata(string $class): ClassMetadata
+    public function enrich(ClassMetadata $classMetadata): void
     {
-        $metadata = $this->metadataFactory->metadata($class);
-
         $subjectIdMapping = [];
 
-        foreach ($metadata->properties as $property) {
+        foreach ($classMetadata->properties as $property) {
             $isSubjectId = false;
             $attributeReflectionList = $property->reflection->getAttributes(DataSubjectId::class);
 
@@ -34,8 +27,8 @@ public function metadata(string $class): ClassMetadata
 
                 if (array_key_exists($subjectIdIdentifier, $subjectIdMapping)) {
                     throw new DuplicateSubjectIdIdentifier(
-                        $metadata->className,
-                        $metadata->propertyForField($subjectIdMapping[$subjectIdIdentifier])->propertyName,
+                        $classMetadata->className,
+                        $classMetadata->propertyForField($subjectIdMapping[$subjectIdIdentifier])->propertyName,
                         $property->propertyName,
                         $subjectIdIdentifier,
                     );
@@ -53,17 +46,17 @@ public function metadata(string $class): ClassMetadata
             }
 
             if ($isSubjectId) {
-                throw new SubjectIdAndSensitiveDataConflict($metadata->className, $property->propertyName);
+                throw new SubjectIdAndSensitiveDataConflict($classMetadata->className, $property->propertyName);
             }
 
             $property->extras[SensitiveDataInfo::class] = $sensitiveDataInfo;
         }
 
-        if ($subjectIdMapping !== []) {
-            $metadata->extras[SubjectIdFieldMapping::class] = new SubjectIdFieldMapping($subjectIdMapping);
+        if ($subjectIdMapping === []) {
+            return;
         }
 
-        return $metadata;
+        $classMetadata->extras[SubjectIdFieldMapping::class] = new SubjectIdFieldMapping($subjectIdMapping);
     }
 
     private function sensitiveDataInfo(ReflectionProperty $reflectionProperty): SensitiveDataInfo|null

src/Extension.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator;
+
+interface Extension
+{
+    public function configure(HydratorBuilder $builder): void;
+}

src/HydratorBuilder.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator;
+
+use Patchlevel\Hydrator\Guesser\ChainGuesser;
+use Patchlevel\Hydrator\Guesser\Guesser;
+use Patchlevel\Hydrator\Metadata\AttributeMetadataFactory;
+use Patchlevel\Hydrator\Metadata\MetadataEnricher;
+use Patchlevel\Hydrator\Middleware\Middleware;
+
+use function array_merge;
+use function krsort;
+
+final class HydratorBuilder
+{
+    private bool $defaultLazy = false;
+
+    /** @var array<int, list<Middleware>> */
+    private array $middlewares = [];
+
+    /** @var array<int, list<MetadataEnricher>> */
+    private array $metadataEnrichers = [];
+
+    /** @var array<int, list<Guesser>> */
+    private array $guessers = [];
+
+    /** @return $this */
+    public function addMiddleware(Middleware $middleware, int $priority = 0): static
+    {
+        $this->middlewares[$priority][] = $middleware;
+
+        return $this;
+    }
+
+    /** @return $this */
+    public function addMetadataEnricher(MetadataEnricher $enricher, int $priority = 0): static
+    {
+        $this->metadataEnrichers[$priority][] = $enricher;
+
+        return $this;
+    }
+
+    /** @return $this */
+    public function addGuesser(Guesser $guesser, int $priority = 0): static
+    {
+        $this->guessers[$priority][] = $guesser;
+
+        return $this;
+    }
+
+    public function enableDefaultLazy(bool $lazy = true): static
+    {
+        $this->defaultLazy = $lazy;
+
+        return $this;
+    }
+
+    public function useExtension(Extension $extension): static
+    {
+        $extension->configure($this);
+
+        return $this;
+    }
+
+    public function build(): Hydrator
+    {
+        krsort($this->middlewares);
+        krsort($this->metadataEnrichers);
+        krsort($this->guessers);
+
+        return new MetadataHydrator(
+            new AttributeMetadataFactory(
+                guesser: new ChainGuesser(array_merge(...$this->guessers)),
+            ),
+            array_merge(...$this->middlewares),
+            array_merge(...$this->metadataEnrichers),
+            $this->defaultLazy,
+        );
+    }
+}

src/Metadata/AttributeMetadataFactory.php

@@ -41,7 +41,7 @@ public function __construct(
         Guesser|null $guesser = null,
     ) {
         $this->typeResolver = $typeResolver ?: TypeResolver::create();
-        $this->guesser = $guesser ?: new BuiltInGuesser(false);
+        $this->guesser = $guesser ?: new BuiltInGuesser();
     }
 
     /**

src/Metadata/MetadataEnricher.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Metadata;
+
+interface MetadataEnricher
+{
+    public function enrich(ClassMetadata $classMetadata): void;
+}

src/MetadataHydrator.php

@@ -4,16 +4,13 @@
 
 namespace Patchlevel\Hydrator;
 
-use Patchlevel\Hydrator\Guesser\BuiltInGuesser;
-use Patchlevel\Hydrator\Guesser\ChainGuesser;
-use Patchlevel\Hydrator\Guesser\Guesser;
 use Patchlevel\Hydrator\Metadata\AttributeMetadataFactory;
 use Patchlevel\Hydrator\Metadata\ClassMetadata;
 use Patchlevel\Hydrator\Metadata\ClassNotFound;
+use Patchlevel\Hydrator\Metadata\MetadataEnricher;
 use Patchlevel\Hydrator\Metadata\MetadataFactory;
 use Patchlevel\Hydrator\Middleware\Middleware;
 use Patchlevel\Hydrator\Middleware\Stack;
-use Patchlevel\Hydrator\Middleware\TransformMiddleware;
 use Patchlevel\Hydrator\Normalizer\HydratorAwareNormalizer;
 use ReflectionClass;
 
@@ -26,10 +23,14 @@
     /** @var array<class-string, ClassMetadata> */
     private array $classMetadata = [];
 
-    /** @param list<Middleware> $middlewares */
+    /**
+     * @param list<Middleware>       $middlewares
+     * @param list<MetadataEnricher> $metadataEnrichers
+     */
     public function __construct(
         private readonly MetadataFactory $metadataFactory = new AttributeMetadataFactory(),
         private readonly array $middlewares = [],
+        private readonly array $metadataEnrichers = [],
         private readonly bool $defaultLazy = false,
     ) {
     }
@@ -110,33 +111,10 @@
             $property->normalizer->setHydrator($this);
         }
 
-        return $metadata;
-    }
-
-    /**
-     * @param list<Middleware>  $additionalMiddleware
-     * @param iterable<Guesser> $guessers
-     */
-    public static function create(
-        array $additionalMiddleware = [],
-        iterable $guessers = [],
-        bool $defaultLazy = false,
-    ): self {
-        $guesser = new BuiltInGuesser();
-
-        if ($guessers !== []) {
-            $guesser = new ChainGuesser([
-                ...$guessers,
-                $guesser,
-            ]);
+        foreach ($this->metadataEnrichers as $enricher) {
+            $enricher->enrich($metadata);
         }
 
-        return new self(
-            new AttributeMetadataFactory(
-                guesser: $guesser,
-            ),
-            [...$additionalMiddleware, new TransformMiddleware()],
-            $defaultLazy,
-        );
+        return $metadata;
     }
 }

tests/Benchmark/HydratorBench.php

@@ -4,8 +4,9 @@
 
 namespace Patchlevel\Hydrator\Tests\Benchmark;
 
+use Patchlevel\Hydrator\CoreExtension;
 use Patchlevel\Hydrator\Hydrator;
-use Patchlevel\Hydrator\MetadataHydrator;
+use Patchlevel\Hydrator\HydratorBuilder;
 use Patchlevel\Hydrator\Tests\Benchmark\Fixture\ProfileCreated;
 use Patchlevel\Hydrator\Tests\Benchmark\Fixture\ProfileId;
 use Patchlevel\Hydrator\Tests\Benchmark\Fixture\Skill;
@@ -18,7 +19,9 @@ final class HydratorBench
 
     public function __construct()
     {
-        $this->hydrator = MetadataHydrator::create();
+        $this->hydrator = (new HydratorBuilder())
+            ->useExtension(new CoreExtension())
+            ->build();
     }
 
     public function setUp(): void

tests/Benchmark/HydratorWithCryptographyBench.php

@@ -4,14 +4,12 @@
 
 namespace Patchlevel\Hydrator\Tests\Benchmark;
 
-use Patchlevel\Hydrator\Cryptography\CryptographyMetadataFactory;
-use Patchlevel\Hydrator\Cryptography\CryptographyMiddleware;
+use Patchlevel\Hydrator\CoreExtension;
+use Patchlevel\Hydrator\Cryptography\CryptographyExtension;
 use Patchlevel\Hydrator\Cryptography\SensitiveDataPayloadCryptographer;
 use Patchlevel\Hydrator\Cryptography\Store\InMemoryCipherKeyStore;
 use Patchlevel\Hydrator\Hydrator;
-use Patchlevel\Hydrator\Metadata\AttributeMetadataFactory;
-use Patchlevel\Hydrator\MetadataHydrator;
-use Patchlevel\Hydrator\Middleware\TransformMiddleware;
+use Patchlevel\Hydrator\HydratorBuilder;
 use Patchlevel\Hydrator\Tests\Benchmark\Fixture\ProfileCreated;
 use Patchlevel\Hydrator\Tests\Benchmark\Fixture\ProfileId;
 use Patchlevel\Hydrator\Tests\Benchmark\Fixture\Skill;
@@ -28,13 +26,10 @@ public function __construct()
     {
         $this->store = new InMemoryCipherKeyStore();
 
-        $this->hydrator = new MetadataHydrator(
-            new CryptographyMetadataFactory(new AttributeMetadataFactory()),
-            [
-                new CryptographyMiddleware(SensitiveDataPayloadCryptographer::createWithDefaultSettings($this->store)),
-                new TransformMiddleware(),
-            ],
-        );
+        $this->hydrator = (new HydratorBuilder())
+            ->useExtension(new CoreExtension())
+            ->useExtension(new CryptographyExtension(SensitiveDataPayloadCryptographer::createWithDefaultSettings($this->store)))
+            ->build();
     }
 
     public function setUp(): void

tests/Benchmark/HydratorWithLazyBench.php

@@ -4,8 +4,9 @@
 
 namespace Patchlevel\Hydrator\Tests\Benchmark;
 
+use Patchlevel\Hydrator\CoreExtension;
 use Patchlevel\Hydrator\Hydrator;
-use Patchlevel\Hydrator\MetadataHydrator;
+use Patchlevel\Hydrator\HydratorBuilder;
 use Patchlevel\Hydrator\Tests\Benchmark\Fixture\ProfileCreated;
 use PhpBench\Attributes as Bench;
 
@@ -16,7 +17,10 @@ final class HydratorWithLazyBench
 
     public function __construct()
     {
-        $this->hydrator = MetadataHydrator::create(defaultLazy: true);
+        $this->hydrator = (new HydratorBuilder())
+            ->useExtension(new CoreExtension())
+            ->enableDefaultLazy()
+            ->build();
     }
 
     public function setUp(): void