minor #10316 [Serializer] Cache the normalizer to use when possible (dunglas, javiereguiluz)

This PR was merged into the 4.1 branch.

Discussion
----------

[Serializer] Cache the normalizer to use when possible

symfony/symfony#27049

Commits
-------

3e2e30f Minor reword
8d6ca70 RST
8e09eeb RST
ccdf894 [Serializer] Cache the normalizer to use when possible

Author: javiereguiluz

components/serializer.rst

@@ -1295,6 +1295,32 @@ can use this simpler configuration:
             </class>
         </serializer>
 
+Performance
+-----------
+
+To figure which normalizer (or denormalizer) must be used to handle an object,
+the :class:`Symfony\\Component\\Serializer\\Serializer` class will call the
+:method:`Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface::supportsNormalization`
+(or :method:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface::supportsDenormalization`)
+of all registered normalizers (or denormalizers) in a loop.
+
+The result of these methods can vary depending on the object to serialize, the
+format and the context. That's why the result **is not cached** by default and
+can result in a significant performance bottleneck.
+
+However, most normalizers (and denormalizers) always return the same result when
+the object's type and the format are the same, so the result can be cached. To
+do so, make those normalizers (and denormalizers) implement the
+:class:`Symfony\\Component\\Serializer\\Normalizer\\CacheableSupportsMethodInterface`
+and return ``true`` when
+:method:`Symfony\\Component\\Serializer\\Normalizer\\CacheableSupportsMethodInterface::hasCacheableSupportsMethod`
+is called.
+
+ .. note::
+    
+    All built-in :ref:`normalizers and denormalizers <component-serializer-normalizers>`
+    as well the ones included in `API Platform`_ natively implement this interface.
+
 Learn more
 ----------
 
@@ -1304,6 +1330,11 @@ Learn more
 
     /serializer
 
+.. seealso::
+
+    Normalizers for the Symfony Serializer Component supporting popular web API formats
+    (JSON-LD, GraphQL, HAL and JSONAPI) are available as part of the `API Platform`_ project.
+
 .. seealso::
 
     A popular alternative to the Symfony Serializer Component is the third-party
@@ -1320,3 +1351,4 @@ Learn more
 .. _CSV: https://tools.ietf.org/html/rfc4180
 .. _`RFC 7807`: https://tools.ietf.org/html/rfc7807
 .. _`Value Objects`: https://en.wikipedia.org/wiki/Value_object
+.. _`API Platform`: https://api-platform.com