AutoMapper for PHP

AutoMapper operates on two primary concepts:

• Source: The existing object or data structure you want to extract information from.
• Target: The destination object or data structure where the information will be mapped.

Understanding these roles is fundamental to all mapping operations, including object-to-object mapping, normalization, and denormalization.

When upgrading to version 10.0, the specialized interfaces CustomPropertyTransformerInterface and CustomModelTransformerInterface have been removed. They are replaced by a single, unified PropertyTransformerInterface that handles both property and model transformations.

If you have custom transformers, you must refactor them to implement PropertyTransformerInterface.

You can define explicit mappings between source and target objects using #[MapTo] and #[MapFrom] attributes.

• #[MapTo] is applied to a property of the source object to specify where its value should go.
• #[MapFrom] is applied to a property of the target object to specify where its value should come from.

These attributes can be applied to:

• Public or private properties (including promoted properties).
• Public or private methods (used as setters/getters).
• Classes (to define virtual properties).

class Entity
{
    #[MapTo(property: 'name')]
    public string $title;
}

class EntityDto
{
    private string $name;

    #[MapFrom(property: 'title')]
    public function setName($name): void
    {
        $this->name = $name;
    }
}

When a property uses both the Symfony Serializer #[Groups] attribute and the groups argument from #[MapTo] or #[MapFrom], the groups defined in #[MapTo] or #[MapFrom] take precedence and will override the #[Groups] attribute. The property will only be mapped if the context contains a group specified in the #[MapTo] or #[MapFrom] argument.

use Symfony\Component\Serializer\Attribute\Groups;

class Source
{
    #[Groups(['group1', 'group2'])]
    #[MapTo(target: 'array', groups: ['group3'])]
    public $groupedProperty;
}
// In this case, the property is only mapped if the context contains 'group3'.

When the Symfony Serializer component is available, AutoMapper respects the #[Groups] attribute to control which properties are included in the mapping process.

Warning: If both the target and source objects have groups defined, a property is only mapped if the mapping context contains at least one group from the target object AND at least one group from the source object.

use Symfony\Component\Serializer\Attribute\Groups;

class Source
{
    #[Groups(['group1', 'group2'])]
    public $groupedProperty;
}

Allowed attributes let you define a specific subset of properties to be mapped. Unlike groups, these are checked against the property names of the source object. You can also use nested arrays to restrict mapping for nested objects.

WARNING

The mapper only checks allowed attributes from the property name of the source object, not the target object.

// Map only the 'id' property
$target = $autoMapper->map($source, UserDTO::class, [
    'allowed_attributes' => ['id']
]);

// Map only the 'city' property of a nested 'address' object
$target = $autoMapper->map($source, UserDTO::class, [
    'allowed_attributes' => ['address' => ['city']]
]);

When mapping data to an existing object that contains collections (e.g., a User with multiple Address objects), AutoMapper can reuse existing objects within those collections instead of always instantiating new ones. This prevents duplicate entries in databases or ORM exceptions when dealing with existing entities.

To enable this, AutoMapper uses the concept of an Identifier. When mapping a collection, AutoMapper checks the destination collection for objects with matching identifiers. If a match is found, the existing object is updated; otherwise, a new object is created and added to the collection.

// Fetch existing object from database
$user = $this->entityManager->find(User::class, $id);

// Map data to the existing object
// AutoMapper will use identifiers to manage nested collections
$mapper->map($requestValue, $user);

AutoMapper automatically tracks mapped objects to prevent infinite loops and preserve circular references in the target. However, you can control this behavior using the following options:

• circular_reference_limit: Set to 0 to break the reference and throw a CircularReferenceException.
• circular_reference_handler: Provide a callback function function ($source, $context) to return a custom value (e.g., null) when a circular reference is detected.

// Break circular reference by throwing exception
$target = $autoMapper->map($source, UserDTO::class, ['circular_reference_limit' => 0]);

// Handle circular reference with a callback
$target = $autoMapper->map($source, UserDTO::class, [
    'circular_reference_handler' => function ($source, $context) {
        return null;
    }
]);

To prevent overwriting existing values in a target object when the source value is empty, use these options:

• skip_null_values: If true, properties with null in the source will not be mapped, preserving the target's current value.
• skip_uninitialized_values: If true, properties that have not been initialized in the source will not be mapped.

// Skip nulls
$target = $autoMapper->map($source, $target, ['skip_null_values' => true]);

// Skip uninitialized properties
$target = $autoMapper->map($source, $target, ['skip_uninitialized_values' => true]);