feat(attribute): allow multiple source/target, allow overriding attribute with priority system

docs/mapping/attributes.md

@@ -69,5 +69,32 @@ class EntityDto
 }
 ```
 
-> [!WARNING]
-> If multiple `#[MapTo]` and/or `#[MapFrom]` attributes target the same property an exception will be thrown.
+You can also pass an array to the `target` or `source` argument to specify configuration for multiple targets or sources.
+```php
+class EntityDto
+{
+    #[MapFrom(source: Entity::class, property: 'title')]
+    #[MapFrom(source: 'array', property: 'name')]
+    public string $name;
+
+    #[MapFrom(source: [Entity::class, 'array'], property: 'bar')]
+    public string $foo;
+}
+```
+
+In case there is multiple attributes that match the same target (not source), you can use the `priority` argument 
+to specify which one should be used first. The default priority is `0`.
+
+```php
+class Entity
+{
+    #[MapTo(ignore: true)]
+    public string $title;
+}
+
+class EntityDto
+{
+    #[MapFrom(source: Entity::class, ignore: false, priority: 10)]
+    public string $title;
+}
+```

src/Attribute/MapFrom.php

@@ -11,22 +11,23 @@
 final readonly class MapFrom
 {
     /**
-     * @param class-string|'array'|null                                 $source      The specific source class name or array. If null this attribute will be used for all source classes.
-     * @param string|null                                               $property    The source property name. If null, the target property name will be used.
-     * @param int|null                                                  $maxDepth    The maximum depth of the mapping. If null, the default max depth will be used.
-     * @param string|callable(mixed $value, object $object): mixed|null $transformer A transformer id or a callable that transform the value during mapping
-     * @param bool|null                                                 $ignore      if true, the property will be ignored during mapping
-     * @param string|null                                               $if          The condition to map the property, using the expression language
-     * @param string[]|null                                             $groups      The groups to map the property
+     * @param class-string<object>|'array'|array<class-string<object>|'array'>|null $source      The specific source class name or array. If null this attribute will be used for all source classes.
+     * @param string|null                                                           $property    The source property name. If null, the target property name will be used.
+     * @param int|null                                                              $maxDepth    The maximum depth of the mapping. If null, the default max depth will be used.
+     * @param string|callable(mixed $value, object $object): mixed|null             $transformer A transformer id or a callable that transform the value during mapping
+     * @param bool|null                                                             $ignore      if true, the property will be ignored during mapping
+     * @param string|null                                                           $if          The condition to map the property, using the expression language
+     * @param string[]|null                                                         $groups      The groups to map the property
      */
     public function __construct(
-        public ?string $source = null,
+        public string|array|null $source = null,
         public ?string $property = null,
         public ?int $maxDepth = null,
         public mixed $transformer = null,
         public ?bool $ignore = null,
         public ?string $if = null,
         public ?array $groups = null,
+        public int $priority = 0,
     ) {
     }
 }

src/Attribute/MapTo.php

@@ -11,22 +11,23 @@
 final readonly class MapTo
 {
     /**
-     * @param class-string|'array'|null                                 $target      The specific target class name or array. If null this attribute will be used for all target classes.
-     * @param string|null                                               $property    The target property name. If null, the source property name will be used.
-     * @param int|null                                                  $maxDepth    The maximum depth of the mapping. If null, the default max depth will be used.
-     * @param string|callable(mixed $value, object $object): mixed|null $transformer A transformer id or a callable that transform the value during mapping
-     * @param bool|null                                                 $ignore      if true, the property will be ignored during mapping
-     * @param string|null                                               $if          The condition to map the property, using the expression language
-     * @param string[]|null                                             $groups      The groups to map the property
+     * @param class-string<object>|'array'|array<class-string<object>|'array'>|null $target      The specific target class name or array. If null this attribute will be used for all target classes.
+     * @param string|null                                                           $property    The target property name. If null, the source property name will be used.
+     * @param int|null                                                              $maxDepth    The maximum depth of the mapping. If null, the default max depth will be used.
+     * @param string|callable(mixed $value, object $object): mixed|null             $transformer A transformer id or a callable that transform the value during mapping
+     * @param bool|null                                                             $ignore      if true, the property will be ignored during mapping
+     * @param string|null                                                           $if          The condition to map the property, using the expression language
+     * @param string[]|null                                                         $groups      The groups to map the property
      */
     public function __construct(
-        public ?string $target = null,
+        public string|array|null $target = null,
         public ?string $property = null,
         public ?int $maxDepth = null,
         public mixed $transformer = null,
         public ?bool $ignore = null,
         public ?string $if = null,
         public ?array $groups = null,
+        public int $priority = 0,
     ) {
     }
 }

src/Event/PropertyMetadataEvent.php

@@ -28,6 +28,7 @@ public function __construct(
         public ?string $if = null,
         public ?array $groups = null,
         public ?bool $disableGroupsCheck = null,
+        public int $priority = 0,
     ) {
     }
 }

src/EventListener/MapFromListener.php

@@ -62,7 +62,9 @@ public function __invoke(GenerateMapperEvent $event): void
 
     private function addPropertyFromTarget(GenerateMapperEvent $event, MapFrom $mapFrom, string $property): void
     {
-        if ($mapFrom->source !== null && $event->mapperMetadata->source !== $mapFrom->source) {
+        $sources = null === $mapFrom->source ? null : (\is_array($mapFrom->source) ? $mapFrom->source : [$mapFrom->source]);
+
+        if ($sources !== null && !\in_array($event->mapperMetadata->source, $sources, true)) {
             return;
         }
 
@@ -79,10 +81,11 @@ private function addPropertyFromTarget(GenerateMapperEvent $event, MapFrom $mapF
             ignoreReason: $mapFrom->ignore === true ? 'Property is ignored by MapFrom Attribute on Target' : null,
             if: $mapFrom->if,
             groups: $mapFrom->groups,
+            priority: $mapFrom->priority,
         );
 
-        if (\array_key_exists($property->target->property, $event->properties)) {
-            throw new BadMapDefinitionException(sprintf('There is already a MapTo or MapFrom attribute with target "%s" in class "%s" or class "%s".', $property->target->property, $event->mapperMetadata->source, $event->mapperMetadata->target));
+        if (\array_key_exists($property->target->property, $event->properties) && $event->properties[$property->target->property]->priority >= $property->priority) {
+            return;
         }
 
         $event->properties[$property->target->property] = $property;

src/EventListener/MapToListener.php

@@ -63,7 +63,9 @@ public function __invoke(GenerateMapperEvent $event): void
 
     private function addPropertyFromSource(GenerateMapperEvent $event, MapTo $mapTo, string $property): void
     {
-        if ($mapTo->target !== null && $event->mapperMetadata->target !== $mapTo->target) {
+        $targets = null === $mapTo->target ? null : (\is_array($mapTo->target) ? $mapTo->target : [$mapTo->target]);
+
+        if ($targets !== null && !\in_array($event->mapperMetadata->target, $targets, true)) {
             return;
         }
 
@@ -80,10 +82,11 @@ private function addPropertyFromSource(GenerateMapperEvent $event, MapTo $mapTo,
             ignoreReason: $mapTo->ignore === true ? 'Property is ignored by MapTo Attribute on Source' : null,
             if: $mapTo->if,
             groups: $mapTo->groups,
+            priority: $mapTo->priority,
         );
 
-        if (\array_key_exists($property->target->property, $event->properties)) {
-            throw new BadMapDefinitionException(sprintf('There is already a MapTo attribute with target "%s" in class "%s".', $property->target->property, $event->mapperMetadata->source));
+        if (\array_key_exists($property->target->property, $event->properties) && $event->properties[$property->target->property]->priority >= $property->priority) {
+            return;
         }
 
         $event->properties[$property->target->property] = $property;

tests/AutoMapperMapToTest.php

@@ -7,10 +7,10 @@
 use AutoMapper\Exception\BadMapDefinitionException;
 use AutoMapper\MapperContext;
 use AutoMapper\Symfony\ExpressionLanguageProvider;
-use AutoMapper\Tests\Fixtures\MapTo\BadMapTo;
 use AutoMapper\Tests\Fixtures\MapTo\BadMapToTransformer;
 use AutoMapper\Tests\Fixtures\MapTo\Bar;
 use AutoMapper\Tests\Fixtures\MapTo\FooMapTo;
+use AutoMapper\Tests\Fixtures\MapTo\PriorityMapTo;
 use AutoMapper\Tests\Fixtures\Transformer\CustomTransformer\FooDependency;
 use AutoMapper\Tests\Fixtures\Transformer\CustomTransformer\TransformerWithDependency;
 use Symfony\Component\DependencyInjection\ServiceLocator;
@@ -114,12 +114,14 @@ public function testMapFromArray()
         $this->assertSame('', $bar->getB());
     }
 
-    public function testBadDefinitionOnSameTargetProperty()
+    public function testPriority()
     {
-        $foo = new BadMapTo('foo');
+        $foo = new PriorityMapTo('foo');
 
-        $this->expectException(BadMapDefinitionException::class);
-        $this->autoMapper->map($foo, 'array');
+        $result = $this->autoMapper->map($foo, 'array');
+
+        self::assertArrayHasKey('foo', $result);
+        self::assertSame('foo', $result['foo']);
     }
 
     public function testBadDefinitionOnTransformer()

tests/Fixtures/MapTo/BadMapTo.php → tests/Fixtures/MapTo/PriorityMapTo.php

@@ -6,11 +6,11 @@
 
 use AutoMapper\Attribute\MapTo;
 
-class BadMapTo
+class PriorityMapTo
 {
     public function __construct(
-        #[MapTo('array', ignore: true)]
-        #[MapTo('array', ignore: false)]
+        #[MapTo('array', ignore: true, priority: 0)]
+        #[MapTo('array', ignore: false, priority: 10)]
         public string $foo
     ) {
     }