From cee847ca6de0ea419e53c3f483bc358b6722ff11 Mon Sep 17 00:00:00 2001 From: David Badura Date: Fri, 6 Nov 2026 17:11:21 +0100 Subject: [PATCH 1/4] Reject documents with a class level normalizer Hydrator 2 uses a normalizer on the class, a parent or an interface for the whole object, while v1 ignored it on the root class. A document is stored field by field, so such a normalizer breaks loading and storing in different ways. The metadata factory now fails early with DocumentHasClassNormalizer. To see the normalizer of the actual document class, FieldMappingResolver::resolve() gets the document class name next to the property, whose declaring class is often a parent. The check in DocumentHydrator::extract() stays as a type guard for custom hydrators. --- .../AttributeDocumentMetadataFactory.php | 2 +- src/Metadata/DocumentHasClassNormalizer.php | 26 +++++++++++ src/Metadata/FieldMappingResolver.php | 3 +- .../StackHydratorFieldMappingResolver.php | 14 +++++- tests/Unit/Fixtures/DocumentBase.php | 16 +++++++ tests/Unit/Fixtures/NormalizedContract.php | 10 +++++ .../AttributeDocumentMetadataFactoryTest.php | 25 +++++++++-- .../DiscriminatorMetadataFactoryTest.php | 4 +- .../StackHydratorFieldMappingResolverTest.php | 43 ++++++++++++++++--- 9 files changed, 129 insertions(+), 14 deletions(-) create mode 100644 src/Metadata/DocumentHasClassNormalizer.php create mode 100644 tests/Unit/Fixtures/DocumentBase.php create mode 100644 tests/Unit/Fixtures/NormalizedContract.php diff --git a/src/Metadata/AttributeDocumentMetadataFactory.php b/src/Metadata/AttributeDocumentMetadataFactory.php index 7635496..8e76605 100644 --- a/src/Metadata/AttributeDocumentMetadataFactory.php +++ b/src/Metadata/AttributeDocumentMetadataFactory.php @@ -151,7 +151,7 @@ private function resolveFields( foreach ($reflection->getProperties() as $reflectionProperty) { $name = $reflectionProperty->getName(); - $field = $this->fieldResolver?->resolve($reflectionProperty); + $field = $this->fieldResolver?->resolve($className, $reflectionProperty); if ($idProperty === $name) { $mapping = new FieldMapping('_id', [], $field?->fieldName); diff --git a/src/Metadata/DocumentHasClassNormalizer.php b/src/Metadata/DocumentHasClassNormalizer.php new file mode 100644 index 0000000..e18ea7c --- /dev/null +++ b/src/Metadata/DocumentHasClassNormalizer.php @@ -0,0 +1,26 @@ + $normalizerClass + */ + public function __construct(string $className, string $normalizerClass) + { + parent::__construct(sprintf( + 'The document "%s" has the class level normalizer "%s". Documents are stored field by field and can not be normalized as a whole.', + $className, + $normalizerClass, + )); + } +} diff --git a/src/Metadata/FieldMappingResolver.php b/src/Metadata/FieldMappingResolver.php index b5f67b4..5b96cfc 100644 --- a/src/Metadata/FieldMappingResolver.php +++ b/src/Metadata/FieldMappingResolver.php @@ -8,5 +8,6 @@ interface FieldMappingResolver { - public function resolve(ReflectionProperty $reflectionProperty): FieldMapping|null; + /** @param class-string $className the document class the property is mapped for */ + public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping|null; } diff --git a/src/Metadata/StackHydratorFieldMappingResolver.php b/src/Metadata/StackHydratorFieldMappingResolver.php index 74ef1df..8c7e67f 100644 --- a/src/Metadata/StackHydratorFieldMappingResolver.php +++ b/src/Metadata/StackHydratorFieldMappingResolver.php @@ -19,9 +19,19 @@ public function __construct( ) { } - public function resolve(ReflectionProperty $reflectionProperty): FieldMapping + /** + * @param class-string $className + * + * @throws DocumentHasClassNormalizer + */ + public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping { - $metadata = $this->hydrator->metadata($reflectionProperty->getDeclaringClass()->getName()); + $metadata = $this->hydrator->metadata($className); + + if ($metadata->normalizer !== null) { + throw new DocumentHasClassNormalizer($className, $metadata->normalizer::class); + } + $property = $metadata->properties[$reflectionProperty->getName()]; return $this->resolvePropertyMetadata($property); diff --git a/tests/Unit/Fixtures/DocumentBase.php b/tests/Unit/Fixtures/DocumentBase.php new file mode 100644 index 0000000..b5c4139 --- /dev/null +++ b/tests/Unit/Fixtures/DocumentBase.php @@ -0,0 +1,16 @@ +getName() === 'status') { return new FieldMapping('_newStatus', []); @@ -185,7 +190,7 @@ className: Profile::class, $fieldResolver = new class implements FieldMappingResolver { - public function resolve(ReflectionProperty $reflectionProperty): FieldMapping|null + public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping|null { if ($reflectionProperty->getName() === 'id') { return new FieldMapping('_otherId', []); @@ -246,7 +251,7 @@ public function __construct( $fieldResolver = new class implements FieldMappingResolver { - public function resolve(ReflectionProperty $reflectionProperty): FieldMapping|null + public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping|null { if ($reflectionProperty->getName() === 'version') { return new FieldMapping('_version', []); @@ -302,4 +307,18 @@ public function __construct( $factory->metadata($class::class); } + + public function testMetadataOfADocumentWithAClassNormalizer(): void + { + $document = new #[Document('things')] + #[SkillNormalizer] + class ('1') extends DocumentBase { + }; + + $factory = new AttributeDocumentMetadataFactory(new StackHydratorFieldMappingResolver(new StackHydrator())); + + $this->expectException(DocumentHasClassNormalizer::class); + + $factory->metadata($document::class); + } } diff --git a/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php b/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php index 1f8f9bc..7fac6cc 100644 --- a/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php +++ b/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php @@ -75,7 +75,7 @@ public function testFieldsAreUnionedAcrossTheHierarchy(): void public function testConflictingFieldMappingAcrossSubclasses(): void { $resolver = new class implements FieldMappingResolver { - public function resolve(ReflectionProperty $reflectionProperty): FieldMapping + public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping { $name = $reflectionProperty->getName(); @@ -135,7 +135,7 @@ public function __construct( private function fieldResolver(): FieldMappingResolver { return new class implements FieldMappingResolver { - public function resolve(ReflectionProperty $reflectionProperty): FieldMapping + public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping { return new FieldMapping($reflectionProperty->getName()); } diff --git a/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php b/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php index 3eb12a4..d8c18da 100644 --- a/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php +++ b/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php @@ -7,15 +7,22 @@ use Patchlevel\Hydrator\Guesser\BuiltInGuesser; use Patchlevel\Hydrator\Metadata\AttributeMetadataFactory; use Patchlevel\Hydrator\StackHydrator; +use Patchlevel\ODM\Metadata\DocumentHasClassNormalizer; use Patchlevel\ODM\Metadata\FieldMapping; use Patchlevel\ODM\Metadata\StackHydratorFieldMappingResolver; +use Patchlevel\ODM\Tests\Unit\Fixtures\DocumentBase; +use Patchlevel\ODM\Tests\Unit\Fixtures\NormalizedContract; use Patchlevel\ODM\Tests\Unit\Fixtures\PersonalData; use Patchlevel\ODM\Tests\Unit\Fixtures\Profile; +use Patchlevel\ODM\Tests\Unit\Fixtures\SkillNormalizer; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\TestCase; use ReflectionProperty; +use function sprintf; + #[CoversClass(StackHydratorFieldMappingResolver::class)] +#[CoversClass(DocumentHasClassNormalizer::class)] final class StackHydratorFieldMappingResolverTest extends TestCase { private StackHydratorFieldMappingResolver $resolver; @@ -34,14 +41,14 @@ public function setUp(): void public function testResolvePropertyWithoutNormalizer(): void { - $mapping = $this->resolver->resolve(new ReflectionProperty(PersonalData::class, 'name')); + $mapping = $this->resolver->resolve(PersonalData::class, new ReflectionProperty(PersonalData::class, 'name')); self::assertEquals(new FieldMapping('_name'), $mapping); } public function testResolvePropertyWithObjectNormalizer(): void { - $mapping = $this->resolver->resolve(new ReflectionProperty(Profile::class, 'personalData')); + $mapping = $this->resolver->resolve(Profile::class, new ReflectionProperty(Profile::class, 'personalData')); self::assertEquals( new FieldMapping('_personal_data', [ @@ -54,7 +61,7 @@ public function testResolvePropertyWithObjectNormalizer(): void public function testResolvePropertyWithArrayOfObjectNormalizer(): void { - $mapping = $this->resolver->resolve(new ReflectionProperty(Profile::class, 'addresses')); + $mapping = $this->resolver->resolve(Profile::class, new ReflectionProperty(Profile::class, 'addresses')); self::assertEquals( new FieldMapping('_addresses', [ @@ -67,7 +74,7 @@ public function testResolvePropertyWithArrayOfObjectNormalizer(): void public function testResolvePropertyWithCustomNormalizer(): void { - $mapping = $this->resolver->resolve(new ReflectionProperty(Profile::class, 'skills')); + $mapping = $this->resolver->resolve(Profile::class, new ReflectionProperty(Profile::class, 'skills')); self::assertEquals( new FieldMapping('_skills'), @@ -77,7 +84,7 @@ public function testResolvePropertyWithCustomNormalizer(): void public function testResolvePropertyWithArrayShapeNormalizer(): void { - $mapping = $this->resolver->resolve(new ReflectionProperty(Profile::class, 'stats')); + $mapping = $this->resolver->resolve(Profile::class, new ReflectionProperty(Profile::class, 'stats')); self::assertEquals( new FieldMapping('_stats', [ @@ -89,4 +96,30 @@ public function testResolvePropertyWithArrayShapeNormalizer(): void $mapping, ); } + + public function testResolveFailsForADocumentWithAClassNormalizer(): void + { + $document = new #[SkillNormalizer] + class ('1') extends DocumentBase { + }; + + $this->expectException(DocumentHasClassNormalizer::class); + $this->expectExceptionMessage(sprintf( + 'The document "%s" has the class level normalizer "%s".', + $document::class, + SkillNormalizer::class, + )); + + $this->resolver->resolve($document::class, new ReflectionProperty($document, 'id')); + } + + public function testResolveFailsForADocumentWithANormalizerFromAnInterface(): void + { + $document = new class ('1') extends DocumentBase implements NormalizedContract { + }; + + $this->expectException(DocumentHasClassNormalizer::class); + + $this->resolver->resolve($document::class, new ReflectionProperty($document, 'id')); + } } From 3a2c1d49e49ed637de3ff2a45d9c3b633dc0726c Mon Sep 17 00:00:00 2001 From: David Badura Date: Fri, 6 Nov 2026 18:00:19 +0100 Subject: [PATCH 2/4] Resolve field mappings per document class FieldMappingResolver::resolve() now takes the document class and returns the mappings of all its properties. The class normalizer check runs once per class, so it also catches subclasses without visible properties of their own, for example when the root declares a private id. Since the stack hydrator resolver now walks the hydrator metadata instead of reflection, properties the hydrator does not store (#[Ignore], static) no longer crash the metadata build, and private properties of a parent class get a mapping like every other stored field. --- .../AttributeDocumentMetadataFactory.php | 22 ++++------- src/Metadata/FieldMappingResolver.php | 10 +++-- .../StackHydratorFieldMappingResolver.php | 27 ++++++++----- tests/Unit/Fixtures/Circle.php | 13 +++++++ .../Unit/Fixtures/NormalizedDocumentBase.php | 10 +++++ tests/Unit/Fixtures/Shape.php | 28 +++++++++++++ tests/Unit/Fixtures/Square.php | 11 ++++++ .../AttributeDocumentMetadataFactoryTest.php | 38 +++++++++--------- .../DiscriminatorMetadataFactoryTest.php | 27 +++++++++---- .../StackHydratorFieldMappingResolverTest.php | 39 +++++++++++++++---- 10 files changed, 161 insertions(+), 64 deletions(-) create mode 100644 tests/Unit/Fixtures/Circle.php create mode 100644 tests/Unit/Fixtures/NormalizedDocumentBase.php create mode 100644 tests/Unit/Fixtures/Shape.php create mode 100644 tests/Unit/Fixtures/Square.php diff --git a/src/Metadata/AttributeDocumentMetadataFactory.php b/src/Metadata/AttributeDocumentMetadataFactory.php index 8e76605..9c0f0d2 100644 --- a/src/Metadata/AttributeDocumentMetadataFactory.php +++ b/src/Metadata/AttributeDocumentMetadataFactory.php @@ -147,22 +147,14 @@ private function resolveFields( $fields = []; foreach ($classNames as $className) { - $reflection = new ReflectionClass($className); - - foreach ($reflection->getProperties() as $reflectionProperty) { - $name = $reflectionProperty->getName(); - $field = $this->fieldResolver?->resolve($className, $reflectionProperty); - - if ($idProperty === $name) { - $mapping = new FieldMapping('_id', [], $field?->fieldName); - } elseif ($versionProperty === $name) { - $mapping = $field ?? new FieldMapping($name); - } elseif ($field !== null) { - $mapping = $field; - } else { - continue; - } + $mappings = $this->fieldResolver?->resolve($className) ?? []; + $mappings[$idProperty] = new FieldMapping('_id', [], ($mappings[$idProperty] ?? null)?->fieldName); + + if ($versionProperty !== null) { + $mappings[$versionProperty] ??= new FieldMapping($versionProperty); + } + foreach ($mappings as $name => $mapping) { if (isset($fields[$name])) { if (!$this->fieldMappingEquals($fields[$name], $mapping)) { throw new DiscriminatorFieldConflict( diff --git a/src/Metadata/FieldMappingResolver.php b/src/Metadata/FieldMappingResolver.php index 5b96cfc..4df00d9 100644 --- a/src/Metadata/FieldMappingResolver.php +++ b/src/Metadata/FieldMappingResolver.php @@ -4,10 +4,12 @@ namespace Patchlevel\ODM\Metadata; -use ReflectionProperty; - interface FieldMappingResolver { - /** @param class-string $className the document class the property is mapped for */ - public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping|null; + /** + * @param class-string $className + * + * @return array keyed by property name + */ + public function resolve(string $className): array; } diff --git a/src/Metadata/StackHydratorFieldMappingResolver.php b/src/Metadata/StackHydratorFieldMappingResolver.php index 8c7e67f..cedffa2 100644 --- a/src/Metadata/StackHydratorFieldMappingResolver.php +++ b/src/Metadata/StackHydratorFieldMappingResolver.php @@ -4,13 +4,13 @@ namespace Patchlevel\ODM\Metadata; +use Patchlevel\Hydrator\Metadata\ClassMetadata; use Patchlevel\Hydrator\Metadata\PropertyMetadata; use Patchlevel\Hydrator\Normalizer\ArrayNormalizer; use Patchlevel\Hydrator\Normalizer\ArrayShapeNormalizer; use Patchlevel\Hydrator\Normalizer\Normalizer; use Patchlevel\Hydrator\Normalizer\ObjectNormalizer; use Patchlevel\Hydrator\StackHydrator; -use ReflectionProperty; final readonly class StackHydratorFieldMappingResolver implements FieldMappingResolver { @@ -22,9 +22,11 @@ public function __construct( /** * @param class-string $className * + * @return array + * * @throws DocumentHasClassNormalizer */ - public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping + public function resolve(string $className): array { $metadata = $this->hydrator->metadata($className); @@ -32,9 +34,19 @@ public function resolve(string $className, ReflectionProperty $reflectionPropert throw new DocumentHasClassNormalizer($className, $metadata->normalizer::class); } - $property = $metadata->properties[$reflectionProperty->getName()]; + return $this->resolveProperties($metadata); + } + + /** @return array */ + private function resolveProperties(ClassMetadata $metadata): array + { + $fields = []; + + foreach ($metadata->properties as $property) { + $fields[$property->propertyName] = $this->resolvePropertyMetadata($property); + } - return $this->resolvePropertyMetadata($property); + return $fields; } private function resolvePropertyMetadata(PropertyMetadata $property): FieldMapping @@ -66,15 +78,10 @@ private function resolveNormalizer(string $fieldName, Normalizer $normalizer): F private function resolveObjectNormalizer(string $fieldName, ObjectNormalizer $objectNormalizer): FieldMapping { $metadata = $this->hydrator->metadata($objectNormalizer->className()); - $children = []; - - foreach ($metadata->properties as $property) { - $children[$property->propertyName] = $this->resolvePropertyMetadata($property); - } return new FieldMapping( $fieldName, - $children, + $this->resolveProperties($metadata), ); } diff --git a/tests/Unit/Fixtures/Circle.php b/tests/Unit/Fixtures/Circle.php new file mode 100644 index 0000000..40f161a --- /dev/null +++ b/tests/Unit/Fixtures/Circle.php @@ -0,0 +1,13 @@ + Circle::class, + 'square' => Square::class, +])] +abstract class Shape +{ + public function __construct( + #[Id] + private string $id, + ) { + } + + public function id(): string + { + return $this->id; + } +} diff --git a/tests/Unit/Fixtures/Square.php b/tests/Unit/Fixtures/Square.php new file mode 100644 index 0000000..3ea2a26 --- /dev/null +++ b/tests/Unit/Fixtures/Square.php @@ -0,0 +1,11 @@ + */ + public function resolve(string $className): array { - if ($reflectionProperty->getName() === 'status') { - return new FieldMapping('_newStatus', []); - } - - return null; + return ['status' => new FieldMapping('_newStatus', [])]; } }; @@ -190,13 +187,10 @@ className: Profile::class, $fieldResolver = new class implements FieldMappingResolver { - public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping|null + /** @return array */ + public function resolve(string $className): array { - if ($reflectionProperty->getName() === 'id') { - return new FieldMapping('_otherId', []); - } - - return null; + return ['id' => new FieldMapping('_otherId', [])]; } }; @@ -251,13 +245,10 @@ public function __construct( $fieldResolver = new class implements FieldMappingResolver { - public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping|null + /** @return array */ + public function resolve(string $className): array { - if ($reflectionProperty->getName() === 'version') { - return new FieldMapping('_version', []); - } - - return null; + return ['version' => new FieldMapping('_version', [])]; } }; @@ -321,4 +312,13 @@ class ('1') extends DocumentBase { $factory->metadata($document::class); } + + public function testMetadataOfAHierarchyWhereOnlyASubclassHasAClassNormalizer(): void + { + $factory = new AttributeDocumentMetadataFactory(new StackHydratorFieldMappingResolver(new StackHydrator())); + + $this->expectException(DocumentHasClassNormalizer::class); + + $factory->metadata(Shape::class); + } } diff --git a/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php b/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php index 7fac6cc..672a19e 100644 --- a/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php +++ b/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php @@ -20,7 +20,7 @@ use Patchlevel\ODM\Tests\Unit\Fixtures\Video; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\TestCase; -use ReflectionProperty; +use ReflectionClass; use function array_keys; @@ -75,15 +75,19 @@ public function testFieldsAreUnionedAcrossTheHierarchy(): void public function testConflictingFieldMappingAcrossSubclasses(): void { $resolver = new class implements FieldMappingResolver { - public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping + /** @return array */ + public function resolve(string $className): array { - $name = $reflectionProperty->getName(); + $fields = []; - if ($name === 'format' && $reflectionProperty->getDeclaringClass()->getShortName() === 'Video') { - return new FieldMapping('video_format'); + foreach ((new ReflectionClass($className))->getProperties() as $property) { + $name = $property->getName(); + $fields[$name] = new FieldMapping( + $name === 'format' && $className === Video::class ? 'video_format' : $name, + ); } - return new FieldMapping($name); + return $fields; } }; @@ -135,9 +139,16 @@ public function __construct( private function fieldResolver(): FieldMappingResolver { return new class implements FieldMappingResolver { - public function resolve(string $className, ReflectionProperty $reflectionProperty): FieldMapping + /** @return array */ + public function resolve(string $className): array { - return new FieldMapping($reflectionProperty->getName()); + $fields = []; + + foreach ((new ReflectionClass($className))->getProperties() as $property) { + $fields[$property->getName()] = new FieldMapping($property->getName()); + } + + return $fields; } }; } diff --git a/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php b/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php index d8c18da..4beea01 100644 --- a/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php +++ b/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php @@ -4,6 +4,7 @@ namespace Patchlevel\ODM\Tests\Unit\Metadata; +use Patchlevel\Hydrator\Attribute\Ignore; use Patchlevel\Hydrator\Guesser\BuiltInGuesser; use Patchlevel\Hydrator\Metadata\AttributeMetadataFactory; use Patchlevel\Hydrator\StackHydrator; @@ -12,12 +13,12 @@ use Patchlevel\ODM\Metadata\StackHydratorFieldMappingResolver; use Patchlevel\ODM\Tests\Unit\Fixtures\DocumentBase; use Patchlevel\ODM\Tests\Unit\Fixtures\NormalizedContract; +use Patchlevel\ODM\Tests\Unit\Fixtures\NormalizedDocumentBase; use Patchlevel\ODM\Tests\Unit\Fixtures\PersonalData; use Patchlevel\ODM\Tests\Unit\Fixtures\Profile; use Patchlevel\ODM\Tests\Unit\Fixtures\SkillNormalizer; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\TestCase; -use ReflectionProperty; use function sprintf; @@ -41,14 +42,14 @@ public function setUp(): void public function testResolvePropertyWithoutNormalizer(): void { - $mapping = $this->resolver->resolve(PersonalData::class, new ReflectionProperty(PersonalData::class, 'name')); + $mapping = $this->resolver->resolve(PersonalData::class)['name']; self::assertEquals(new FieldMapping('_name'), $mapping); } public function testResolvePropertyWithObjectNormalizer(): void { - $mapping = $this->resolver->resolve(Profile::class, new ReflectionProperty(Profile::class, 'personalData')); + $mapping = $this->resolver->resolve(Profile::class)['personalData']; self::assertEquals( new FieldMapping('_personal_data', [ @@ -61,7 +62,7 @@ public function testResolvePropertyWithObjectNormalizer(): void public function testResolvePropertyWithArrayOfObjectNormalizer(): void { - $mapping = $this->resolver->resolve(Profile::class, new ReflectionProperty(Profile::class, 'addresses')); + $mapping = $this->resolver->resolve(Profile::class)['addresses']; self::assertEquals( new FieldMapping('_addresses', [ @@ -74,7 +75,7 @@ public function testResolvePropertyWithArrayOfObjectNormalizer(): void public function testResolvePropertyWithCustomNormalizer(): void { - $mapping = $this->resolver->resolve(Profile::class, new ReflectionProperty(Profile::class, 'skills')); + $mapping = $this->resolver->resolve(Profile::class)['skills']; self::assertEquals( new FieldMapping('_skills'), @@ -84,7 +85,7 @@ public function testResolvePropertyWithCustomNormalizer(): void public function testResolvePropertyWithArrayShapeNormalizer(): void { - $mapping = $this->resolver->resolve(Profile::class, new ReflectionProperty(Profile::class, 'stats')); + $mapping = $this->resolver->resolve(Profile::class)['stats']; self::assertEquals( new FieldMapping('_stats', [ @@ -110,7 +111,7 @@ class ('1') extends DocumentBase { SkillNormalizer::class, )); - $this->resolver->resolve($document::class, new ReflectionProperty($document, 'id')); + $this->resolver->resolve($document::class); } public function testResolveFailsForADocumentWithANormalizerFromAnInterface(): void @@ -120,6 +121,28 @@ public function testResolveFailsForADocumentWithANormalizerFromAnInterface(): vo $this->expectException(DocumentHasClassNormalizer::class); - $this->resolver->resolve($document::class, new ReflectionProperty($document, 'id')); + $this->resolver->resolve($document::class); + } + + public function testResolveFailsForADocumentWithANormalizerFromAParentClass(): void + { + $document = new class ('1') extends NormalizedDocumentBase { + }; + + $this->expectException(DocumentHasClassNormalizer::class); + + $this->resolver->resolve($document::class); + } + + public function testResolveSkipsPropertiesTheHydratorDoesNotStore(): void + { + $document = new class ('1') extends DocumentBase { + public static string $registry = ''; + + #[Ignore] + public string $cache = ''; + }; + + self::assertEquals(['id' => new FieldMapping('id')], $this->resolver->resolve($document::class)); } } From a2ac25ee7b3458e4ec0407a6cc7ba2dfb6fa83c1 Mon Sep 17 00:00:00 2001 From: David Badura Date: Fri, 6 Nov 2026 18:11:41 +0100 Subject: [PATCH 3/4] Only map id and version where the resolver returns them The factory added an id and version mapping for every class of a hierarchy, even when the resolver did not return the property for that class. A resolver that cannot see a private id of the root from a subclass then produced a different id mapping for the subclass and a false DiscriminatorFieldConflict. The defaults are now only added once, after all classes are resolved. --- .../AttributeDocumentMetadataFactory.php | 17 ++++++++++------- .../DiscriminatorMetadataFactoryTest.php | 10 ++++++++++ 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/src/Metadata/AttributeDocumentMetadataFactory.php b/src/Metadata/AttributeDocumentMetadataFactory.php index 9c0f0d2..0a83a00 100644 --- a/src/Metadata/AttributeDocumentMetadataFactory.php +++ b/src/Metadata/AttributeDocumentMetadataFactory.php @@ -147,14 +147,11 @@ private function resolveFields( $fields = []; foreach ($classNames as $className) { - $mappings = $this->fieldResolver?->resolve($className) ?? []; - $mappings[$idProperty] = new FieldMapping('_id', [], ($mappings[$idProperty] ?? null)?->fieldName); - - if ($versionProperty !== null) { - $mappings[$versionProperty] ??= new FieldMapping($versionProperty); - } + foreach ($this->fieldResolver?->resolve($className) ?? [] as $name => $mapping) { + if ($name === $idProperty) { + $mapping = new FieldMapping('_id', [], $mapping->fieldName); + } - foreach ($mappings as $name => $mapping) { if (isset($fields[$name])) { if (!$this->fieldMappingEquals($fields[$name], $mapping)) { throw new DiscriminatorFieldConflict( @@ -172,6 +169,12 @@ private function resolveFields( } } + $fields[$idProperty] ??= new FieldMapping('_id'); + + if ($versionProperty !== null) { + $fields[$versionProperty] ??= new FieldMapping($versionProperty); + } + return $fields; } diff --git a/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php b/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php index 672a19e..01d7556 100644 --- a/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php +++ b/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php @@ -17,6 +17,7 @@ use Patchlevel\ODM\Tests\Unit\Fixtures\Address; use Patchlevel\ODM\Tests\Unit\Fixtures\Image; use Patchlevel\ODM\Tests\Unit\Fixtures\Media; +use Patchlevel\ODM\Tests\Unit\Fixtures\Shape; use Patchlevel\ODM\Tests\Unit\Fixtures\Video; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\TestCase; @@ -98,6 +99,15 @@ public function resolve(string $className): array $factory->metadata(Media::class); } + public function testAPrivateRootIdIsOnlyMappedWhereTheResolverSeesIt(): void + { + $factory = new AttributeDocumentMetadataFactory($this->fieldResolver()); + $metadata = $factory->metadata(Shape::class); + + self::assertEquals(new FieldMapping('_id', [], 'id'), $metadata->fields['id']); + self::assertEquals(new FieldMapping('radius'), $metadata->fields['radius']); + } + public function testMapEntryThatIsNotASubtype(): void { $class = new #[Document('things')] From f15d44c0aa36cc75da4ab92ee544c9f2e7ed4acc Mon Sep 17 00:00:00 2001 From: David Badura Date: Sat, 7 Nov 2026 12:29:10 +0100 Subject: [PATCH 4/4] Document the class normalizer check and the new FieldMappingResolver The upgrade guide gets both changes, field-mapping.md and inheritance.md say that a document can not have a class level normalizer. --- docs/UPGRADE-2.0.md | 60 +++++++++++++++++++++++++++++++++++++++++++ docs/field-mapping.md | 5 ++++ docs/inheritance.md | 2 ++ 3 files changed, 67 insertions(+) diff --git a/docs/UPGRADE-2.0.md b/docs/UPGRADE-2.0.md index fe787e7..fe202f6 100644 --- a/docs/UPGRADE-2.0.md +++ b/docs/UPGRADE-2.0.md @@ -74,6 +74,17 @@ final class SkillNormalizer implements Normalizer } } ``` +### Documents with a class level normalizer + +Hydrator 2 uses a normalizer on a class, on one of its parents or on an implemented interface for the whole +object, and a guesser that matches the class has the same effect. Documents are stored field by field, so a +document class must not end up with such a normalizer. The `StackHydratorFieldMappingResolver`, which the +repository managers' `create()` sets up, now throws `Patchlevel\ODM\Metadata\DocumentHasClassNormalizer` +when it builds the metadata of such a document. + +Remove the normalizer from the document class, its parents and its interfaces, and make sure no guesser +matches a document class. Put normalizers on the value objects inside the document instead. + ### Custom hydrators The repository managers and repositories now take a `Patchlevel\Hydrator\Hydrator` instead of a @@ -135,3 +146,52 @@ final class LoggingHydrator implements Hydrator `Patchlevel\ODM\Hydrator\DocumentHydrator` is internal now and no longer implements the `Hydrator` interface. Load and store documents through the repository instead of using it directly. + +## Field Mapping + +### FieldMappingResolver + +`FieldMappingResolver::resolve()` now works per class instead of per property. It receives a document class +and returns the field mappings of all its properties, keyed by property name. With inheritance it is called +for the root and for every class in the discriminator map. Properties you leave out are not mapped, except +the id and version properties, which always are. + +before: + +```php +use Patchlevel\ODM\Metadata\FieldMapping; +use Patchlevel\ODM\Metadata\FieldMappingResolver; + +final class PropertyNameFieldMappingResolver implements FieldMappingResolver +{ + public function resolve(ReflectionProperty $reflectionProperty): FieldMapping|null + { + return new FieldMapping($reflectionProperty->getName()); + } +} +``` +after: + +```php +use Patchlevel\ODM\Metadata\FieldMapping; +use Patchlevel\ODM\Metadata\FieldMappingResolver; + +final class PropertyNameFieldMappingResolver implements FieldMappingResolver +{ + /** + * @param class-string $className + * + * @return array + */ + public function resolve(string $className): array + { + $fields = []; + + foreach ((new ReflectionClass($className))->getProperties() as $property) { + $fields[$property->getName()] = new FieldMapping($property->getName()); + } + + return $fields; + } +} +``` diff --git a/docs/field-mapping.md b/docs/field-mapping.md index 098ae60..f71da09 100644 --- a/docs/field-mapping.md +++ b/docs/field-mapping.md @@ -145,6 +145,11 @@ final readonly class Skill } } ``` +A document itself must not end up with a normalizer, neither on its class, a parent or an interface it +implements, nor through a guesser, because documents are always stored field by field. The +`StackHydratorFieldMappingResolver`, which `create()` sets up, throws `DocumentHasClassNormalizer` when it +builds the metadata of such a document. + :::tip The hydrator ships normalizers for enums, dates and arrays out of the box. See the [hydrator documentation](https://patchlevel.dev/docs/hydrator/latest) for the full list. diff --git a/docs/inheritance.md b/docs/inheritance.md index 5ee562b..1293812 100644 --- a/docs/inheritance.md +++ b/docs/inheritance.md @@ -104,6 +104,8 @@ $images->insert(new Video('m-3', 'Clip', 30)); // throws WrongClass collection. Declare hierarchy-wide indexes there. * Discriminator values are stored in every document, so keep them short and never change one once data exists. +* No class in the hierarchy may have a class level normalizer, otherwise the metadata factory throws + `DocumentHasClassNormalizer`. :::warning The discriminator map is validated when the metadata is built. Mapping a value to a class that does