Merge branch '7.3' into 7.4

* 7.3:
  [Form] Document conditional constraints in forms without classes
  [Serializer] Update the getSupportedTypes() docs of custom serializers

Author: javiereguiluz

form/without_class.rst

@@ -177,3 +177,41 @@ in your controller::
         ->add('firstName', TextType::class)
         ->add('lastName', TextType::class)
         ->getForm();
+
+Conditional Constraints
+~~~~~~~~~~~~~~~~~~~~~~~
+
+It's possible to define field constraints that depend on the value of other
+fields (e.g. a field must not be blank when another field has a certain value).
+To achieve this, use the ``expression`` option of the
+:doc:`When constraint </reference/constraints/When>` to reference the other field::
+
+    $builder
+        ->add('how_did_you_hear', ChoiceType::class, [
+            'required' => true,
+            'label' => 'How did you hear about us?',
+            'choices' => [
+                'Search engine' => 'search_engine',
+                'Friends' => 'friends',
+                'Other' => 'other',
+            ],
+            'expanded' => true,
+            'constraints' => [
+                new Assert\NotBlank(),
+            ]
+        ])
+
+        // this field is only required if the value of the 'how_did_you_hear' field is 'other'
+        ->add('other_text', TextType::class, [
+            'required' => false,
+            'label' => 'Please specify',
+            'constraints' => [
+                new Assert\When(
+                    expression: 'this.getParent().get("how_did_you_hear").getData() == "other"',
+                    constraints: [
+                        new Assert\NotBlank(),
+                    ],
+                )
+            ],
+        ])
+    ;

serializer/custom_normalizer.rst

@@ -126,41 +126,32 @@ If you're not using ``autoconfigure``, you have to tag the service with
             ;
         };
 
-Performance of Normalizers/Denormalizers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-Additionally, both
-:class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface`
-and :class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface`
-contain the ``getSupportedTypes()`` method. This method allows normalizers or
-denormalizers to declare the type of objects they can handle, and whether they
-are cacheable. With this info, even if the ``supports*()`` call is not cacheable,
-the Serializer can skip a ton of method calls to ``supports*()`` improving
-performance substantially in some cases.
+Improving Performance of Normalizers/Denormalizers
+--------------------------------------------------
+
+Both :class:Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface
+and :class:Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface
+define a ``getSupportedTypes()`` method to declare which types they support and
+whether their ``supports*()`` result can be cached.
+
+This **does not** cache the actual normalization or denormalization result. It
+only **caches the decision** of whether a normalizer supports a given type, allowing
+the Serializer to skip unnecessary ``supports*()`` calls and improve performance.
 
 The ``getSupportedTypes()`` method should return an array where the keys
-represent the supported types, and the values indicate whether the result of
-the ``supports*()`` method call can be cached or not. The format of the
-returned array is as follows:
+represent the supported types, and the values indicate whether the result of the
+corresponding ``supports*()`` call can be cached. The array format is as follows:
 
 #. The special key ``object`` can be used to indicate that the normalizer or
    denormalizer supports any classes or interfaces.
 #. The special key ``*`` can be used to indicate that the normalizer or
-   denormalizer might support any types.
-#. The other keys in the array should correspond to specific types that the
-   normalizer or denormalizer supports.
-#. The values associated with each type should be a boolean indicating if the
-   result of the ``supports*()`` method call for that type can be cached or not.
-   A value of ``true`` means that the result is cacheable, while ``false`` means
-   that the result is not cacheable.
-#. A ``null`` value for a type means that the normalizer or denormalizer does
-   not support that type.
+   denormalizer might support any type.
+#. Other keys should correspond to specific types that the normalizer or
+   denormalizer supports.
+#. The values should be booleans indicating whether the result of the
+   ``supports*()`` call for that type is cacheable. Use ``true`` if the result
+   can be cached, ``false`` if it cannot.
+#. A ``null`` value means the normalizer or denormalizer does not support that type.
 
 Here is an example of how to use the ``getSupportedTypes()`` method::
 
@@ -173,9 +164,9 @@ Here is an example of how to use the ``getSupportedTypes()`` method::
         public function getSupportedTypes(?string $format): array
         {
             return [
-                'object' => null,             // Doesn't support any classes or interfaces
-                '*' => false,                 // Supports any other types, but the result is not cacheable
-                MyCustomClass::class => true, // Supports MyCustomClass and result is cacheable
+                'object' => null,             // doesn't support any classes or interfaces
+                '*' => false,                 // supports any other types, but the decision is not cacheable
+                MyCustomClass::class => true, // supports MyCustomClass and decision is cacheable
             ];
         }
     }