[Serializer] Introduce named serializers #56823

HypeMC · 2024-05-20T06:40:59Z

Q	A
Branch?	7.2
Bug fix?	no
New feature?	yes
Deprecations?	no
Issues	-
License	MIT

The idea behind this PR is to allow configuring multiple serializer instances with different default contexts, name converters, and sets of normalizers and encoders. This is useful when your application is communicating with multiple APIs, each with different rules. Similar ideas have been mentioned before.

serializer:
  named_serializers:
    api1:
      name_converter: 'serializer.name_converter.camel_case_to_snake_case'
      default_context:
        enable_max_depth: true
    api2:
      default_context:
        enable_max_depth: false

The different serializers can be injected using named aliases:

#[AsController]
class HomeController
{
    #[Route('/', name: 'app_home')]
    public function index(
        SerializerInterface $serializer,     // Default serializer
        SerializerInterface $api1Serializer, // api1 serializer
        #[Target('api2.serializer')]         // api2 serializer
        SerializerInterface $someName,
    ) {
        // ...
    }
}

Multiple normalizer/encoder instances with different arguments are created as child services of the default ones. I also ensured that the same normalizer/encoder instances are reused between different serializers that have the same default context and name converter to minimize the number of child services created.

Custom normalizers/encoders can target specific serializers using the serializer tag attribute:

get_set_method_normalizer:
    class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer
    autoconfigure: false # This is needed so that it's not included in the default serializer
    tags:
        # single serializer
        - serializer.normalizer: { serializer: 'api1' }
        # or multiple ones
        - serializer.normalizer: { serializer: [ 'api1', 'api2' ] }
        # use * to include the service in all serializers including the default one
        - serializer.normalizer: { serializer: '*' }

For BC reasons, not setting the serializer tag attribute is the same as setting it to the default one:

    tags:
        - serializer.normalizer
        # same as
        - serializer.normalizer: { serializer: 'default' }

The profiler has been updated to support multiple serializer instances:

All normalizers/encoders are tagged with additional named serializer specific tags to help with debugging. To get the priority of normalizers/encoders for a certain serializer, use the serializer.normalizer.<name> or serializer.encoder.<name> tags:

$ bin/console debug:container --tag serializer.normalizer.default
Symfony Container Services Tagged with "serializer.normalizer.default" Tag
==========================================================================

 ------------------------------------------------- ---------- ------------------------------------------------------------------------------------------- 
  Service ID                                        priority   Class name                                                                                 
 ------------------------------------------------- ---------- ------------------------------------------------------------------------------------------- 
  serializer.denormalizer.unwrapping                1000       Symfony\Component\Serializer\Normalizer\UnwrappingDenormalizer                             
  serializer.normalizer.flatten_exception           -880       Symfony\Component\Messenger\Transport\Serialization\Normalizer\FlattenExceptionNormalizer  
  ...
  serializer.denormalizer.array                     -990       Symfony\Component\Serializer\Normalizer\ArrayDenormalizer                                  
  serializer.normalizer.object                      -1000      Symfony\Component\Serializer\Normalizer\ObjectNormalizer                                   
 ------------------------------------------------- ---------- ------------------------------------------------------------------------------------------- 

$ bin/console debug:container --tag serializer.normalizer.api1

Symfony Container Services Tagged with "serializer.normalizer.api1" Tag
=======================================================================

 ------------------------------------------------- ---------- ------------------------------------------------------------------------------------------- 
  Service ID                                        priority   Class name                                                                                 
 ------------------------------------------------- ---------- ------------------------------------------------------------------------------------------- 
  serializer.denormalizer.unwrapping                1000       Symfony\Component\Serializer\Normalizer\UnwrappingDenormalizer                             
  get_set_method_normalizer                                    Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer                             
  serializer.normalizer.flatten_exception           -880       Symfony\Component\Messenger\Transport\Serialization\Normalizer\FlattenExceptionNormalizer  
  ...
  serializer.denormalizer.array                     -990       Symfony\Component\Serializer\Normalizer\ArrayDenormalizer                                  
  serializer.normalizer.object                      -1000      Symfony\Component\Serializer\Normalizer\ObjectNormalizer                                   
 ------------------------------------------------- ---------- ------------------------------------------------------------------------------------------- 

$ bin/console debug:container --tag serializer.normalizer

Symfony Container Services Tagged with "serializer.normalizer" Tag
==================================================================

 ------------------------------------------------- ---------- ---------- ----------------- ------------------------------------------------------------------------------------------- 
  Service ID                                        standard   priority   serializer        Class name                                                                                 
 ------------------------------------------------- ---------- ---------- ----------------- ------------------------------------------------------------------------------------------- 
  serializer.denormalizer.unwrapping                1          1000                         Symfony\Component\Serializer\Normalizer\UnwrappingDenormalizer                             
  get_set_method_normalizer                                               ["api1","api2"]   Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer                             
  serializer.normalizer.flatten_exception           1          -880                         Symfony\Component\Messenger\Transport\Serialization\Normalizer\FlattenExceptionNormalizer  
  ...
  serializer.denormalizer.array                     1          -990                         Symfony\Component\Serializer\Normalizer\ArrayDenormalizer                                  
  serializer.normalizer.object                      1          -1000                        Symfony\Component\Serializer\Normalizer\ObjectNormalizer                                   
 ------------------------------------------------- ---------- ---------- ----------------- -------------------------------------------------------------------------------------------

Since Symfony comes with some pre-registered normalizers and encoders, I added options to exclude those in case someone wants to use only custom ones:

serializer:
  named_serializers:
    api1:
      include_built_in_normalizers: false
      include_built_in_encoders: true

      name_converter: 'serializer.name_converter.camel_case_to_snake_case'
      default_context:
        enable_max_depth: true

TBH, I have doubts about the usefulness of this, please let me know your thoughts.

I've split the PR into two commits to ease reviewing:

the first commit only rearranges the SerializerPass without adding any features
the second commit implements the feature

This PR was merged into the 7.1 branch. Discussion ---------- Fix singular phpdoc | Q | A | ------------- | --- | Branch? | 7.1 | Bug fix? | no | New feature? | no  | Deprecations? | no  | Issues | Fix #...  | License | MIT (Found while reviewing #56823) Commits ------- e0f6258 Fix singular phpdoc

dunglas · 2024-08-13T09:39:00Z

Good work! This will help improve performance and reduce the complexity of projects needing multiple serializers to deal with different contexts (ex: serializing data exposed through a public API and deserializing data coming from a third-party service). I'm +1 to merge this.

autoconfigure: false # This is needed so that it's not included in the default serializer

Maybe could we tweak the autoconfigurator to automatically exclude definitions already having an explicit serializer tag? This will improve the DX a bit.

src/Symfony/Component/DependencyInjection/ContainerBuilder.php

mtarld

That's a really great addition!

Just a quick question, why mixing up standard and default as name describing default stuff? Shouldn't we stick to default only?

…hild()` shortcut method (HypeMC) This PR was merged into the 7.2 branch. Discussion ---------- [DependencyInjection] Add `ContainerBuilder::registerChild()` shortcut method | Q | A | ------------- | --- | Branch? | 7.2 | Bug fix? | no | New feature? | yes | Deprecations? | no | Issues | - | License | MIT Extracted from #56823 as suggested in #56823 (comment) Commits ------- 7ba430c [DependencyInjection] Add `ContainerBuilder::registerChild()` shortcut method

stof · 2024-08-14T17:03:14Z

Reusing the same normalizer instances is a very bad idea as it would break for any normalizer implementing any of the *Aware interfaces of the component (as instantiating the second serializer would replace the instance that those shared normalizers are aware of)

src/Symfony/Bundle/WebProfilerBundle/Resources/views/Collector/serializer.html.twig

src/Symfony/Component/Serializer/Debug/TraceableNormalizer.php

src/Symfony/Component/Serializer/Debug/TraceableSerializer.php

HypeMC · 2024-08-15T22:58:54Z

Rebase needed after #58013

@chalasr Done

chalasr

Nice work

chalasr · 2024-09-18T15:57:29Z

fabbot's suggestion looks legit, can you apply it?

HypeMC · 2024-09-18T16:06:23Z

fabbot's suggestion looks legit, can you apply it?

@chalasr Done, https://github.com/symfony/symfony/compare/d9ceb8521073610eff9d338eea2a5558d3edbbc5..03534988f5e9cef66798ab9b36d38cdf3770e671

fabpot · 2024-09-19T07:32:53Z

src/Symfony/Component/Serializer/DependencyInjection/SerializerPass.php

+                    $names = array_unique(['default', ...$serializerNames]);
+                }
+
+                if ($tag['built-in'] ?? false) {


To be consistent with the code base (like extended_type for Forms), I think it should be:

Suggested change

if ($tag['built-in'] ?? false) {

if ($tag['built_in'] ?? false) {

@fabpot Done, https://github.com/symfony/symfony/compare/aee8227eddd18e78b95b177ad5ea50d38c2c153a..ca834e5375c55edc7960417114ca3d02bd9f9845

fabpot · 2024-09-19T09:07:51Z

Thank you @HypeMC.

Named serializers were introduced in symfony#56823 and they work great. We noticed a small bug when using custom name convertors. The MimeMessageNormalizer holds a reference to `serializer.normalizer.property`. But when using named serializers, it would use the specific child normalizer instead. With this change, we fix this problem for any service that starts with `serializer.normalizer.`.

HypeMC requested a review from dunglas as a code owner May 20, 2024 06:41

carsonbot added Status: Needs Review Feature Serializer labels May 20, 2024

This comment has been minimized.

Sign in to view

carsonbot added this to the 7.1 milestone May 20, 2024

HypeMC force-pushed the named-serializers branch 2 times, most recently from ecd355d to 63409d5 Compare May 20, 2024 11:52

OskarStark modified the milestones: 7.1, 7.2 May 20, 2024

alamirault mentioned this pull request May 20, 2024

Fix singular phpdoc #56828

Merged

HypeMC force-pushed the named-serializers branch from 63409d5 to fecf52b Compare June 6, 2024 23:18

HypeMC force-pushed the named-serializers branch 3 times, most recently from 3e3ef44 to f1c17d7 Compare August 12, 2024 19:27

dunglas requested changes Aug 13, 2024

View reviewed changes

src/Symfony/Component/DependencyInjection/ContainerBuilder.php Outdated Show resolved Hide resolved

carsonbot added Status: Needs Work and removed Status: Needs Review labels Aug 13, 2024

HypeMC mentioned this pull request Aug 13, 2024

[DependencyInjection] Add ContainerBuilder::registerChild() shortcut method #58004

Merged

dunglas approved these changes Aug 13, 2024

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Work labels Aug 13, 2024

mtarld approved these changes Aug 14, 2024

View reviewed changes

HypeMC force-pushed the named-serializers branch from f1c17d7 to 764b46f Compare August 14, 2024 17:11

stof requested changes Aug 14, 2024

View reviewed changes

HypeMC force-pushed the named-serializers branch from 7d850a0 to e3b4b23 Compare August 15, 2024 22:57

chalasr approved these changes Aug 15, 2024

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Work labels Aug 15, 2024

OskarStark requested a review from stof August 16, 2024 15:16

carsonbot added Status: Needs Review and removed Status: Reviewed labels Aug 16, 2024

HypeMC force-pushed the named-serializers branch 2 times, most recently from 6b1ee4d to d9ceb85 Compare September 18, 2024 15:05

HypeMC force-pushed the named-serializers branch from d9ceb85 to 0353498 Compare September 18, 2024 16:05

fabpot requested changes Sep 19, 2024

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Needs Review labels Sep 19, 2024

HypeMC force-pushed the named-serializers branch 2 times, most recently from aee8227 to ca834e5 Compare September 19, 2024 09:01

fabpot approved these changes Sep 19, 2024

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Work labels Sep 19, 2024

[Serializer] Introduce named serializers

29bd8ce

fabpot force-pushed the named-serializers branch from ca834e5 to 29bd8ce Compare September 19, 2024 09:07

fabpot merged commit ce228d3 into symfony:7.2 Sep 19, 2024
4 of 6 checks passed

fabpot mentioned this pull request Sep 19, 2024

[Serializer] Introduce named serializers symfony/symfony-docs#20235

Closed

HypeMC deleted the named-serializers branch September 19, 2024 09:17

fabpot mentioned this pull request Oct 27, 2024

Release v7.2.0-BETA1 #58686

Merged

ruudk mentioned this pull request Jan 27, 2025

[Serializer] Named serializer should get correct normalizer instance #59627

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Serializer] Introduce named serializers #56823

[Serializer] Introduce named serializers #56823

HypeMC commented May 20, 2024 •

edited

Loading

This comment has been minimized.

dunglas commented Aug 13, 2024

mtarld left a comment

stof commented Aug 14, 2024

HypeMC commented Aug 15, 2024

chalasr left a comment

chalasr commented Sep 18, 2024

HypeMC commented Sep 18, 2024

fabpot Sep 19, 2024

HypeMC Sep 19, 2024

fabpot commented Sep 19, 2024

	if ($tag['built-in'] ?? false) {
	if ($tag['built_in'] ?? false) {

[Serializer] Introduce named serializers #56823

[Serializer] Introduce named serializers #56823

Conversation

HypeMC commented May 20, 2024 • edited Loading

This comment has been minimized.

dunglas commented Aug 13, 2024

mtarld left a comment

Choose a reason for hiding this comment

stof commented Aug 14, 2024

HypeMC commented Aug 15, 2024

chalasr left a comment

Choose a reason for hiding this comment

chalasr commented Sep 18, 2024

HypeMC commented Sep 18, 2024

fabpot Sep 19, 2024

Choose a reason for hiding this comment

HypeMC Sep 19, 2024

Choose a reason for hiding this comment

fabpot commented Sep 19, 2024

HypeMC commented May 20, 2024 •

edited

Loading