Add context attribute for properties

docs/hydrator.md

@@ -133,6 +133,42 @@ You can rename a property without a backwards compatibility break in your stored
 data by keeping the old serialized name with `NormalizedName`.
 :::
 
+## Context
+
+Both `extract` and `hydrate` accept a context array as last argument. It is
+passed to every normalizer and on to nested objects, so it can change how
+values are converted for a single call.
+
+```php
+use Patchlevel\Hydrator\Normalizer\DateTimeImmutableNormalizer;
+
+$data = $hydrator->extract($event, [DateTimeImmutableNormalizer::FORMAT => 'Y-m-d']);
+```
+With the `Context` attribute you can add context for a single property. It is
+merged into the context that is passed to the normalizer of this property, and
+on to nested objects if the property holds one. Values from the attribute win
+over the context of the call.
+
+```php
+use Patchlevel\Hydrator\Attribute\Context;
+use Patchlevel\Hydrator\Normalizer\DateTimeImmutableNormalizer;
+
+final class Profile
+{
+    #[Context([DateTimeImmutableNormalizer::FORMAT => 'Y-m-d'])]
+    public DateTimeImmutable $birthday;
+
+    public DateTimeImmutable $createdAt;
+}
+```
+The attribute can be used multiple times on the same property. The contexts
+are merged in the given order.
+
+:::note
+The context only reaches normalizers. Properties without a normalizer, like
+plain strings or integers, are copied as they are.
+:::
+
 ## Ignore properties
 
 Sometimes it is necessary to exclude properties. You can do that with the

docs/normalizer.md

@@ -109,10 +109,26 @@ final class Profile
 You can read about how the format is structured in the [php docs](https://www.php.net/manual/en/datetime.format.php).
 :::
 
+The format can also be changed through the [context](hydrator.md#context) with
+the `DateTimeImmutableNormalizer::FORMAT` key. It takes precedence over the
+format of the normalizer, for a single call or with the `Context` attribute for
+a single property.
+
+```php
+use Patchlevel\Hydrator\Attribute\Context;
+use Patchlevel\Hydrator\Normalizer\DateTimeImmutableNormalizer;
+
+final class Profile
+{
+    #[Context([DateTimeImmutableNormalizer::FORMAT => 'Y-m-d'])]
+    public DateTimeImmutable $birthday;
+}
+```
 ## DateTime
 
 The `DateTimeNormalizer` works exactly like the `DateTimeImmutableNormalizer`,
-only for `DateTime` objects. The default format is `DateTime::ATOM`.
+only for `DateTime` objects. The default format is `DateTime::ATOM`, and it
+reads the same context key, also available as `DateTimeNormalizer::FORMAT`.
 
 ```php
 use Patchlevel\Hydrator\Normalizer\DateTimeNormalizer;

src/Attribute/Context.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
+final class Context
+{
+    /** @param array<string, mixed> $context */
+    public function __construct(
+        public readonly array $context,
+    ) {
+    }
+}

src/Extension/Cryptography/CryptographyMiddleware.php

@@ -66,7 +66,10 @@
                     : $info->fallback;
 
                 if ($propertyMetadata->normalizer) {
-                    $fallback = $propertyMetadata->normalizer->normalize($fallback, $context);
+                    $fallback = $propertyMetadata->normalizer->normalize(
+                        $fallback,
+                        $propertyMetadata->context === [] ? $context : [...$context, ...$propertyMetadata->context],
+                    );
                 }
 
                 $data[$propertyMetadata->fieldName] = $fallback;
@@ -170,7 +173,10 @@
                 $subjectId = $property->getValue($data);
 
                 if ($property->normalizer) {
-                    $subjectId = $property->normalizer->normalize($subjectId, $context);
+                    $subjectId = $property->normalizer->normalize(
+                        $subjectId,
+                        $property->context === [] ? $context : [...$context, ...$property->context],
+                    );
                 }
             }
 

src/Metadata/AttributeMetadataFactory.php

@@ -4,6 +4,7 @@
 
 namespace Patchlevel\Hydrator\Metadata;
 
+use Patchlevel\Hydrator\Attribute\Context;
 use Patchlevel\Hydrator\Attribute\Ignore;
 use Patchlevel\Hydrator\Attribute\Lazy;
 use Patchlevel\Hydrator\Attribute\NormalizedName;
@@ -131,6 +132,7 @@
                 $type,
                 $fieldName,
                 $this->getNormalizer($reflectionProperty, $type),
+                context: $this->getContext($reflectionProperty),
             );
         }
 
@@ -160,6 +162,18 @@
         return $attributeReflectionList[0]->newInstance()->name();
     }
 
+    /** @return array<string, mixed> */
+    private function getContext(ReflectionProperty $reflectionProperty): array
+    {
+        $context = [];
+
+        foreach ($reflectionProperty->getAttributes(Context::class) as $attributeReflection) {
+            $context = [...$context, ...$attributeReflection->newInstance()->context];
+        }
+
+        return $context;
+    }
+
     private function hasIgnore(ReflectionProperty $reflectionProperty): bool
     {
         return $reflectionProperty->getAttributes(Ignore::class) !== [];

src/Metadata/PropertyMetadata.php

@@ -16,19 +16,24 @@
  *     fieldName: string,
  *     normalizer: Normalizer|null,
  *     extras: array<string, mixed>,
+ *     context?: array<string, mixed>,
  * }
  */
 final class PropertyMetadata
 {
     public readonly string $propertyName;
 
-    /** @param array<string, mixed> $extras */
+    /**
+     * @param array<string, mixed> $extras
+     * @param array<string, mixed> $context merged into the context passed to the normalizer
+     */
     public function __construct(
         public readonly ReflectionProperty $reflection,
         public readonly Type $type,
         public string $fieldName,
         public Normalizer|null $normalizer = null,
         public array $extras = [],
+        public array $context = [],
     ) {
         $this->propertyName = $reflection->getName();
     }
@@ -53,6 +58,7 @@ public function __serialize(): array
             'fieldName' => $this->fieldName,
             'normalizer' => $this->normalizer,
             'extras' => $this->extras,
+            'context' => $this->context,
         ];
     }
 
@@ -65,5 +71,7 @@ public function __unserialize(array $data): void
         $this->fieldName = $data['fieldName'];
         $this->normalizer = $data['normalizer'];
         $this->extras = $data['extras'];
+        // metadata cached by an older version has no context
+        $this->context = $data['context'] ?? [];
     }
 }

src/Middleware/TransformMiddleware.php

@@ -61,7 +61,14 @@
             if ($propertyMetadata->normalizer) {
                 try {
                     /** @psalm-suppress MixedAssignment */
-                    $value = $propertyMetadata->normalizer->denormalize($data[$propertyMetadata->fieldName], $context);
+                    $value = $propertyMetadata->normalizer->denormalize(
+                        $data[$propertyMetadata->fieldName],
+                        match (true) {
+                            $propertyMetadata->context === [] => $context,
+                            $context === [] => $propertyMetadata->context,
+                            default => [...$context, ...$propertyMetadata->context],
+                        },
+                    );
                 } catch (Throwable $e) {
                     throw new DenormalizationFailure(
                         $metadata->className,
@@ -106,7 +113,7 @@
 
         $this->callStack[$objectId] = $object::class;
 
         try {
             $data = [];
 
             foreach ($metadata->properties as $propertyMetadata) {
@@ -115,7 +122,11 @@
                         /** @psalm-suppress MixedAssignment */
                         $data[$propertyMetadata->fieldName] = $propertyMetadata->normalizer->normalize(
                             $propertyMetadata->getValue($object),
-                            $context,
+                            match (true) {
+                                $propertyMetadata->context === [] => $context,
+                                $context === [] => $propertyMetadata->context,
+                                default => [...$context, ...$propertyMetadata->context],
+                            },
                         );
                     } catch (CircularReference $e) {
                         throw $e;

src/Normalizer/DateTimeImmutableNormalizer.php

@@ -12,6 +12,9 @@
 #[Attribute(Attribute::TARGET_PROPERTY)]
 final readonly class DateTimeImmutableNormalizer implements Normalizer
 {
+    /** Context key to override the format, e.g. with the Context attribute. */
+    public const FORMAT = 'datetime_format';
+
     public function __construct(
         private string $format = DateTimeImmutable::ATOM,
     ) {
@@ -28,7 +31,7 @@ public function normalize(mixed $value, array $context): string|null
             throw InvalidArgument::withWrongType('DateTimeImmutable|null', $value);
         }
 
-        return $value->format($this->format);
+        return $value->format($this->format($context));
     }
 
     /** @param array<string, mixed> $context */
@@ -42,12 +45,20 @@ public function denormalize(mixed $value, array $context): DateTimeImmutable|nul
             throw InvalidArgument::withWrongType('string|null', $value);
         }
 
-        $date = DateTimeImmutable::createFromFormat($this->format, $value);
+        $date = DateTimeImmutable::createFromFormat($this->format($context), $value);
 
         if ($date === false) {
             throw new InvalidArgument();
         }
 
         return $date;
     }
+
+    /** @param array<string, mixed> $context */
+    private function format(array $context): string
+    {
+        $format = $context[self::FORMAT] ?? null;
+
+        return is_string($format) ? $format : $this->format;
+    }
 }

src/Normalizer/DateTimeNormalizer.php

@@ -12,6 +12,9 @@
 #[Attribute(Attribute::TARGET_PROPERTY)]
 final readonly class DateTimeNormalizer implements Normalizer
 {
+    /** Context key to override the format, e.g. with the Context attribute. */
+    public const FORMAT = 'datetime_format';
+
     public function __construct(
         private string $format = DateTime::ATOM,
     ) {
@@ -28,7 +31,7 @@ public function normalize(mixed $value, array $context): string|null
             throw InvalidArgument::withWrongType('DateTime|null', $value);
         }
 
-        return $value->format($this->format);
+        return $value->format($this->format($context));
     }
 
     /** @param array<string, mixed> $context */
@@ -42,12 +45,20 @@ public function denormalize(mixed $value, array $context): DateTime|null
             throw InvalidArgument::withWrongType('string|null', $value);
         }
 
-        $date = DateTime::createFromFormat($this->format, $value);
+        $date = DateTime::createFromFormat($this->format($context), $value);
 
         if ($date === false) {
             throw new InvalidArgument();
         }
 
         return $date;
     }
+
+    /** @param array<string, mixed> $context */
+    private function format(array $context): string
+    {
+        $format = $context[self::FORMAT] ?? null;
+
+        return is_string($format) ? $format : $this->format;
+    }
 }

tests/Unit/Extension/Cryptography/CryptographyMiddlewareTest.php

@@ -20,6 +20,7 @@
 use Patchlevel\Hydrator\Middleware\TransformMiddleware;
 use Patchlevel\Hydrator\Tests\Unit\Extension\Cryptography\Fixture\SensitiveDataProfileCreated;
 use Patchlevel\Hydrator\Tests\Unit\Extension\Cryptography\Fixture\SensitiveDataProfileCreatedFallbackCallback;
+use Patchlevel\Hydrator\Tests\Unit\Extension\Cryptography\Fixture\SensitiveDataWithContextDto;
 use Patchlevel\Hydrator\Tests\Unit\Fixture\Email;
 use Patchlevel\Hydrator\Tests\Unit\Fixture\ProfileCreated;
 use Patchlevel\Hydrator\Tests\Unit\Fixture\ProfileId;
@@ -223,6 +224,46 @@ public function testDecryptWithFallbackCallback(): void
         self::assertEquals(new Email('foo@example.com'), $result->email);
     }
 
+    public function testFallbackUsesPropertyContext(): void
+    {
+        $cryptographer = $this->createMock(Cryptographer::class);
+        $cryptographer->method('supports')->willReturn(true);
+        $cryptographer->method('decrypt')->willThrowException(DecryptionFailed::forMethod('aes-256-gcm'));
+
+        $middleware = new CryptographyMiddleware($cryptographer);
+
+        $result = $middleware->hydrate(
+            $this->metadata(SensitiveDataWithContextDto::class),
+            ['id' => 'foo', 'email' => 'encrypted'],
+            [],
+            new Stack([new TransformMiddleware()]),
+        );
+
+        self::assertInstanceOf(SensitiveDataWithContextDto::class, $result);
+        self::assertSame('p-fallback-s', $result->email);
+    }
+
+    public function testSubjectIdUsesPropertyContext(): void
+    {
+        $cryptographer = $this->createMock(Cryptographer::class);
+        $cryptographer
+            ->expects($this->once())
+            ->method('encrypt')
+            ->with('id-foo', 'p-info@patchlevel.de')
+            ->willReturn('encrypted');
+
+        $middleware = new CryptographyMiddleware($cryptographer);
+
+        $result = $middleware->extract(
+            $this->metadata(SensitiveDataWithContextDto::class),
+            new SensitiveDataWithContextDto('foo', 'info@patchlevel.de'),
+            [],
+            new Stack([new TransformMiddleware()]),
+        );
+
+        self::assertSame(['id' => 'id-foo', 'email' => 'encrypted'], $result);
+    }
+
     public function testDecrypt(): void
     {
         $cryptographer = $this->createMock(Cryptographer::class);

tests/Unit/Extension/Cryptography/Fixture/SensitiveDataWithContextDto.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Hydrator\Tests\Unit\Extension\Cryptography\Fixture;
+
+use Patchlevel\Hydrator\Attribute\Context;
+use Patchlevel\Hydrator\Extension\Cryptography\Attribute\DataSubjectId;
+use Patchlevel\Hydrator\Extension\Cryptography\Attribute\SensitiveData;
+use Patchlevel\Hydrator\Tests\Unit\Fixture\ContextAwareNormalizer;
+
+final class SensitiveDataWithContextDto
+{
+    public function __construct(
+        #[ContextAwareNormalizer]
+        #[Context(['prefix' => 'id-'])]
+        #[DataSubjectId]
+        public string $id,
+        #[ContextAwareNormalizer]
+        #[Context(['prefix' => 'p-', 'suffix' => '-s'])]
+        #[SensitiveData(fallback: 'fallback')]
+        public string $email,
+    ) {
+    }
+}