danilovl / object-dto-mapper
Mapper that converts an object to a DTO.
Package info
github.com/danilovl/object-dto-mapper
Type:symfony-bundle
pkg:composer/danilovl/object-dto-mapper
Requires
- php: ^8.5
- psr/container: ^1.1 || ^2.0
- symfony/config: ^8.0
- symfony/dependency-injection: ^8.0
- symfony/http-kernel: ^8.0
- symfony/property-access: ^8.0
- symfony/yaml: ^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.92.5
- phpstan/extension-installer: ^1.4.3
- phpstan/phpstan: ^2.1.33
- phpstan/phpstan-symfony: ^2.0.9
- phpunit/phpunit: ^12.5.6
- symfony/framework-bundle: ^8.0
- symfony/serializer: ^8.0
Suggests
- symfony/serializer: Required to filter DTO properties by #[Groups] (allowGroups/ignoreGroups)
Provides
None
Conflicts
None
Replaces
None
README
Object to DTO mapper
Description
A lightweight mapper that converts an object (Entity/model) to a DTO based on the DTO constructor signature.
Mapping is controlled via the #[Map] attribute on DTO constructor parameters / properties.
It supports conditional mapping (if), value transformations (transform), collections, nested objects,
enums, dates and filtering by Symfony Serializer #[Groups] — and it is safe by default: entities never leak into a DTO unmapped.
Key features
- Map by matching a property name or from any property path via
Map(source)(profile.address.city,settings[theme]) - Conditional mapping: bool, callable, closure or container service (
Map(if)/Map(ifContainer)) - Transformations: callable, closure or container service (
Map(transform)/Map(transformContainer)) - Nested objects are mapped recursively based on the constructor parameter type (union types supported)
- Collections (arrays,
Traversable, generators, Doctrine collections) are mapped item by item viaMap(target) - Automatic conversion of
DateTimeInterfaceand enums (see Type conversion) - Filter DTO properties by groups (
allowGroups/ignoreGroups), nested DTOs included - Protection against leaking unmapped objects, circular references and too deep graphs
- Every error is a
MappingExceptionwith the property path, e.g.(path: "posts[3].author.name") - Metadata (reflection, attributes, resolved callables) is built once per DTO class and cached
Requirements
- PHP 8.5+
- symfony/property-access 8.0+
- symfony/dependency-injection, symfony/config, symfony/http-kernel, symfony/yaml 8.0+
- psr/container 1.1+ or 2.0+
- symfony/serializer 8.0+ (optional, only for
#[Groups]filtering)
Installation
composer require danilovl/object-dto-mapper
With Symfony Flex the bundle is registered automatically. Otherwise add it to config/bundles.php:
// config/bundles.php return [ // ... Danilovl\ObjectDtoMapper\ObjectDtoMapperBundle::class => ['all' => true] ];
That is all: ObjectToDtoMapperInterface can be injected right away, no service configuration is needed.
If you want to filter by groups:
composer require symfony/serializer
Quick start
<?php declare(strict_types=1); namespace App\Entity; use DateTimeImmutable; use Doctrine\DBAL\Types\Types; use Doctrine\ORM\Mapping as ORM; #[ORM\Entity] #[ORM\Table(name: 'user')] class UserEntity { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column(type: Types::INTEGER)] public int $id; #[ORM\Column(type: Types::STRING, length: 255)] public string $name; #[ORM\Column(type: Types::STRING, length: 255)] public string $password; #[ORM\Column(type: Types::INTEGER)] public int $age; #[ORM\Column(type: Types::STRING, enumType: UserStatus::class)] public UserStatus $status; #[ORM\Column(type: Types::DATE_IMMUTABLE, nullable: true)] public ?DateTimeImmutable $registeredAt = null; #[ORM\Column(type: Types::STRING, length: 255, nullable: true)] public ?string $email = null; }
<?php declare(strict_types=1); namespace App\Dto; final readonly class UserDto { public function __construct( public string $name, public int $age, public string $status, // backed enum -> its value public ?string $registeredAt, // DateTimeInterface -> ATOM string public ?string $email, ) {} }
<?php declare(strict_types=1); namespace App\Controller; use App\Dto\UserDto; use App\Entity\UserEntity; use Danilovl\ObjectDtoMapper\Service\ObjectToDtoMapperInterface; use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\Routing\Attribute\Route; final class UserController { public function __construct(private readonly ObjectToDtoMapperInterface $mapper) {} #[Route('/api/users/{id}', name: 'api_user', methods: ['GET'])] public function show(UserEntity $user): JsonResponse { return new JsonResponse($this->mapper->map($user, UserDto::class)); } #[Route('/api/users', name: 'api_users', methods: ['GET'])] public function list(UserRepository $repository): JsonResponse { return new JsonResponse($this->mapper->mapCollection($repository->findAll(), UserDto::class)); } }
Mapper API
interface ObjectToDtoMapperInterface { public function map(object $source, string $target, array $allowGroups = [], array $ignoreGroups = []): object; public function mapCollection(iterable $collection, string $target, array $allowGroups = [], array $ignoreGroups = []): array; }
Constructor options of ObjectToDtoMapper:
| Option | Default | Description |
|---|---|---|
$container |
null |
PSR container (preferably a service locator) for Map(ifContainer), Map(transformContainer) and invokable class-strings |
$propertyAccessor |
new accessor | Inject the cached property_accessor service in Symfony |
$allowObjectPassthrough |
false |
Allow unmapped objects inside array/mixed/object parameters (see Security) |
$maxDepth |
32 |
Maximum nesting depth of mapped objects |
Symfony integration
The bundle registers everything automatically:
ObjectToDtoMapperservice with theObjectToDtoMapperInterfacealias (autowiring works out of the box);- the cached
property_accessorservice of the framework is injected when available; - every service implementing
MapIfCallableInterfaceorMapTransformCallableInterfaceis found by a compiler pass and is available to the mapper by its service id (class name) through a service locator — with or withoutautoconfigure, private services included; no tags are needed and the wholeservice_containeris never exposed.
A handler only has to be a registered service (e.g. via the default App\ resource of services.yaml)
and implement the interface:
final class EmailGuardService implements MapIfCallableInterface { public function __invoke(mixed $value, object $source, string $target): bool { return !empty($value); } } final class UserDto { public function __construct( #[Map(ifContainer: EmailGuardService::class)] public ?string $email = null, ) {} }
The service is looked up by the id used in the attribute, so for a service registered under a custom id
use that id: #[Map(ifContainer: 'app.email_guard')].
Configuration (optional)
# config/packages/danilovl_object_dto_mapper.yaml danilovl_object_dto_mapper: allow_object_passthrough: false # see "Security: unmapped objects" max_depth: 32 # maximum nesting depth of mapped objects
Without Symfony
The mapper can be created manually; pass any PSR-11 container for container handlers:
$mapper = new ObjectToDtoMapper(container: $psrContainer);
Where to put #[Map]
The mapper reads the target constructor. For every constructor parameter the #[Map] attribute is looked up:
- on the constructor-promoted property (the usual case);
- on a regular (non-promoted) constructor parameter;
- on a class property with the same name as the parameter.
final class ArticleDto { #[Map(source: 'headline')] public string $title; public string $slug; public function __construct(string $title, #[Map(source: 'name')] string $slug) { $this->title = $title; $this->slug = mb_strtolower($slug); } }
Inherited constructors (also with private promoted properties) and variadic parameters (string ...$tags) are supported.
The target must be a concrete class with a public constructor.
#[Map] attribute
#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_PARAMETER)] readonly class Map { public function __construct( public ?string $target = null, // DTO class for collection items / nested object public ?string $source = null, // property path in the source object public mixed $if = null, // bool | callable | Closure public ?string $ifContainer = null, // service id (MapIfCallableInterface) public mixed $transform = null, // callable | Closure public ?string $transformContainer = null // service id (MapTransformCallableInterface) ) {} }
Configuration is validated when the attribute is instantiated:
ifandifContainercannot be used together —MappingIfExceptiontransformandtransformContainercannot be used together —MappingTransformExceptionifContainer/transformContainermust be non-empty stringsifmust be bool, string, array or Closure;transformmust be string, array or Closure
Supported callable forms for if and transform
| Form | Example |
|---|---|
| Closure (PHP 8.5) | #[Map(transform: static function (string $v): string { return trim($v); })] |
| First-class callable (PHP 8.5) | #[Map(transform: mb_strtoupper(...))] |
| Function name | #[Map(transform: 'trim')] |
| Static method string | #[Map(if: EmailGuard::class . '::notEmpty')] |
| Static method array | #[Map(if: [EmailGuard::class, 'notEmpty'])] |
| Invokable class | #[Map(transform: Uppercase::class)] |
An invokable class-string is taken from the container when the container has it, otherwise it is instantiated
with new (it must not have required constructor arguments). Resolved callables are cached per DTO class.
Handlers receive up to three arguments: (mixed $value, object $source, string $target), where $target is the DTO class
being created. A handler declaring fewer parameters receives fewer arguments; built-in PHP functions (trim, strlen, …)
receive only the value.
Mapping pipeline
For every constructor parameter the mapper performs these steps in this order:
- Groups — if the property is excluded by
allowGroups/ignoreGroups, the source is not touched at all (getters are not called). Map(if: false)— skips the property without reading the source.- Read the value once from
source(property name by default) using Symfony PropertyAccess (public property, gettergetX()/isX()/hasX(), array index, nested path). - Condition
if/ifContainer— the result is cast to bool. - Transform
transform/transformContainer. - Null handling and type conversion / nested mapping.
Skipped or unreadable values
When a property is excluded by groups, skipped by a condition or the source path cannot be read
(missing or private property, uninitialized typed property, null in the middle of a path):
- the constructor default value is used, if any;
- otherwise
null, if the parameter is nullable; - otherwise an exception is thrown:
| Reason | Exception |
|---|---|
excluded by ignoreGroups / allowGroups |
RuntimeException (... is restricted by ignoreGroups filter) |
if / ifContainer returned false |
MappingIfException (... skipped by Map(if) condition) |
| source path cannot be read | NoSuchPropertyException |
Null values
When the read (or transformed) value is null:
- nullable parameter →
null(an explicitnullfrom the source wins over the default value); - non-nullable parameter with a default value → the default value;
- otherwise →
RuntimeException(Non-nullable property "x" of "Dto" is null).
Object default values (public Options $options = new Options) are created fresh for every DTO.
Type conversion
| Source value | Parameter type | Result |
|---|---|---|
| object | class/interface the object already is an instance of | the object as is |
DateTimeInterface |
string, mixed, untyped |
DateTimeInterface::ATOM string |
DateTimeInterface |
DateTimeImmutable / DateTime (or subclass) |
converted via createFromInterface() |
BackedEnum |
string / int |
->value (int-backed enum to string is cast) |
UnitEnum |
string |
->name |
| enum | mixed, object, untyped |
the enum as is |
int/string |
BackedEnum |
Enum::tryFrom(); invalid value → RuntimeException |
| object | concrete DTO class (also inside a union type) | mapped recursively |
| object | interface / abstract class it does not implement | RuntimeException — use Map(target) |
| iterable | array / iterable with Map(target) |
every item mapped to the target |
Traversable |
array / iterable without Map(target) |
converted to array |
| scalar | scalar | passed as is (PHP coercion applies) |
Usage examples
1) Map from another field or a nested path (source)
final class UserDto { public function __construct( #[Map(source: 'altName')] public string $name, #[Map(source: 'profile.address.city')] public ?string $city, // null when profile or address is null #[Map(source: 'settings[theme]')] public string $theme = 'light', ) {} }
2) Conditional mapping: simple flags
final class DtoIfBool { public function __construct( #[Map(if: true)] public string $name, #[Map(if: false)] public ?int $age = null, ) {} }
3) Conditional mapping: callable or closure
final class DtoIfCallable { public function __construct( public string $name, #[Map(if: [EmailGuard::class, 'allowIfNotEmpty'])] public ?string $email = null, #[Map(if: static function (mixed $value, UserEntity $source): bool { return $source->isPhonePublic(); })] public ?string $phone = null, ) {} } final class EmailGuard { public static function allowIfNotEmpty(?string $value): bool { return !empty($value); } }
4) Conditional mapping via container (ifContainer)
final class DtoIfContainer { public function __construct( public string $name, #[Map(ifContainer: EmailGuardService::class)] public ?string $email = null, ) {} } final class EmailGuardService implements MapIfCallableInterface { public function __construct(private readonly Security $security) {} public function __invoke(mixed $value, object $source, string $target): bool { return $this->security->isGranted('ROLE_ADMIN'); } }
5) Transform
final class DtoTransform { public function __construct( #[Map(transform: Uppercase::class)] public string $name, #[Map(transform: mb_strtolower(...))] public string $login, #[Map(transform: static function (?string $v): ?string { return $v === null ? null : mb_strtoupper(mb_trim($v)); })] public ?string $email = null, ) {} } final class Uppercase { public function __invoke(string $value): string { return mb_strtoupper($value); } }
The value is passed to the transformer as is, including null: make the transformer null-safe for nullable sources.
The transformer result goes through the normal type conversion, so returning a DateTimeInterface
into a string parameter produces an ATOM string. A transformer result is trusted: it is not checked by the
unmapped-object protection.
6) Transform using a service (transformContainer)
final class DtoTransformService { public function __construct( #[Map(transformContainer: PriceFormatter::class)] public string $price, ) {} } final class PriceFormatter implements MapTransformCallableInterface { public function __construct(private readonly NumberFormatter $formatter) {} public function __invoke(mixed $value, object $source, string $target): mixed { return $this->formatter->formatCurrency((float) $value, 'EUR'); } }
7) Collections
final class OrderDto { /** * @param OrderItemDto[] $items */ public function __construct( #[Map(target: OrderItemDto::class)] public array $items, ) {} }
- Works with arrays,
Traversable(DoctrineCollection), generators. - Integer keys are re-indexed into a list (a Doctrine collection after
removeElement()still serializes as a JSON array); string keys are preserved. nullitems are kept asnull; scalar items throwRuntimeException.- Items that already are instances of the target are kept.
$mapper->mapCollection($entities, OrderItemDto::class)maps a top-level collection.
8) Nested objects
If the parameter type is a concrete class, the source object is mapped recursively:
final class UserDto { public function __construct( public string $name, public ProfileDto $profile, public ?AddressDto $address, // null stays null public AddressDto|string $location, // union types are supported ) {} }
For an interface or abstract parameter type specify the class with Map(target):
#[Map(target: PostalAddressDto::class)] public AddressInterface $address,
9) Groups (allowGroups/ignoreGroups)
Mark DTO properties with Symfony\Component\Serializer\Attribute\Groups:
final class UserDto { public function __construct( #[Groups(['public'])] public string $name, #[Groups(['admin'])] public ?string $email = null, public ?int $age = null, // no group ) {} } $mapper->map($user, UserDto::class, allowGroups: ['public']); // name $mapper->map($user, UserDto::class, allowGroups: ['public', 'admin']); // name, email $mapper->map($user, UserDto::class, ignoreGroups: ['admin']); // name, age $mapper->map($user, UserDto::class, allowGroups: ['public'], ignoreGroups: ['x']); // name
Rules (same as Symfony Serializer):
allowGroupsnot empty → only properties belonging to at least one of the groups are mapped; properties without groups are excluded.ignoreGroups→ properties belonging to any of the groups are excluded;ignoreGroupswins overallowGroups.- Groups are applied to nested DTOs and collection items as well.
- An excluded property gets its default value or
null; a non-nullable property without default throwsRuntimeException.
Security: unmapped objects
An object that is not mapped to a DTO is never put into the DTO as is. Without this protection an entity inside
an array, mixed, object or untyped parameter would be serialized with all its public fields (password hash, tokens, …):
final class UserListDto { public function __construct(public array $users) {} // no Map(target) } $mapper->map($group, UserListDto::class); // UnmappedObjectException: Refusing to pass unmapped object of class "App\Entity\UserEntity" into property "users" ...
Allowed without mapping:
- scalars, arrays of scalars;
DateTimeInterfaceand enums;- an object whose class is explicitly declared as the parameter type (
public UserEntity $user); - the result of a transformer.
Fix the DTO by declaring a DTO type / Map(target) / Map(transform), or disable the check globally with
new ObjectToDtoMapper(allowObjectPassthrough: true).
Recursion
- Circular references (
Author → posts → Post → author → Author) throwCircularReferenceExceptionwith the path where the cycle was found. Break the cycle with a separate summary DTO, groups orMap(if). - The same object used in several non-cyclic places (one author of several posts) is fine.
- Graphs deeper than
maxDepth(default 32) throwMaxDepthException.
Exceptions
All exceptions extend Danilovl\ObjectDtoMapper\Exception\MappingException (which extends \RuntimeException),
so a single catch (MappingException) is enough. Messages contain the property path, e.g. (path: "items[2].author.name").
| Exception | When |
|---|---|
NoSuchClassException |
target class or Map(target) class or invokable class does not exist |
NoSuchPropertyException |
source cannot be read for a non-nullable property without default |
MappingIfException |
invalid if/ifContainer definition, handler failed, non-nullable property skipped |
MappingTransformException |
invalid transform/transformContainer definition or handler failed |
UnmappedObjectException |
an unmapped object would be put into the DTO |
CircularReferenceException |
circular reference in the source graph |
MaxDepthException |
graph deeper than maxDepth |
RuntimeException |
invalid target class, null for non-nullable, group restriction, invalid enum value, type mismatch (TypeError is attached as previous) |
Exceptions thrown by if/transform handlers are wrapped into MappingIfException/MappingTransformException;
the original exception is available via getPrevious().
Upgrade notes (from previous versions)
allowGroupsnow works on its own. Previously it was ignored unlessignoreGroupswas also set, somap($e, Dto::class, allowGroups: ['public'])mapped every property.- Unmapped objects inside
array/mixed/object/untyped parameters now throwUnmappedObjectException(useallowObjectPassthrough: trueto restore the old behaviour). - Collections keep
nullitems and string keys; scalar items throw instead of being silently dropped. - A
nullsource value for a non-nullable parameter with a default value now uses the default instead of throwing. - A non-readable source for a non-nullable parameter without default throws
NoSuchPropertyExceptioninstead of aTypeError. - Errors in transform definitions throw
MappingTransformException(previouslyMappingIfException). #[Map]targets properties and parameters only (TARGET_CLASSandIS_REPEATABLEwere never used).symfony/serializeris optional,psr/containeris now a declared dependency.- New method
mapCollection()inObjectToDtoMapperInterface. - The package is now a Symfony bundle (
ObjectDtoMapperBundle): remove the manual service definition of the mapper (and the$container: '@service_container'argument) from yourservices.yaml.
License
This package is open-sourced software licensed under the MIT.