Add AutoMapper component #1

Korbeil · 2023-03-28T12:00:45Z

Q	A
Branch?	6.3
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	N/A
License	MIT
Doc PR	todo

This PR brings a new component to Symfony: the AutoMapper. While Symfony's Serializer aims towards flexibility, it lacks performance (you can see https://live.symfony.com/account/replay/video/593 replay for more details about it).
The AutoMapper adds AST to generate blazing fast mappers to replace the Serializer in simple mapping scenarios.

Description

Taken from https://github.com/AutoMapper/AutoMapper

AutoMapper is a simple little library built to solve a deceptively complex problem - getting rid of code that mapped one object to another. This type of code is rather dreary and boring to write, so why not invent a tool to do it for us?

In PHP libraries and application mapping from one object to another is fairly common:

ObjectNormalizer / GetSetMethodNormalizer in symfony/serializer
Mapping request data to object in symfony/form
Hydrate object from SQL results in Doctrine (You can see https://github.com/soyuka/esql that uses the AutoMapper for the same purpose)
Migrating legacy data to new model
Mapping from database model to dto objects (API / CQRS / ...)
...

And even more recently with the MapQueryString attribute.

The goal of this component is to offer an abstraction on top of this subject. For that goal it provides an unique interface (other code is only implementation detail):

interface AutoMapperInterface
{
    /**
     * Maps data from a source to a target.
     *
     * @param array|object|null   $source  Any data object, which may be an object or an array
     * @param string|array|object $target  To which type of data, or data, the source should be mapped
     * @param array               $context Mapper context
     *
     * @return array|object|null The mapped object
     */
    public function map(null|array|object $source, string|array|object $target, array $context = []): null|array|object;
}

The source is from where the data comes from, it can be either an array or an object.
The target is where the data should be mapped to, it can be either a string (representing a type: array or class name) or directly an array or object (in that case construction of the object is avoided).

Current implementation handle all of those possibilities at the exception of the mapping from a dynamic object (array / stdClass) to another dynamic object (this could be compared to the normalization stack of the Symfony Serializer).

Usage

Someone who wants to map an object will only have to do this:

// With class name
$target = $automapper->map($source, Foo::class);
// With existing object
$target = new Foo();
$target = $automapper->map($source, $target);
// To an array
$target = $automapper->map($source, 'array');
// From an array
$source = ['a' => 'b'];
$target = $automapper->map($source, Foo::class);

Other features

Context

Context object allow to pass options for the mapping:

// Using context
$context = new Context();
$target = $automapper->map($source, Foo::class, $context);

// Groups (serializer annotation), will only map value that match those group in source and target
$context = new Context(['groupA', 'groupB']);
// Allowed attributes, will only map specific properties (exclude others), allow nesting for sub mapping like the serializer component
$context = new Context(null, ['propertyA', 'propertyB', 'foo' => ['fooPropertyA']]);
// Ignored attributes, exclude thos propreties include others
$context = new Context(null, null, ['propertyA', 'propertyB', 'foo' => ['fooPropertyA']]);
// Set circular reference limit
$context->setCircularReferenceLimit(2);
// Set circular reference handler
$context->setCircularReferenceHandler(function () { ... });

Private properties

This component map private properties (However this can deactivated).

Nested Mapping

This component map nested class when it's possible.

Circular Reference

Default circular reference implementation is to keep them during mapping, which means somethings like:

$foo = new Foo();
$foo->setFoo($foo);

$target = $this->automapper->map($foo, 'array');

will produce an array where the foo property will be a reference to the parent.

Having that allow using this component as a DeepCloning service by mapping to the same object:

$foo = new Foo();
$foo->setFoo($foo);

$deepClonedFoo = $this->automapper->map($foo, Foo::class);

Max Depth

This component understand the Max Depth Annotation of the Serializer component and will not map after it's reached.

Name Converter

Default implementation allows you to pass a Name Converter when converting to or from an array to change the property name used.

Discriminator Mapping

This component understand the Discriminiator Mapping Annotation of the Serializer component and should correctly handle construction of object when having inheritance.

Ignored

This component understand the Ignore Annotation of the Serializer component and will not map if a property is flagged.

Type casting

This component will try to correctly map scalar values (going from int to string, etc ...).

Readonly properties & classes

This component does support readonly properties & classes. For the readonly classes, you will have an exception by default if you try to map to a readonly class with an object to populate.

Warmup mappers

If you have a set of critical mappers, you can generate mappers before executing your code on cache warmup thanks to some configuration:

framework:
    automapper: 
        enabled: true
        warmup:
            - {source: 'array', target: 'Symfony\Bundle\FrameworkBundle\Tests\Fixtures\AutoMapper\Foo'}
            - {target: 'Symfony\Bundle\FrameworkBundle\Tests\Fixtures\AutoMapper\Bar'}

History

Initial code of this component was done in a library here: https://github.com/janephp/automapper

After some works and talks with @dunglas, @lyrixx and @mtarld I propose this library as a new component for Symfony, which can be used by other components.

Implementation

Default implementation use code generation for mapping, it reads once the metadata needed to build the mapper then write PHP code, after this, no metadata reading or analysis is done, only the generated mapper is used.

This allow for very fast mapping, here is some benchmarks using the library where the code comes from (jane-php/automapper):

I used PHP 7.4 here because JMS Serializer is not compatible with PHP 8.0+, but this shouldn't change the results that much. Bench code can be found at: https://github.com/Korbeil/automapper-bench

Normalizer Bridge

A normalizer Bridge is available where its goal is to be 100% feature compatible with the ObjectNormalizer of the symfony/serializer component. The goal of this bridge is not to replace the ObjectNormalizer but rather providing a very fast alternative.

As shown in the benchmark above, using this bridge leads up to more than 8x speed increase in normalization.

Things that needs to be done

This PR should be mostly readly in terms of code and functionnalities for a first stage, however there is still some things to be done:

Documentation: documentation explaining this new component (will be done once the main interface and usage is ok).
Support all Serializer attributes for a complete compatibility.

Future consideration

Things that could be done but not in this PR:

symfony/form bridge for mapping request data to object
symfony/framework-bundle integration
symfony/validator integration:

Feel free to challenge as much as possible

…hen publishing a message. (jwage) This PR was squashed before being merged into the 6.4 branch. Discussion ---------- [Messenger] [Amqp] Handle AMQPConnectionException when publishing a message. | Q | A | ------------- | --- | Branch? | 6.4 | Bug fix? | yes | New feature? | no | Deprecations? | no | Issues | Fix symfony#36538 Fix symfony#48241 | License | MIT If you have a message handler that dispatches messages to another queue, you can encounter `AMQPConnectionException` with the message "Library error: a SSL error occurred" or "a socket error occurred" depending on if you are using tls or not or if you are running behind a load balancer or not. You can manually reproduce this issue by dispatching a message where the handler then dispatches another message to a different queue, then go to rabbitmq admin and close the connection manually, then dispatch another message and when the message handler goes to dispatch the other message, you will get this exception: ``` a socket error occurred #0 /vagrant/vendor/symfony/amqp-messenger/Transport/AmqpTransport.php(60): Symfony\Component\Messenger\Bridge\Amqp\Transport\AmqpSender->send() #1 /vagrant/vendor/symfony/messenger/Middleware/SendMessageMiddleware.php(62): Symfony\Component\Messenger\Bridge\Amqp\Transport\AmqpTransport->send() #2 /vagrant/vendor/symfony/messenger/Middleware/FailedMessageProcessingMiddleware.php(34): Symfony\Component\Messenger\Middleware\SendMessageMiddleware->handle() symfony#3 /vagrant/vendor/symfony/messenger/Middleware/DispatchAfterCurrentBusMiddleware.php(61): Symfony\Component\Messenger\Middleware\FailedMessageProcessingMiddleware->handle() symfony#4 /vagrant/vendor/symfony/messenger/Middleware/RejectRedeliveredMessageMiddleware.php(41): Symfony\Component\Messenger\Middleware\DispatchAfterCurrentBusMiddleware->handle() symfony#5 /vagrant/vendor/symfony/messenger/Middleware/AddBusNameStampMiddleware.php(37): Symfony\Component\Messenger\Middleware\RejectRedeliveredMessageMiddleware->handle() symfony#6 /vagrant/vendor/symfony/messenger/Middleware/TraceableMiddleware.php(40): Symfony\Component\Messenger\Middleware\AddBusNameStampMiddleware->handle() symfony#7 /vagrant/vendor/symfony/messenger/MessageBus.php(70): Symfony\Component\Messenger\Middleware\TraceableMiddleware->handle() symfony#8 /vagrant/vendor/symfony/messenger/TraceableMessageBus.php(38): Symfony\Component\Messenger\MessageBus->dispatch() symfony#9 /vagrant/src/Messenger/MessageBus.php(37): Symfony\Component\Messenger\TraceableMessageBus->dispatch() symfony#10 /vagrant/vendor/symfony/mailer/Mailer.php(66): App\Messenger\MessageBus->dispatch() symfony#11 /vagrant/src/Mailer/Mailer.php(83): Symfony\Component\Mailer\Mailer->send() symfony#12 /vagrant/src/Mailer/Mailer.php(96): App\Mailer\Mailer->send() symfony#13 /vagrant/src/MessageHandler/Trading/StrategySubscriptionMessageHandler.php(118): App\Mailer\Mailer->sendEmail() symfony#14 /vagrant/src/MessageHandler/Trading/StrategySubscriptionMessageHandler.php(72): App\MessageHandler\Trading\StrategySubscriptionMessageHandler->handle() symfony#15 /vagrant/vendor/symfony/messenger/Middleware/HandleMessageMiddleware.php(152): App\MessageHandler\Trading\StrategySubscriptionMessageHandler->__invoke() symfony#16 /vagrant/vendor/symfony/messenger/Middleware/HandleMessageMiddleware.php(91): Symfony\Component\Messenger\Middleware\HandleMessageMiddleware->callHandler() symfony#17 /vagrant/vendor/symfony/messenger/Middleware/SendMessageMiddleware.php(71): Symfony\Component\Messenger\Middleware\HandleMessageMiddleware->handle() symfony#18 /vagrant/vendor/symfony/messenger/Middleware/FailedMessageProcessingMiddleware.php(34): Symfony\Component\Messenger\Middleware\SendMessageMiddleware->handle() symfony#19 /vagrant/vendor/symfony/messenger/Middleware/DispatchAfterCurrentBusMiddleware.php(68): Symfony\Component\Messenger\Middleware\FailedMessageProcessingMiddleware->handle() symfony#20 /vagrant/vendor/symfony/messenger/Middleware/RejectRedeliveredMessageMiddleware.php(41): Symfony\Component\Messenger\Middleware\DispatchAfterCurrentBusMiddleware->handle() symfony#21 /vagrant/vendor/symfony/messenger/Middleware/AddBusNameStampMiddleware.php(37): Symfony\Component\Messenger\Middleware\RejectRedeliveredMessageMiddleware->handle() symfony#22 /vagrant/vendor/symfony/messenger/Middleware/TraceableMiddleware.php(40): Symfony\Component\Messenger\Middleware\AddBusNameStampMiddleware->handle() symfony#23 /vagrant/vendor/symfony/messenger/MessageBus.php(70): Symfony\Component\Messenger\Middleware\TraceableMiddleware->handle() symfony#24 /vagrant/vendor/symfony/messenger/TraceableMessageBus.php(38): Symfony\Component\Messenger\MessageBus->dispatch() symfony#25 /vagrant/vendor/symfony/messenger/RoutableMessageBus.php(54): Symfony\Component\Messenger\TraceableMessageBus->dispatch() symfony#26 /vagrant/vendor/symfony/messenger/Worker.php(162): Symfony\Component\Messenger\RoutableMessageBus->dispatch() symfony#27 /vagrant/vendor/symfony/messenger/Worker.php(109): Symfony\Component\Messenger\Worker->handleMessage() symfony#28 /vagrant/vendor/symfony/messenger/Command/ConsumeMessagesCommand.php(238): Symfony\Component\Messenger\Worker->run() symfony#29 /vagrant/vendor/symfony/console/Command/Command.php(326): Symfony\Component\Messenger\Command\ConsumeMessagesCommand->execute() symfony#30 /vagrant/vendor/symfony/console/Application.php(1096): Symfony\Component\Console\Command\Command->run() symfony#31 /vagrant/vendor/symfony/framework-bundle/Console/Application.php(126): Symfony\Component\Console\Application->doRunCommand() symfony#32 /vagrant/vendor/symfony/console/Application.php(324): Symfony\Bundle\FrameworkBundle\Console\Application->doRunCommand() symfony#33 /vagrant/vendor/symfony/framework-bundle/Console/Application.php(80): Symfony\Component\Console\Application->doRun() symfony#34 /vagrant/vendor/symfony/console/Application.php(175): Symfony\Bundle\FrameworkBundle\Console\Application->doRun() symfony#35 /vagrant/vendor/symfony/runtime/Runner/Symfony/ConsoleApplicationRunner.php(49): Symfony\Component\Console\Application->run() symfony#36 /vagrant/vendor/autoload_runtime.php(29): Symfony\Component\Runtime\Runner\Symfony\ConsoleApplicationRunner->run() symfony#37 /vagrant/bin/console(11): require_once('...') symfony#38 {main} ``` TODO: - [x] Add test for retry logic when publishing messages Commits ------- f123370 [Messenger] [Amqp] Handle AMQPConnectionException when publishing a message.

Korbeil force-pushed the feature/automapper-component branch 6 times, most recently from 00042df to 393b11c Compare March 31, 2023 11:55

Korbeil force-pushed the feature/automapper-component branch 4 times, most recently from fdb92ec to d9f1d58 Compare April 10, 2023 13:57

Korbeil force-pushed the feature/automapper-component branch 9 times, most recently from 865f063 to 056388e Compare April 24, 2023 08:17

Add AutoMapper component

204c7a8

Korbeil force-pushed the feature/automapper-component branch from 056388e to 204c7a8 Compare September 25, 2023 11:20

Korbeil changed the base branch from 6.3 to 7.0 September 25, 2023 11:21

Korbeil mentioned this pull request Sep 26, 2023

[ObjectMapper] Object to Object mapper component symfony/symfony#51741

Merged

2 tasks

dunglas mentioned this pull request Sep 26, 2023

[AutoMapper] New component to automatically map a source object to a target object symfony/symfony#30248

Closed

Korbeil mentioned this pull request Apr 3, 2024

[RFC] ObjectMapper symfony/symfony#54476

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add AutoMapper component #1

Add AutoMapper component #1

Uh oh!

Korbeil commented Mar 28, 2023 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add AutoMapper component #1

Are you sure you want to change the base?

Add AutoMapper component #1

Uh oh!

Conversation

Korbeil commented Mar 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Usage

Other features

Context

Private properties

Nested Mapping

Circular Reference

Max Depth

Name Converter

Discriminator Mapping

Ignored

Type casting

Readonly properties & classes

Warmup mappers

History

Implementation

Normalizer Bridge

Things that needs to be done

Future consideration

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Korbeil commented Mar 28, 2023 •

edited

Loading