Why ?

In the train back from API Platform Con and after watching @weaverryan conference about API Platform's feature that helps separating Doctrine Entities from POPOs, we had the feeling that such a component is definitely missing from the Symfony ecosystem. Current implementations (automapper-plus, janephp/automapper) are good but feel to complicated when you want something accessible (DX and complexity). Here we're not trying to have exceptional performance, we just want an accessible API with few mandatory features. Basically those are:

• map properties from a class/object to another class/object (Map(target: A::class))
• configure the property name each property is mapped to (Map(target: 'prop'))
• change the value during transformation (Map(transform: 'ucfirst'))
• control whether the value should be mapped or not (Map(if: 'boolval'))
• reuse objects if possible (works better with doctrine UOW)

Other implementation details:

• if a property exists in B, it'll "automatically" be mapped (doesn't handle type errors, should we ?)
• if a property doesn't exists in B it'll "automatically" not be mapped

The rest is not "auto".

Mapper Component

The Mapper component allows you to map an object to another object,
facilitating the mapping using attributes.

Usage

use Symfony\Component\ObjectMapper\ObjectMapper;
use Symfony\Component\ObjectMapper\Attributes\Map;

// This maps class `A` to class `B`.
#[Map(B::class)]
class A
{
    // This maps A::foo to B::bar.
    #[Map(target: 'bar')]
    public string $foo;

    // This calls ucfirst on A::transform
    #[Map(transform: 'ucfirst')]
    public string $name;

    // This doesn't map A::bar if it's value is falsy.
    #[Map(if: 'boolval')]
    public bool $bar = false;
}

$mapper = new ObjectMapper();
$mapper->map(new A);

The Map attribute has the following signature:

#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
final class Map
{
    /**
     *
     * @param null|string|class-string                                  $source     The property or the class to map to
     * @param null|string|class-string                                  $target     The property or the class to map from
     * @param string|callable(mixed $value, object $object): bool       $if         A Symfony service name or a callable that instructs whether to map
     * @param CallableType|CallableType[]                               $transform  A Symfony service name or a callable that transform the value during mapping
     */
    public function __construct(
        public readonly ?string $source = null,
        public readonly ?string $target = null,
        public readonly mixed $if = null,
        public readonly mixed $transform = null
    ){
    }
}

if and transform are callable or Symfony services, not that we need to introduce an interface for services to implement, this will follow if we want to introduce the component inside the Framework Bundle.

The mapper also takes a $source argument if one needs to update an object instead of creating a new one:

$b = new B;
$mapper = new ObjectMapper();
$mapper->map(new A, $b);

TODO

• AutoMapper or Automapper or something else? ObjectMapper
• max depth? Supports recursivity, maxDepth is for serializers.