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

CHANGELOG.md

@@ -9,6 +9,8 @@ CHANGELOG
 * added an optional `default_constructor_arguments` option of context to specify a default data in
   case the object is not initializable by its constructor because of data missing
 * added optional `bool $escapeFormulas = false` argument to `CsvEncoder::__construct`
+* added `AbstractObjectNormalizer::setMaxDepthHandler` to set a handler to call when the configured
+  maximum depth is reached
 
 4.0.0
 -----

Normalizer/AbstractObjectNormalizer.php

@@ -41,6 +41,11 @@ abstract class AbstractObjectNormalizer extends AbstractNormalizer
     private $attributesCache = array();
     private $cache = array();
 
+    /**
+     * @var callable|null
+     */
+    private $maxDepthHandler;
+
     /**
      * @var ClassDiscriminatorResolverInterface|null
      */
@@ -86,11 +91,15 @@ public function normalize($object, $format = null, array $context = array())
         $attributesMetadata = $this->classMetadataFactory ? $this->classMetadataFactory->getMetadataFor($class)->getAttributesMetadata() : null;
 
         foreach ($attributes as $attribute) {
-            if (null !== $attributesMetadata && $this->isMaxDepthReached($attributesMetadata, $class, $attribute, $context)) {
+            $maxDepthReached = false;
+            if (null !== $attributesMetadata && ($maxDepthReached = $this->isMaxDepthReached($attributesMetadata, $class, $attribute, $context)) && !$this->maxDepthHandler) {
                 continue;
             }
 
             $attributeValue = $this->getAttributeValue($object, $attribute, $format, $context);
+            if ($maxDepthReached) {
+                $attributeValue = \call_user_func($this->maxDepthHandler, $attributeValue);
+            }
 
             if (isset($this->callbacks[$attribute])) {
                 $attributeValue = call_user_func($this->callbacks[$attribute], $attributeValue);
@@ -204,6 +213,14 @@ abstract protected function extractAttributes($object, $format = null, array $co
      */
     abstract protected function getAttributeValue($object, $attribute, $format = null, array $context = array());
 
+    /**
+     * Sets an handler function that will be called when the max depth is reached.
+     */
+    public function setMaxDepthHandler(?callable $handler): void
+    {
+        $this->maxDepthHandler = $handler;
+    }
+
     /**
      * {@inheritdoc}
      */

Tests/Normalizer/ObjectNormalizerTest.php

@@ -613,6 +613,27 @@ public function testMaxDepth()
         );
 
         $this->assertEquals($expected, $result);
+
+        $expected = array(
+            'bar' => null,
+            'foo' => 'level1',
+            'child' => array(
+                'bar' => null,
+                'foo' => 'level2',
+                'child' => array(
+                    'bar' => null,
+                    'child' => null,
+                    'foo' => 'handler',
+                ),
+            ),
+        );
+
+        $this->normalizer->setMaxDepthHandler(function ($obj) {
+            return 'handler';
+        });
+
+        $result = $serializer->normalize($level1, null, array(ObjectNormalizer::ENABLE_MAX_DEPTH => true));
+        $this->assertEquals($expected, $result);
     }
 
     /**