feature #26108 [Serializer] Add a MaxDepth handler (dunglas)

This PR was squashed before being merged into the 4.1-dev branch (closes #26108).

Discussion
----------

[Serializer] Add a MaxDepth handler

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes <!-- don't forget to update src/**/CHANGELOG.md files -->
| BC breaks?    | no
| Deprecations? | no <!-- don't forget to update UPGRADE-*.md files -->
| Tests pass?   | yes
| Fixed tickets | api-platform/core#1130, api-platform/core#1528, api-platform/core#1528 <!-- #-prefixed issue number(s), if any -->
| License       | MIT
| Doc PR        | todo <!--highly recommended for new features-->

Sometimes, instead of just stopping the serialization process when the configured max depth is reached, it can be interesting to let the user return something (like returning the identifier of the entity to stop manually the serialization process).

This PR also makes the max depth handling more similar to circular references handling (that already has the possibility to set a handler).

Commits
-------

ed975c764b [Serializer] Add a MaxDepth handler

Author: fabpot

DependencyInjection/Configuration.php

@@ -731,6 +731,7 @@ private function addSerializerSection(ArrayNodeDefinition $rootNode)
                         ->booleanNode('enable_annotations')->{!class_exists(FullStack::class) && class_exists(Annotation::class) ? 'defaultTrue' : 'defaultFalse'}()->end()
                         ->scalarNode('name_converter')->end()
                         ->scalarNode('circular_reference_handler')->end()
+                        ->scalarNode('max_depth_handler')->end()
                         ->arrayNode('mapping')
                             ->addDefaultsIfNotSet()
                             ->fixXmlConfig('path')

DependencyInjection/FrameworkExtension.php

@@ -1275,6 +1275,10 @@ private function registerSerializerConfiguration(array $config, ContainerBuilder
         if (isset($config['circular_reference_handler']) && $config['circular_reference_handler']) {
             $container->getDefinition('serializer.normalizer.object')->addMethodCall('setCircularReferenceHandler', array(new Reference($config['circular_reference_handler'])));
         }
+
+        if ($config['max_depth_handler'] ?? false) {
+            $container->getDefinition('serializer.normalizer.object')->addMethodCall('setMaxDepthHandler', array(new Reference($config['max_depth_handler'])));
+        }
     }
 
     private function registerPropertyInfoConfiguration(array $config, ContainerBuilder $container, XmlFileLoader $loader)

Resources/config/schema/symfony-1.0.xsd

@@ -239,6 +239,7 @@
         <xsd:attribute name="cache" type="xsd:string" />
         <xsd:attribute name="enable-annotations" type="xsd:boolean" />
         <xsd:attribute name="name-converter" type="xsd:string" />
+        <xsd:attribute name="max-depth-handler" type="xsd:string" />
     </xsd:complexType>
 
     <xsd:complexType name="property_info">

Tests/DependencyInjection/Fixtures/php/full.php

@@ -68,6 +68,7 @@
         'enabled' => true,
         'enable_annotations' => true,
         'name_converter' => 'serializer.name_converter.camel_case_to_snake_case',
+        'max_depth_handler' => 'my.max.depth.handler',
     ),
     'property_info' => true,
     'ide' => 'file%%link%%format',

Tests/DependencyInjection/Fixtures/xml/full.xml

@@ -41,7 +41,7 @@
         </framework:translator>
         <framework:validation enabled="true" />
         <framework:annotations cache="file" debug="true" file-cache-dir="%kernel.cache_dir%/annotations" />
-        <framework:serializer enabled="true" enable-annotations="true" name-converter="serializer.name_converter.camel_case_to_snake_case" />
+        <framework:serializer enabled="true" enable-annotations="true" name-converter="serializer.name_converter.camel_case_to_snake_case" max-depth-handler="my.max.depth.handler" />
         <framework:property-info />
     </framework:config>
 </container>

Tests/DependencyInjection/Fixtures/yml/full.yml

@@ -54,6 +54,7 @@ framework:
          enabled:        true
          enable_annotations: true
          name_converter: serializer.name_converter.camel_case_to_snake_case
+         max_depth_handler: my.max.depth.handler
     property_info: ~
     ide: file%%link%%format
     request:

Tests/DependencyInjection/FrameworkExtensionTest.php

@@ -807,6 +807,7 @@ public function testSerializerEnabled()
         $this->assertNull($container->getDefinition('serializer.mapping.class_metadata_factory')->getArgument(1));
         $this->assertEquals(new Reference('serializer.name_converter.camel_case_to_snake_case'), $container->getDefinition('serializer.normalizer.object')->getArgument(1));
         $this->assertEquals(new Reference('property_info', ContainerBuilder::IGNORE_ON_INVALID_REFERENCE), $container->getDefinition('serializer.normalizer.object')->getArgument(3));
+        $this->assertEquals(array('setMaxDepthHandler', array(new Reference('my.max.depth.handler'))), $container->getDefinition('serializer.normalizer.object')->getMethodCalls()[0]);
     }
 
     public function testRegisterSerializerExtractor()