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 diff --git a/src/Metadata/AttributeDocumentMetadataFactory.php b/src/Metadata/AttributeDocumentMetadataFactory.php index 7635496..0a83a00 100644 --- a/src/Metadata/AttributeDocumentMetadataFactory.php +++ b/src/Metadata/AttributeDocumentMetadataFactory.php @@ -147,20 +147,9 @@ private function resolveFields( $fields = []; foreach ($classNames as $className) { - $reflection = new ReflectionClass($className); - - foreach ($reflection->getProperties() as $reflectionProperty) { - $name = $reflectionProperty->getName(); - $field = $this->fieldResolver?->resolve($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; + foreach ($this->fieldResolver?->resolve($className) ?? [] as $name => $mapping) { + if ($name === $idProperty) { + $mapping = new FieldMapping('_id', [], $mapping->fieldName); } if (isset($fields[$name])) { @@ -180,6 +169,12 @@ private function resolveFields( } } + $fields[$idProperty] ??= new FieldMapping('_id'); + + if ($versionProperty !== null) { + $fields[$versionProperty] ??= new FieldMapping($versionProperty); + } + return $fields; } 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..4df00d9 100644 --- a/src/Metadata/FieldMappingResolver.php +++ b/src/Metadata/FieldMappingResolver.php @@ -4,9 +4,12 @@ namespace Patchlevel\ODM\Metadata; -use ReflectionProperty; - interface FieldMappingResolver { - public function resolve(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 74ef1df..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 { @@ -19,12 +19,34 @@ public function __construct( ) { } - public function resolve(ReflectionProperty $reflectionProperty): FieldMapping + /** + * @param class-string $className + * + * @return array + * + * @throws DocumentHasClassNormalizer + */ + public function resolve(string $className): array { - $metadata = $this->hydrator->metadata($reflectionProperty->getDeclaringClass()->getName()); - $property = $metadata->properties[$reflectionProperty->getName()]; + $metadata = $this->hydrator->metadata($className); - return $this->resolvePropertyMetadata($property); + if ($metadata->normalizer !== null) { + throw new DocumentHasClassNormalizer($className, $metadata->normalizer::class); + } + + 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 $fields; } private function resolvePropertyMetadata(PropertyMetadata $property): FieldMapping @@ -56,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', [])]; } }; @@ -185,13 +187,10 @@ className: Profile::class, $fieldResolver = new class implements FieldMappingResolver { - public function resolve(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', [])]; } }; @@ -246,13 +245,10 @@ public function __construct( $fieldResolver = new class implements FieldMappingResolver { - public function resolve(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', [])]; } }; @@ -302,4 +298,27 @@ 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); + } + + 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 1f8f9bc..01d7556 100644 --- a/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php +++ b/tests/Unit/Metadata/DiscriminatorMetadataFactoryTest.php @@ -17,10 +17,11 @@ 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; -use ReflectionProperty; +use ReflectionClass; use function array_keys; @@ -75,15 +76,19 @@ public function testFieldsAreUnionedAcrossTheHierarchy(): void public function testConflictingFieldMappingAcrossSubclasses(): void { $resolver = new class implements FieldMappingResolver { - public function resolve(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; } }; @@ -94,6 +99,15 @@ public function resolve(ReflectionProperty $reflectionProperty): FieldMapping $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')] @@ -135,9 +149,16 @@ public function __construct( private function fieldResolver(): FieldMappingResolver { return new class implements FieldMappingResolver { - public function resolve(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 3eb12a4..4beea01 100644 --- a/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php +++ b/tests/Unit/Metadata/StackHydratorFieldMappingResolverTest.php @@ -4,18 +4,26 @@ 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; +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\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; #[CoversClass(StackHydratorFieldMappingResolver::class)] +#[CoversClass(DocumentHasClassNormalizer::class)] final class StackHydratorFieldMappingResolverTest extends TestCase { private StackHydratorFieldMappingResolver $resolver; @@ -34,14 +42,14 @@ public function setUp(): void public function testResolvePropertyWithoutNormalizer(): void { - $mapping = $this->resolver->resolve(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(new ReflectionProperty(Profile::class, 'personalData')); + $mapping = $this->resolver->resolve(Profile::class)['personalData']; self::assertEquals( new FieldMapping('_personal_data', [ @@ -54,7 +62,7 @@ public function testResolvePropertyWithObjectNormalizer(): void public function testResolvePropertyWithArrayOfObjectNormalizer(): void { - $mapping = $this->resolver->resolve(new ReflectionProperty(Profile::class, 'addresses')); + $mapping = $this->resolver->resolve(Profile::class)['addresses']; self::assertEquals( new FieldMapping('_addresses', [ @@ -67,7 +75,7 @@ public function testResolvePropertyWithArrayOfObjectNormalizer(): void public function testResolvePropertyWithCustomNormalizer(): void { - $mapping = $this->resolver->resolve(new ReflectionProperty(Profile::class, 'skills')); + $mapping = $this->resolver->resolve(Profile::class)['skills']; self::assertEquals( new FieldMapping('_skills'), @@ -77,7 +85,7 @@ public function testResolvePropertyWithCustomNormalizer(): void public function testResolvePropertyWithArrayShapeNormalizer(): void { - $mapping = $this->resolver->resolve(new ReflectionProperty(Profile::class, 'stats')); + $mapping = $this->resolver->resolve(Profile::class)['stats']; self::assertEquals( new FieldMapping('_stats', [ @@ -89,4 +97,52 @@ 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); + } + + public function testResolveFailsForADocumentWithANormalizerFromAnInterface(): void + { + $document = new class ('1') extends DocumentBase implements NormalizedContract { + }; + + $this->expectException(DocumentHasClassNormalizer::class); + + $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)); + } }