Introduce scenarios to allow multiple normalized representations of the data. (#19)

* Feature: Introduce scenarios to allow multiple normalized representations of the model data.

Author: zolex

docs/VOM.md

@@ -1282,6 +1282,195 @@ class RegexpExtractorProperty
 $model = $objectMapper->denormalize('image1.jpg,tag:foobar,visibility:hidden', RegexpExtractorProperty::class);
 ```
 
+## Scenarios
+
+If there is more than one representation of your normalized data, the `scenario` argument allows to switch between different mappings.
+
+```php
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class ModelWithScenarios
+{
+    #[VOM\Property]
+    #[VOM\Property('[FIRST_NAME]', scenario: 'second')]
+    #[VOM\Property('[name][first]'), scenario: 'third'])]
+    public string $firstName;
+    
+    #[VOM\Property]
+    #[VOM\Property('[LAST_NAME]', scenario: 'second')]
+    #[VOM\Property('[name][last]'), scenario: 'third'])]
+    public string $lastName;
+}
+```
+
+The scenario can be passed in the context of the `serialize`, `deserialize`, `normalize` and `denormalize` methods of the ObjectMapper.
+
+```php
+$data = [
+    'firstName' => 'Peter',
+    'lastName' => 'Parker'
+];
+$objectMapper->denormalize($data, ModelWithScenarios::class);
+
+$data = [
+    'FIRST_NAME' => 'Peter',
+    'LAST_NAME' => 'Parker'
+];
+$objectMapper->denormalize($data, ModelWithScenarios::class, null, ['scenario' => 'second']);
+
+$data = [
+    'name' => [
+        'first' => 'Peter',
+        'last' => 'Parker'
+    ]
+];
+$objectMapper->denormalize($data, ModelWithScenarios::class, null, ['scenario' => 'third']);
+```
+
+The `scenario` argument can also be used on the arguments of constructors, factories and denormalizers as well as on normalizer methods.
+
+**Constructor Scenarios**
+
+```php
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class ModelWithScenarios
+{
+    public function __construct(
+      #[VOM\Argument]
+      #[VOM\Argument('[FIRST_NAME]', scenario: 'second')]
+      string $firstName,
+      
+      #[VOM\Argument]
+      #[VOM\Argument('[LAST_NAME]', scenario: 'second')]
+      string $lastName,
+    ) {
+        // ...
+    }
+}
+```
+
+**Factory Scenarios**
+
+```php
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class ModelWithScenarios
+{
+    #[VOM\Factory]
+    public function create(
+      #[VOM\Argument]
+      #[VOM\Argument('[FIRST_NAME]', scenario: 'second')]
+      string $firstName,
+      
+      #[VOM\Argument]
+      #[VOM\Argument('[LAST_NAME]', scenario: 'second')]
+      string $lastName,
+    ): self {
+        // ...
+    }
+}
+```
+
+**Denormalizer Scenarios**
+
+```php
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class ModelWithScenarios
+{
+    #[VOM\Denormalizer]
+    public function denormalizeValues(
+      #[VOM\Argument]
+      #[VOM\Argument('[FIRST_NAME]', scenario: 'second')]
+      string $firstName,
+      
+      #[VOM\Argument]
+      #[VOM\Argument('[LAST_NAME]', scenario: 'second')]
+      string $lastName,
+    ) {
+        // ...
+    }
+}
+```
+
+**Normalizer Scenarios**
+
+```php
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class ModelWithScenarios
+{
+    private string $firstName = 'Peter';
+    private string $lastName = 'Parker';
+
+    #[VOM\Normalizer(accessor: '[firstName]')]
+    public function normalizeFirstNameForDefaultScenario(): string {
+        return $this->firstName;
+    }
+    
+    #[VOM\Normalizer(accessor: '[FIRST_NAME]', scenario: 'second')]
+    public function normalizeFirstNameForSecondScenario(): string {
+        return strtoupper($this->firstName);
+    }
+    
+    #[VOM\Normalizer(accessor: '[lastName]')]
+    public function normalizeLastNameForDefaultScenario(): string {
+        return return $this->lastName;
+    }
+    
+    #[VOM\Normalizer(accessor: '[LAST_NAME]', scenario: 'second')]
+    public function normalizeFirstNameForSecondScenario(): string {
+        return strtoupper($this->lastName);
+    }
+}
+```
+
+> [!NOTE]
+> For fine-grained control, scenarios can also be combined with the `Groups` feature.
+
+```php
+use \Symfony\Component\Serializer\Attribute\Groups;
+use Zolex\VOM\Mapping as VOM;
+
+#[VOM\Model]
+class ModelWithScenarios
+{
+    private string $firstName = 'Peter';
+    private string $lastName = 'Parker';
+
+    #[Groups('firstname')]
+    #[VOM\Normalizer(accessor: '[firstName]')]
+    public function getFirstNameForDefaultScenario(): string {
+        return $this->firstName;
+    }
+    
+    #[Groups('firstname')]
+    #[VOM\Normalizer(accessor: '[FIRST_NAME]', scenario: 'second')]
+    public function getFirstNameForSecondScenario(): string {
+        return strtoupper($this->firstName);
+    }
+    
+    #[Groups('lastname')]
+    #[VOM\Normalizer(accessor: '[lastName]')]
+    public function getLastNameForDefaultScenario(): string {
+        return return $this->lastName;
+    }
+    
+    #[Groups('lastname')]
+    #[VOM\Normalizer(accessor: '[LAST_NAME]', scenario: 'second')]
+    public function getFirstNameForSecondScenario(): string {
+       return strtoupper($this->lastName);
+    }
+}
+``` 
+
+
 ## Interfaces and Abstract Classes
 
 When dealing with objects that are fairly similar or share properties, you can use interfaces or abstract classes.

src/Mapping/AbstractProperty.php

@@ -13,6 +13,8 @@
 
 namespace Zolex\VOM\Mapping;
 
+use Zolex\VOM\Metadata\ModelMetadata;
+
 abstract class AbstractProperty
 {
     public function __construct(
@@ -27,6 +29,7 @@ public function __construct(
         private ?array $map = null,
         private bool $serialized = false,
         private ?string $extractor = null,
+        private ?string $scenario = ModelMetadata::DEFAULT_SCENARIO,
     ) {
     }
 
@@ -99,4 +102,9 @@ public function getExtractor(): ?string
     {
         return $this->extractor;
     }
+
+    public function getScenario(): string
+    {
+        return $this->scenario;
+    }
 }

src/Mapping/Argument.php

@@ -22,7 +22,7 @@
  *
  * {@see ModelMetadataFactory::createPropertyMetadata()}
  */
-#[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::TARGET_PROPERTY)]
+#[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::TARGET_PROPERTY | \Attribute::IS_REPEATABLE)]
 final class Argument extends AbstractProperty
 {
 }

src/Mapping/Denormalizer.php

@@ -16,12 +16,19 @@
 #[\Attribute(\Attribute::TARGET_METHOD)]
 final class Denormalizer
 {
-    public function __construct(private readonly bool $allowNonScalarArguments = false)
-    {
+    public function __construct(
+        private readonly bool $allowNonScalarArguments = false,
+        private readonly ?string $scenario = null,
+    ) {
     }
 
     public function allowNonScalarArguments(): bool
     {
         return $this->allowNonScalarArguments;
     }
+
+    public function getScenario(): ?string
+    {
+        return $this->scenario;
+    }
 }

src/Mapping/Factory.php

@@ -16,12 +16,19 @@
 #[\Attribute(\Attribute::TARGET_METHOD)]
 final class Factory
 {
-    public function __construct(private readonly int $priority = 0)
-    {
+    public function __construct(
+        private readonly int $priority = 0,
+        private readonly ?string $scenario = null,
+    ) {
     }
 
     public function getPriority(): int
     {
         return $this->priority;
     }
+
+    public function getScenario(): ?string
+    {
+        return $this->scenario;
+    }
 }

src/Mapping/Normalizer.php

@@ -16,12 +16,19 @@
 #[\Attribute(\Attribute::TARGET_METHOD)]
 final class Normalizer
 {
-    public function __construct(private readonly ?string $accessor = null)
-    {
+    public function __construct(
+        private readonly ?string $accessor = null,
+        private readonly ?string $scenario = null,
+    ) {
     }
 
     public function getAccessor(): ?string
     {
         return $this->accessor;
     }
+
+    public function getScenario(): ?string
+    {
+        return $this->scenario;
+    }
 }

src/Mapping/Property.php

@@ -13,7 +13,7 @@
 
 namespace Zolex\VOM\Mapping;
 
-#[\Attribute(\Attribute::TARGET_PROPERTY)]
+#[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::IS_REPEATABLE)]
 final class Property extends AbstractProperty
 {
 }

src/Metadata/AbstractCallableMetadata.php

@@ -43,8 +43,8 @@ public function getLongMethodName(): string
         return \sprintf('%s::%s()', $this->class, $this->method);
     }
 
-    public function getArguments(): array
+    public function getArguments(string $scenario = ModelMetadata::DEFAULT_SCENARIO): array
     {
-        return $this->arguments;
+        return $this->arguments[$scenario] ?? [];
     }
 }