Introducing Symfony Object Mapper: Clean and Explicit Object Mapping in Modern PHP

Modern software engineering is experiencing a strong maturation phase within the PHP ecosystem, driven by increasing demands for scalability, architectural clarity, and developer productivity. In this context, the release of the Symfony Object Mapper in 2025 represents an important step forward in the evolution of tools that help developers build more cohesive, explicit, and well-designed applications.

The Object Mapper emerges as a new component in the Symfony ecosystem with the goal of solving a classic problem: transforming data between domain objects and other representations, such as arrays, DTOs, or transport structures. Unlike ORMs, it does not deal with persistence, but rather with clear and controlled conversion between conceptually different models.

A core concept of the Symfony Object Mapper is the separation between the domain and external layers. For example, consider a domain object User that represents business rules, and a UserDTO used for API input. The Object Mapper allows one to be converted into the other without forcing the domain to depend on HTTP concerns or framework-specific details.

$user = $mapper->map($userDto, User::class);

Another important aspect is the explicit definition of mappings. Instead of scattering manual conversions throughout the codebase, developers can declare how properties relate to one another. A simple example would be mapping fields with different names between objects:

$mapper->define(UserDTO::class, User::class)
    ->map('emailAddress', 'email')
    ->map('fullName', 'name');

This approach improves readability and significantly reduces subtle errors, especially as models evolve over time.

The component also makes it easier to handle more complex transformations, such as creating value objects. Suppose the domain uses an Email value object, while incoming data provides a plain string. The Object Mapper allows custom transformations to be defined:

$mapper->define(UserDTO::class, User::class)
    ->transform('email', fn (string $value) => new Email($value));

This keeps domain rules intact and avoids duplicating validation logic across multiple layers of the application.

In architectures such as Domain-Driven Design or Clean Architecture, the Object Mapper naturally fits between use cases and external interfaces. A controller, for instance, can receive a DTO, delegate the mapping process, and pass a consistent domain object to the use case without taking on extra responsibilities.

$user = $mapper->map($requestDto, User::class);
$createUserUseCase->execute($user);

From a technical standpoint, the Symfony Object Mapper is designed to be both extensible and efficient. Mapping definitions can be reused, transformations can be composed, and validations can even be integrated into the process, ensuring that resulting objects are already in a valid state before they are used.

Finally, by introducing clear examples and an intention-driven API, the Symfony Object Mapper helps standardize something that was historically implemented in an ad hoc manner. It reduces repetitive code, improves system expressiveness, and reinforces a culture of thoughtful design, making it a valuable ally for teams aiming to improve architectural quality from the very beginning of a project.

Comments

[Jean Klebert de A Modesto]

symfony.com/doc/current/object_map...

The Symfony ObjectMapper component was first released in March 2025. It was officially included as a new component in the stable release of Symfony 7.3 in May 2025, initially marked as experimental.
The component was later marked as no longer experimental in August 2025. The stable versions of Symfony 7.4 and Symfony 8.0, both released in November 2025, include the non-experimental component.

[david duymelinck]

I have written about the object mapper library, and while I think it is a convenient library it isn't that transformative that I would use it everywhere.

I was amazed by the more advanced options like conditional mapping, but now I'm leaning more to handling that logic in the business layer.

I would use the library when the mapping pattern is used enough and it results in less code.
There are other solutions to reduce repetitive code. And as far expressiveness goes a well named function/method, DTOToUser, is as good as $mapper->map($userDto, User::class).