Map DTOs to Entities in Symfony with ObjectMapper

Imagine you’re building a modern API with Symfony. You’re meticulous about your architecture, separating concerns with Data Transfer Objects (DTOs) for incoming request payloads and your Doctrine entities for your database persistence. It’s clean, it’s scalable, but then you hit a familiar wall: mapping data from your DTOs to your entities. You find yourself writing tedious, repetitive code like this: // src/Dto/ProductInput.php class ProductInput { public string $name; public string $description; public float $price; public string $currency; } // src/Controller/ProductController.php use App\Dto\ProductInput; use App\Entity\Product; use Doctrine\ORM\EntityManagerInterface; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Annotation\Route; use Symfony\Component\Serializer\SerializerInterface; class ProductController extends AbstractController { #[Route('/products', methods: ['POST'])] public function create( Request $request, SerializerInterface $serializer, EntityManagerInterface $entityManager ): Response { // ... (Assume validation happens here) /** @var ProductInput $productInput */ $productInput = $serializer->deserialize($request->getContent(), ProductInput::class, 'json'); $product = new Product(); $product->setName($productInput->name); $product->setDescription($productInput->description); $product->setPrice($productInput->price); $product->setCurrency($productInput->currency); // Manual mapping! $entityManager->persist($product); $entityManager->flush(); return $this->json(['id' => $product->getId()], Response::HTTP_CREATED); } } // src/Dto/ProductInput.php class ProductInput { public string $name; public string $description; public float $price; public string $currency; } // src/Controller/ProductController.php use App\Dto\ProductInput; use App\Entity\Product; use Doctrine\ORM\EntityManagerInterface; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Annotation\Route; use Symfony\Component\Serializer\SerializerInterface; class ProductController extends AbstractController { #[Route('/products', methods: ['POST'])] public function create( Request $request, SerializerInterface $serializer, EntityManagerInterface $entityManager ): Response { // ... (Assume validation happens here) /** @var ProductInput $productInput */ $productInput = $serializer->deserialize($request->getContent(), ProductInput::class, 'json'); $product = new Product(); $product->setName($productInput->name); $product->setDescription($productInput->description); $product->setPrice($productInput->price); $product->setCurrency($productInput->currency); // Manual mapping! $entityManager->persist($product); $entityManager->flush(); return $this->json(['id' => $product->getId()], Response::HTTP_CREATED); } } This isn’t terrible for one or two properties, but what if your DTOs and entities have dozens? Or if you need to perform transformations during the mapping? This manual process quickly becomes: Repetitive and verbose: Boilerplate code for every DTO-to-entity transformation. Error-prone: Easy to forget a property or introduce a typo. Hard to maintain: Changes to DTOs or entities require corresponding changes in multiple mapping locations. Clutters your domain logic: The actual business logic gets buried under mapping code. Repetitive and verbose: Boilerplate code for every DTO-to-entity transformation. Repetitive and verbose: Error-prone: Easy to forget a property or introduce a typo. Error-prone: Hard to maintain: Changes to DTOs or entities require corresponding changes in multiple mapping locations. Hard to maintain: Clutters your domain logic: The actual business logic gets buried under mapping code. Clutters your domain logic: Enter the Symfony ObjectMapper component. It’s a new, powerful tool designed specifically to solve this problem, allowing you to elegantly and automatically transfer data between different object types. This article will be your comprehensive guide to mastering it, making your DTO-to-entity (and object-to-object) mapping a breeze. Symfony ObjectMapper What is Object Mapping? At its heart, object mapping is the process of automatically transferring data from the properties of one object to the properties of another. Instead of manually writing setFoo($source->getBar()), an object mapper uses conventions (like matching property names) and explicit configurations to handle the data transfer for you. setFoo($source->getBar()) conventions explicit configurations For example, you might have: A UserRegistrationDto from a web form. A User entity to be persisted in your database. A UserRegistrationDto from a web form. UserRegistrationDto A User entity to be persisted in your database. User The object mapper bridges these two, transforming the DTO into the entity, property by property. The “Why”: Decoupling and Architecture The Symfony ObjectMapper shines brightest in architectures that prioritize separation of concerns, especially those utilizing DTOs (Data Transfer Objects) and Domain Entities. DTOs and Entities: This is the bread and butter. DTOs represent the data shape of an external interaction (like an API request payload or a message queue payload). Entities, on the other hand, represent your core domain model and how data is stored in your database. The ObjectMapper provides a clean, automated way to move data from the “outer” DTO world into your “inner” entity world, and vice-versa if needed. DTOs and Entities: This is the bread and butter. DTOs represent the data shape of an external interaction (like an API request payload or a message queue payload). Entities, on the other hand, represent your core domain model and how data is stored in your database. The ObjectMapper provides a clean, automated way to move data from the “outer” DTO world into your “inner” entity world, and vice-versa if needed. DTOs and Entities: graph TD A[API Request JSON] --> B(DTO: UserInput); B -- Map properties --> C(Entity: User); C -- Persist --> D[Database]; graph TD A[API Request JSON] --> B(DTO: UserInput); B -- Map properties --> C(Entity: User); C -- Persist --> D[Database]; Hexagonal Architecture (Ports & Adapters): Briefly, hexagonal architecture advocates for a clear separation between your core application logic (the “hexagon”) and external concerns (databases, UIs, APIs, message queues). DTOs act as messages exchanged through “ports,” and the ObjectMapper helps “adapt” these messages into your core domain objects. This keeps your domain logic pure, testable, and independent of infrastructure details. Hexagonal Architecture (Ports & Adapters): Briefly, hexagonal architecture advocates for a clear separation between your core application logic (the “hexagon”) and external concerns (databases, UIs, APIs, message queues). DTOs act as messages exchanged through “ports,” and the ObjectMapper helps “adapt” these messages into your core domain objects. This keeps your domain logic pure, testable, and independent of infrastructure details. Hexagonal Architecture (Ports & Adapters): By using an object mapper, you achieve a higher degree of decoupling. Your API controller doesn’t need to know the intricate details of your entity’s setters; it simply dispatches a DTO. Your entity remains focused on its domain responsibilities, not on how to consume incoming request data. Installation and Basic Usage The Symfony ObjectMapper component is designed for ease of use. Let’s get it installed and see it in action. Installation Installation Like any other Symfony component, you install it via Composer: composer require symfony/object-mapper composer require symfony/object-mapper Once installed, Symfony Flex will automatically register the necessary services. Basic Mapping Basic Mapping The core of the component is the ObjectMapperInterface. Symfony’s service container will automatically make an implementation available for autowiring in your services and controllers. ObjectMapperInterface Let’s revisit our ProductInput DTO and Product entity. // src/Dto/ProductInput.php namespace App\Dto; class ProductInput { public string $name; public string $description; public float $price; public string $currency; } // src/Entity/Product.php namespace App\Entity; use Doctrine\ORM\Mapping as ORM; #[ORM\Entity] class Product { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] private ?int $id = null; #[ORM\Column(length: 255)] private ?string $name = null; #[ORM\Column(length: 255)] private ?string $description = null; #[ORM\Column] private ?float $price = null; #[ORM\Column(length: 3)] private ?string $currency = null; // Getters and Setters omitted for brevity // ... } // src/Dto/ProductInput.php namespace App\Dto; class ProductInput { public string $name; public string $description; public float $price; public string $currency; } // src/Entity/Product.php namespace App\Entity; use Doctrine\ORM\Mapping as ORM; #[ORM\Entity] class Product { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] private ?int $id = null; #[ORM\Column(length: 255)] private ?string $name = null; #[ORM\Column(length: 255)] private ?string $description = null; #[ORM\Column] private ?float $price = null; #[ORM\Column(length: 3)] private ?string $currency = null; // Getters and Setters omitted for brevity // ... } Now, let’s use the ObjectMapperInterface in our controller. ObjectMapperInterface Mapping to a New Object Mapping to a New Object To create a brand new Product entity from our ProductInput DTO, we use the map() method, providing the source object and the target class name. Product ProductInput map() // src/Controller/ProductController.php (Updated) namespace App\Controller; use App\Dto\ProductInput; use App\Entity\Product; use App\Repository\ProductRepository; // Assuming you have this use Doctrine\ORM\EntityManagerInterface; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route; use Symfony\Component\Serializer\SerializerInterface; use Symfony\Component\Validator\Validator\ValidatorInterface; use Symfony\Component\Mapper\ObjectMapperInterface; // Import the interface! class ProductController extends AbstractController { #[Route('/products', methods: ['POST'])] public function create( ProductInput $productInput, // Symfony's RequestBody resolver injects DTO automatically ObjectMapperInterface $objectMapper, EntityManagerInterface $entityManager, ValidatorInterface $validator ): Response { // In modern Symfony (from 6.3), you'd use #[MapRequestPayload] for DTO injection and validation // So, $productInput is already populated and validated here. // Map the DTO to a new Product entity! $product = $objectMapper->map($productInput, Product::class); $entityManager->persist($product); $entityManager->flush(); return $this->json(['id' => $product->getId()], Response::HTTP_CREATED); } } // src/Controller/ProductController.php (Updated) namespace App\Controller; use App\Dto\ProductInput; use App\Entity\Product; use App\Repository\ProductRepository; // Assuming you have this use Doctrine\ORM\EntityManagerInterface; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route; use Symfony\Component\Serializer\SerializerInterface; use Symfony\Component\Validator\Validator\ValidatorInterface; use Symfony\Component\Mapper\ObjectMapperInterface; // Import the interface! class ProductController extends AbstractController { #[Route('/products', methods: ['POST'])] public function create( ProductInput $productInput, // Symfony's RequestBody resolver injects DTO automatically ObjectMapperInterface $objectMapper, EntityManagerInterface $entityManager, ValidatorInterface $validator ): Response { // In modern Symfony (from 6.3), you'd use #[MapRequestPayload] for DTO injection and validation // So, $productInput is already populated and validated here. // Map the DTO to a new Product entity! $product = $objectMapper->map($productInput, Product::class); $entityManager->persist($product); $entityManager->flush(); return $this->json(['id' => $product->getId()], Response::HTTP_CREATED); } } We inject ObjectMapperInterface $objectMapper. The magical line is $product = $objectMapper->map($productInput, Product::class);. The mapper automatically inspects both ProductInput and Product and, finding properties with matching names (name, description, price, currency), it transfers the values. It works by looking for public properties or setter methods on the target object. We inject ObjectMapperInterface $objectMapper. ObjectMapperInterface $objectMapper The magical line is $product = $objectMapper->map($productInput, Product::class);. $product = $objectMapper->map($productInput, Product::class); The mapper automatically inspects both ProductInput and Product and, finding properties with matching names (name, description, price, currency), it transfers the values. It works by looking for public properties or setter methods on the target object. Mapping to an Existing Object Mapping to an Existing Object What if you want to update an existing entity from a DTO (e.g., for a PUT request)? The map() method supports this too by passing the existing object instance as the target. Let’s imagine an ProductUpdateInput DTO, which might have nullable properties to represent partial updates. ProductUpdateInput // src/Dto/ProductUpdateInput.php namespace App\Dto; class ProductUpdateInput { public ?string $name = null; public ?string $description = null; public ?float $price = null; public ?string $currency = null; } // src/Dto/ProductUpdateInput.php namespace App\Dto; class ProductUpdateInput { public ?string $name = null; public ?string $description = null; public ?float $price = null; public ?string $currency = null; } Now, the update controller: // src/Controller/ProductController.php (Updated) namespace App\Controller; // ... other imports use App\Dto\ProductUpdateInput; class ProductController extends AbstractController { // ... create method #[Route('/products/{id}', methods: ['PUT'])] public function update( int $id, ProductUpdateInput $productUpdateInput, ObjectMapperInterface $objectMapper, ProductRepository $productRepository, EntityManagerInterface $entityManager, ValidatorInterface $validator ): Response { $product = $productRepository->find($id); if (!$product) { throw $this->createNotFoundException('Product not found.'); } // Map the DTO to the existing Product entity! $objectMapper->map($productUpdateInput, $product); $entityManager->flush(); // Persist changes return $this->json(['id' => $product->getId(), 'message' => 'Product updated successfully.']); } } // src/Controller/ProductController.php (Updated) namespace App\Controller; // ... other imports use App\Dto\ProductUpdateInput; class ProductController extends AbstractController { // ... create method #[Route('/products/{id}', methods: ['PUT'])] public function update( int $id, ProductUpdateInput $productUpdateInput, ObjectMapperInterface $objectMapper, ProductRepository $productRepository, EntityManagerInterface $entityManager, ValidatorInterface $validator ): Response { $product = $productRepository->find($id); if (!$product) { throw $this->createNotFoundException('Product not found.'); } // Map the DTO to the existing Product entity! $objectMapper->map($productUpdateInput, $product); $entityManager->flush(); // Persist changes return $this->json(['id' => $product->getId(), 'message' => 'Product updated successfully.']); } } We retrieve an existing $product entity from the repository. We then call $objectMapper->map($productUpdateInput, $product);. The mapper will iterate through the $productUpdateInput properties. For each non-null property, it will update the corresponding property on the existing $product entity. If a property in $productUpdateInput is null, it’s generally ignored by default unless explicitly configured otherwise (which we’ll see with attributes). We retrieve an existing $product entity from the repository. $product We then call $objectMapper->map($productUpdateInput, $product);. $objectMapper->map($productUpdateInput, $product); The mapper will iterate through the $productUpdateInput properties. For each non-null property, it will update the corresponding property on the existing $product entity. If a property in $productUpdateInput is null, it’s generally ignored by default unless explicitly configured otherwise (which we’ll see with attributes). $productUpdateInput $product $productUpdateInput With just these basic map() calls, we’ve eliminated a significant amount of manual data transfer code! map() Advanced Mapping with Attributes While property-name-matching is powerful, real-world applications often require more nuanced control. The Symfony ObjectMapper provides the #[Map] attribute to fine-tune the mapping process directly on your target object’s properties. Symfony ObjectMapper #[Map] The #[Map] Attribute The #[Map] attribute can be applied to properties or methods of your target object (e.g., your entity) to customize how data from the source object is mapped. // src/Entity/Product.php (with #[Map] attributes) namespace App\Entity; use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Mapper\Attribute\Map; // Don't forget this import! #[ORM\Entity] class Product { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] private ?int $id = null; // Example 1: Renaming a property // Map 'title' from source to 'name' on target #[ORM\Column(length: 255)] #[Map((source: 'title')] private ?string $name = null; #[ORM\Column(length: 255)] private ?string $description = null; // Example 2: Transforming a value // Assuming price comes in as a string, convert to float and round #[ORM\Column] #[Map(transform: 'floatval', round: 2)] // 'round' is a custom option for the transformer private ?float $price = null; #[ORM\Column(length: 3)] // Example 3: Conditional mapping (only map if not null/empty in source) #[Map(if: '!empty(value)')] private ?string $currency = null; // Example 4: Mapping to a setter method #[Map(source: 'supplierName')] private ?string $supplierInfo = null; // Getters and Setters public function getId(): ?int { return $this->id; } public function getName(): ?string { return $this->name; } public function setName(?string $name): static { $this->name = $name; return $this; } public function getDescription(): ?string { return $this->description; } public function setDescription(?string $description): static { $this->description = $description; return $this; } public function getPrice(): ?float { return $this->price; } public function setPrice(?float $price): static { $this->price = $price; return $this; } public function getCurrency(): ?string { return $this->currency; } public function setCurrency(?string $currency): static { $this->currency = $currency; return $this; } // Custom setter for supplierInfo, mapped from 'supplierName' public function setSupplierInfo(string $supplierName): static { $this->supplierInfo = 'Supplier: ' . $supplierName; return $this; } } // src/Entity/Product.php (with #[Map] attributes) namespace App\Entity; use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Mapper\Attribute\Map; // Don't forget this import! #[ORM\Entity] class Product { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] private ?int $id = null; // Example 1: Renaming a property // Map 'title' from source to 'name' on target #[ORM\Column(length: 255)] #[Map((source: 'title')] private ?string $name = null; #[ORM\Column(length: 255)] private ?string $description = null; // Example 2: Transforming a value // Assuming price comes in as a string, convert to float and round #[ORM\Column] #[Map(transform: 'floatval', round: 2)] // 'round' is a custom option for the transformer private ?float $price = null; #[ORM\Column(length: 3)] // Example 3: Conditional mapping (only map if not null/empty in source) #[Map(if: '!empty(value)')] private ?string $currency = null; // Example 4: Mapping to a setter method #[Map(source: 'supplierName')] private ?string $supplierInfo = null; // Getters and Setters public function getId(): ?int { return $this->id; } public function getName(): ?string { return $this->name; } public function setName(?string $name): static { $this->name = $name; return $this; } public function getDescription(): ?string { return $this->description; } public function setDescription(?string $description): static { $this->description = $description; return $this; } public function getPrice(): ?float { return $this->price; } public function setPrice(?float $price): static { $this->price = $price; return $this; } public function getCurrency(): ?string { return $this->currency; } public function setCurrency(?string $currency): static { $this->currency = $currency; return $this; } // Custom setter for supplierInfo, mapped from 'supplierName' public function setSupplierInfo(string $supplierName): static { $this->supplierInfo = 'Supplier: ' . $supplierName; return $this; } } Now, let’s create a new DTO that would work with these #[Map] configurations. // src/Dto/EnhancedProductInput.php namespace App\Dto; class EnhancedProductInput { public string $title; // Will be mapped to 'name' due to #[Map(source: 'title')] public string $description; public string $price; // Will be transformed to floatval public ?string $currency = null; // Can be null, will be mapped conditionally public string $supplierName; // Will be mapped to setSupplierInfo method } // src/Dto/EnhancedProductInput.php namespace App\Dto; class EnhancedProductInput { public string $title; // Will be mapped to 'name' due to #[Map(source: 'title')] public string $description; public string $price; // Will be transformed to floatval public ?string $currency = null; // Can be null, will be mapped conditionally public string $supplierName; // Will be mapped to setSupplierInfo method } And the mapping call remains the same: // In a controller or service: // Assuming $enhancedProductInput is an instance of EnhancedProductInput $product = $objectMapper->map($enhancedProductInput, Product::class); // In a controller or service: // Assuming $enhancedProductInput is an instance of EnhancedProductInput $product = $objectMapper->map($enhancedProductInput, Product::class); Let’s break down the #[Map] options: Let’s break down the #[Map] options: **1. Renaming Properties (from)**Sometimes your source object has a property name that doesn’t match your target object. The from option handles this. #[Map(source: ‘sourcePropertyName’)] — In Product, #[Map(source: ‘title’)] private ?string $name; tells the mapper to take the value from the title property of the source object and apply it to the name property (or setName() method) of the Product entity. #[Map(source: ‘sourcePropertyName’)] **2. Transforming Values (transform)**Often, you need to modify a value during mapping — perhaps changing its type, formatting it, or performing a calculation. The transform option accepts a callable. #[Map(transform: ‘callable_function_or_method’)] — #[Map(transform: ‘floatval’)] private ?float $price; will convert the incoming price value (e.g., a string) to a float. #[Map(transform: ‘callable_function_or_method’)] — Custom Callables: You can also pass a fully qualified callable (e.g., [App\Util\PriceTransformer::class, ‘transform’] or a service ID if the callable is a service). Custom Callables: **3. Conditional Mapping (if)**Sometimes you only want to map a property if a certain condition is met — for instance, if the source property isn’t null or empty, or if another property has a specific value. #[Map(if: ‘expression’)] — #[Map(if: ‘!empty(value)’)] private ?string $currency; means the currency property will only be set if the incoming value (from EnhancedProductInput::$currency) is not empty. #[Map(if: ‘expression’)] — Expression Language: The if option uses Symfony’s Expression Language. Expression Language: value: Refers to the value of the source property being mapped. source: Refers to the entire source object. target: Refers to the entire target object. value: Refers to the value of the source property being mapped. value: source: Refers to the entire source object. source: target: Refers to the entire target object. target: Example with source: #[Map(if: ‘source.isPublished’)] (assuming isPublished is a public property or getter on the source object). Example with source: #[Map(if: ‘source.isPublished’)] (assuming isPublished is a public property or getter on the source object). 4. Mapping to Setter MethodsThe ObjectMapper doesn’t just look for public properties; it also tries to use setter methods (e.g., setName()). You can explicitly map to a setter by placing the #[Map] attribute on the method itself. 4. Mapping to Setter Methods setSupplierInfo method in the Product entity. The #[Map(source: ‘supplierName’)] attribute on this method means that the value from EnhancedProductInput::$supplierName will be passed to setSupplierInfo(). This is great for encapsulating data processing within your domain model. setSupplierInfo EnhancedProductInput::$supplierName setSupplierInfo() These attributes provide a highly flexible and declarative way to manage complex mapping scenarios directly within your entity definitions, keeping your mapping logic co-located with the properties it affects. The Big Question: ObjectMapper vs. Serializer This is a crucial distinction that often causes confusion for new users. Symfony already has a powerful Serializer component, so why do we need another component for object mapping? The answer lies in their primary purpose and domain of responsibility. The Key Distinction: graph TD A[JSON String] -- deserialize --> B{Array}; B -- denormalize --> C(Object 1); C -- normalize --> D{Array}; D -- serialize --> E[JSON String]; subgraph Serializer A --- B B --- C C --- D D --- E end F(Object A) -- map --> G(Object B); subgraph ObjectMapper F --- G end graph TD A[JSON String] -- deserialize --> B{Array}; B -- denormalize --> C(Object 1); C -- normalize --> D{Array}; D -- serialize --> E[JSON String]; subgraph Serializer A --- B B --- C C --- D D --- E end F(Object A) -- map --> G(Object B); subgraph ObjectMapper F --- G end The diagram illustrates it clearly: the Serializer always involves an array conversion, while the ObjectMapper works directly with objects. Symfony Serializer Component Primary Goal is Transform data to and from formats (JSON, XML, YAML). Symfony Serializer Component Primary Goal is Transform Symfony ObjectMapper Component Primary Goal is Transform data from one object to another object. Symfony ObjectMapper Component Primary Goal The Benefits of ObjectMapper Simplicity for Object-to-Object: For the specific task of mapping one PHP object to another, the ObjectMapper is far simpler to configure and use than the Serializer. You avoid the mental overhead of normalizers, denormalizers, and group contexts that the Serializer often requires for complex object graphs. Performance: Bypassing the intermediate array step can offer a performance advantage, especially when dealing with many objects or very large objects, as it avoids the overhead of array creation and manipulation. Performance: Dedicated Purpose: The ObjectMapper is a single-purpose tool. This makes its behavior predictable and its API focused. When you’re dealing with object mapping, you reach for the object mapper; when you’re dealing with format conversion, you reach for the serializer. This clarity improves code readability and maintainability. Dedicated Purpose: In essence: In essence: Use the Serializer when you’re dealing with external data formats. Use the ObjectMapper when you’re dealing with internal PHP object conversions. Use the Serializer when you’re dealing with external data formats. Serializer external data formats Use the ObjectMapper when you’re dealing with internal PHP object conversions. ObjectMapper internal PHP object conversions Modern Symfony (from 6.3) applications often use both in tandem: the Serializer (via #[MapRequestPayload]) handles the initial deserialization from a request format into a DTO, and then the ObjectMapper takes over to transform that DTO into a domain entity. #[MapRequestPayload] Practical Examples and Use Cases Let’s look at some real-world scenarios where the ObjectMapper significantly simplifies your code. API Controllers (Putting it all together) This is the most common and impactful use case. By combining #[MapRequestPayload] (for initial DTO deserialization and validation) with the ObjectMapper, your controllers become lean, clean, and focused on coordination, not data wrangling. #[MapRequestPayload] // src/Controller/ProductApiController.php namespace App\Controller; use App\Dto\ProductInput; // Our DTO use App\Entity\Product; // Our Entity use App\Repository\ProductRepository; use Doctrine\ORM\EntityManagerInterface; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\HttpKernel\Attribute\MapRequestPayload; // Import this! use Symfony\Component\Mapper\ObjectMapperInterface; use Symfony\Component\Routing\Attribute\Route; class ProductApiController extends AbstractController { public function __construct( private ObjectMapperInterface $objectMapper, private EntityManagerInterface $entityManager, private ProductRepository $productRepository ) {} #[Route('/api/products', methods: ['POST'])] public function createProduct( #[MapRequestPayload] ProductInput $productInput // DTO automatically deserialized & validated! ): Response { // Map DTO to new Entity $product = $this->objectMapper->map($productInput, Product::class); $this->entityManager->persist($product); $this->entityManager->flush(); return $this->json([ 'message' => 'Product created successfully', 'id' => $product->getId(), 'name' => $product->getName() ], Response::HTTP_CREATED); } #[Route('/api/products/{id}', methods: ['PUT'])] public function updateProduct( int $id, #[MapRequestPayload] ProductInput $productInput // Using the same DTO for simplicity ): Response { $product = $this->productRepository->find($id); if (!$product) { throw $this->createNotFoundException('Product not found.'); } // Map DTO to existing Entity $this->objectMapper->map($productInput, $product); $this->entityManager->flush(); return $this->json([ 'message' => 'Product updated successfully', 'id' => $product->getId(), 'name' => $product->getName() ]); } } // src/Controller/ProductApiController.php namespace App\Controller; use App\Dto\ProductInput; // Our DTO use App\Entity\Product; // Our Entity use App\Repository\ProductRepository; use Doctrine\ORM\EntityManagerInterface; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\HttpKernel\Attribute\MapRequestPayload; // Import this! use Symfony\Component\Mapper\ObjectMapperInterface; use Symfony\Component\Routing\Attribute\Route; class ProductApiController extends AbstractController { public function __construct( private ObjectMapperInterface $objectMapper, private EntityManagerInterface $entityManager, private ProductRepository $productRepository ) {} #[Route('/api/products', methods: ['POST'])] public function createProduct( #[MapRequestPayload] ProductInput $productInput // DTO automatically deserialized & validated! ): Response { // Map DTO to new Entity $product = $this->objectMapper->map($productInput, Product::class); $this->entityManager->persist($product); $this->entityManager->flush(); return $this->json([ 'message' => 'Product created successfully', 'id' => $product->getId(), 'name' => $product->getName() ], Response::HTTP_CREATED); } #[Route('/api/products/{id}', methods: ['PUT'])] public function updateProduct( int $id, #[MapRequestPayload] ProductInput $productInput // Using the same DTO for simplicity ): Response { $product = $this->productRepository->find($id); if (!$product) { throw $this->createNotFoundException('Product not found.'); } // Map DTO to existing Entity $this->objectMapper->map($productInput, $product); $this->entityManager->flush(); return $this->json([ 'message' => 'Product updated successfully', 'id' => $product->getId(), 'name' => $product->getName() ]); } } This controller is beautifully concise. It defines the endpoint, handles the input DTO, and delegates the mapping and persistence. No more tedious manual property assignments. Asynchronous Messages (Symfony Messenger) When using the Symfony Messenger component, you often have a Message object that triggers a Handler. The message might contain raw data or IDs, but your handler’s business logic might prefer working with fully hydrated entities or richer domain objects. The ObjectMapper is perfect here. // src/Message/UpdateProductStock.php namespace App\Message; class UpdateProductStock { public function __construct( public int $productId, public int $newStockLevel ) {} } // src/Dto/ProductStockUpdateDto.php // A DTO that your service might prefer for domain operations namespace App\Dto; class ProductStockUpdateDto { public function __construct( public Product $product, // Fully hydrated entity public int $stockLevel ) {} } // src/MessageHandler/UpdateProductStockHandler.php namespace App\MessageHandler; use App\Message\UpdateProductStock; use App\Dto\ProductStockUpdateDto; use App\Entity\Product; use App\Repository\ProductRepository; use Symfony\Component\Messenger\Attribute\AsMessageHandler; use Symfony\Component\Mapper\ObjectMapperInterface; #[AsMessageHandler] class UpdateProductStockHandler { public function __construct( private ObjectMapperInterface $objectMapper, private ProductRepository $productRepository ) {} public function __invoke(UpdateProductStock $message) { $product = $this->productRepository->find($message->productId); if (!$product) { // Handle product not found, e.g., log error, dead-letter queue return; } // Create a DTO for internal service logic using the ObjectMapper $productStockUpdateDto = $this->objectMapper->map([ 'product' => $product, 'stockLevel' => $message->newStockLevel, ], ProductStockUpdateDto::class); // Now pass the richer DTO to your domain service // $this->productService->updateStock($productStockUpdateDto); // ... Or handle the logic directly here $productStockUpdateDto->product->setStock($productStockUpdateDto->stockLevel); $this->productRepository->save($productStockUpdateDto->product, true); // Assuming a save method } } // src/Message/UpdateProductStock.php namespace App\Message; class UpdateProductStock { public function __construct( public int $productId, public int $newStockLevel ) {} } // src/Dto/ProductStockUpdateDto.php // A DTO that your service might prefer for domain operations namespace App\Dto; class ProductStockUpdateDto { public function __construct( public Product $product, // Fully hydrated entity public int $stockLevel ) {} } // src/MessageHandler/UpdateProductStockHandler.php namespace App\MessageHandler; use App\Message\UpdateProductStock; use App\Dto\ProductStockUpdateDto; use App\Entity\Product; use App\Repository\ProductRepository; use Symfony\Component\Messenger\Attribute\AsMessageHandler; use Symfony\Component\Mapper\ObjectMapperInterface; #[AsMessageHandler] class UpdateProductStockHandler { public function __construct( private ObjectMapperInterface $objectMapper, private ProductRepository $productRepository ) {} public function __invoke(UpdateProductStock $message) { $product = $this->productRepository->find($message->productId); if (!$product) { // Handle product not found, e.g., log error, dead-letter queue return; } // Create a DTO for internal service logic using the ObjectMapper $productStockUpdateDto = $this->objectMapper->map([ 'product' => $product, 'stockLevel' => $message->newStockLevel, ], ProductStockUpdateDto::class); // Now pass the richer DTO to your domain service // $this->productService->updateStock($productStockUpdateDto); // ... Or handle the logic directly here $productStockUpdateDto->product->setStock($productStockUpdateDto->stockLevel); $this->productRepository->save($productStockUpdateDto->product, true); // Assuming a save method } } Here, the ObjectMapper is used to construct a ProductStockUpdateDto that encapsulates both the Product entity and the newStockLevel. This allows your ProductService (or the handler itself) to work with a more meaningful, typed object rather than raw message data. Notice how we pass an array as the source when mapping to a DTO with constructor arguments. ObjectMapper ProductStockUpdateDto Product newStockLevel ProductService Legacy Code Integration / Refactoring Imagine a large, legacy entity with many properties, and you need to build a new feature that only interacts with a subset of that data. You want to use a DTO for the new feature’s input, but directly mapping to the full legacy entity is problematic or requires too much modification. You can use the ObjectMapper to map your new, lean DTO to a subset of the legacy entity, or even to a temporary “adapter” object, helping you incrementally refactor. // src/Dto/LegacyProductMinimalUpdate.php namespace App\Dto; class LegacyProductMinimalUpdate { public ?string $newName = null; public ?string $newStatus = null; } // src/Entity/LegacyProduct.php namespace App\Entity; use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Mapper\Attribute\Map; #[ORM\Entity] class LegacyProduct { #[ORM\Id, ORM\GeneratedValue, ORM\Column] private ?int $id = null; #[ORM\Column(length: 255)] #[Map(source: 'newName')] // Map newName from DTO to name on entity private ?string $name = null; #[ORM\Column(length: 50)] #[Map(source: 'newStatus')] // Map newStatus from DTO to status on entity private ?string $status = null; #[ORM\Column(type: 'text')] private ?string $legacyDescription = null; // This property is not touched by the DTO // ... other many legacy properties // Getters and Setters public function getId(): ?int { return $this->id; } public function getName(): ?string { return $this->name; } public function setName(?string $name): static { $this->name = $name; return $this; } public function getStatus(): ?string { return $this->status; } public function setStatus(?string $status): static { $this->status = $status; return $this; } public function getLegacyDescription(): ?string { return $this->legacyDescription; } public function setLegacyDescription(?string $legacyDescription): static { $this->legacyDescription = $legacyDescription; return $this; } } // In a service for updating legacy products namespace App\Service; use App\Dto\LegacyProductMinimalUpdate; use App\Entity\LegacyProduct; use App\Repository\LegacyProductRepository; use Symfony\Component\Mapper\ObjectMapperInterface; use Doctrine\ORM\EntityManagerInterface; class LegacyProductUpdater { public function __construct( private ObjectMapperInterface $objectMapper, private LegacyProductRepository $legacyProductRepository, private EntityManagerInterface $entityManager ) {} public function updateMinimal(int $productId, LegacyProductMinimalUpdate $dto): LegacyProduct { $product = $this->legacyProductRepository->find($productId); if (!$product) { throw new \RuntimeException('Legacy product not found.'); } // Map only the relevant properties from the DTO to the legacy entity $this->objectMapper->map($dto, $product); $this->entityManager->flush(); return $product; } } // src/Dto/LegacyProductMinimalUpdate.php namespace App\Dto; class LegacyProductMinimalUpdate { public ?string $newName = null; public ?string $newStatus = null; } // src/Entity/LegacyProduct.php namespace App\Entity; use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Mapper\Attribute\Map; #[ORM\Entity] class LegacyProduct { #[ORM\Id, ORM\GeneratedValue, ORM\Column] private ?int $id = null; #[ORM\Column(length: 255)] #[Map(source: 'newName')] // Map newName from DTO to name on entity private ?string $name = null; #[ORM\Column(length: 50)] #[Map(source: 'newStatus')] // Map newStatus from DTO to status on entity private ?string $status = null; #[ORM\Column(type: 'text')] private ?string $legacyDescription = null; // This property is not touched by the DTO // ... other many legacy properties // Getters and Setters public function getId(): ?int { return $this->id; } public function getName(): ?string { return $this->name; } public function setName(?string $name): static { $this->name = $name; return $this; } public function getStatus(): ?string { return $this->status; } public function setStatus(?string $status): static { $this->status = $status; return $this; } public function getLegacyDescription(): ?string { return $this->legacyDescription; } public function setLegacyDescription(?string $legacyDescription): static { $this->legacyDescription = $legacyDescription; return $this; } } // In a service for updating legacy products namespace App\Service; use App\Dto\LegacyProductMinimalUpdate; use App\Entity\LegacyProduct; use App\Repository\LegacyProductRepository; use Symfony\Component\Mapper\ObjectMapperInterface; use Doctrine\ORM\EntityManagerInterface; class LegacyProductUpdater { public function __construct( private ObjectMapperInterface $objectMapper, private LegacyProductRepository $legacyProductRepository, private EntityManagerInterface $entityManager ) {} public function updateMinimal(int $productId, LegacyProductMinimalUpdate $dto): LegacyProduct { $product = $this->legacyProductRepository->find($productId); if (!$product) { throw new \RuntimeException('Legacy product not found.'); } // Map only the relevant properties from the DTO to the legacy entity $this->objectMapper->map($dto, $product); $this->entityManager->flush(); return $product; } } The LegacyProductMinimalUpdate DTO only exposes two properties. By using #[Map(source: …)] on the LegacyProduct entity, we can selectively update only name and status without affecting legacyDescription or any other properties that aren’t part of the DTO, providing a safer way to introduce DTOs into existing, complex codebases. LegacyProductMinimalUpdate #[Map(source: …)] LegacyProduct legacyDescription Looking Ahead: The Future of the Component It’s important to note that the Symfony ObjectMapper component is currently marked as experimental. This means: API Stability: The API may change in future Symfony versions. While the core map() method is likely to remain, attribute options or other details could be adjusted. Backward Compatibility: It’s not yet covered by Symfony’s strict backward compatibility promise. Production Readiness: While perfectly usable, you should be aware of its experimental status when deploying to critical production environments and be prepared for potential adjustments during upgrades. API Stability: The API may change in future Symfony versions. While the core map() method is likely to remain, attribute options or other details could be adjusted. API Stability: Backward Compatibility: It’s not yet covered by Symfony’s strict backward compatibility promise. Backward Compatibility: Production Readiness: While perfectly usable, you should be aware of its experimental status when deploying to critical production environments and be prepared for potential adjustments during upgrades. Production Readiness: Despite its experimental tag, the component is already robust and highly valuable. Its inclusion in Symfony 6.4 (and later 7.0) signals a strong commitment to addressing the object mapping problem. Future Possibilities As an experimental component, there’s exciting potential for its evolution: Performance Optimizations: While already efficient, future versions might explore techniques like code generation (similar to how some Doctrine proxies work) to achieve even greater mapping speeds. More Advanced Mapping Strategies: Expanding the attribute options or introducing configuration files for more complex, global mapping rules. Integration with other components: Even tighter integration with validation, serialization, or form components. Performance Optimizations: While already efficient, future versions might explore techniques like code generation (similar to how some Doctrine proxies work) to achieve even greater mapping speeds. Performance Optimizations: More Advanced Mapping Strategies: Expanding the attribute options or introducing configuration files for more complex, global mapping rules. More Advanced Mapping Strategies: Integration with other components: Even tighter integration with validation, serialization, or form components. Integration with other components: Conclusion The Symfony ObjectMapper component is a fantastic addition to the Symfony ecosystem. It provides a focused, elegant, and highly configurable solution to the perennial problem of mapping data between different PHP objects. By adopting it, you can: Significantly reduce boilerplate code in your controllers and services. Improve the clarity and maintainability of your application’s architecture. Decouple your domain models from external data representations. Write cleaner, more robust code with less manual data transfer. Significantly reduce boilerplate code in your controllers and services. Significantly reduce boilerplate code Improve the clarity and maintainability of your application’s architecture. Improve the clarity and maintainability Decouple your domain models from external data representations. Decouple your domain models Write cleaner, more robust code with less manual data transfer. Write cleaner, more robust code While currently experimental, its value is undeniable. Embrace the Symfony ObjectMapper, and say goodbye to tedious manual mapping — your codebase (and your future self) will thank you. Start integrating it into your projects today and experience the benefits firsthand!