[HttpKernel] Warn about custom types in MapRequestPayload exposing cl…

controller.rst

@@ -622,6 +622,23 @@ using the ``type`` option of the attribute::
 
     The ``type`` option of ``#[MapRequestPayload]`` was introduced in Symfony 7.1.
 
+.. warning::
+
+    When using custom types (e.g. enums) in your DTO properties, denormalization
+    errors may expose internal class names to the end user. To avoid leaking
+    implementation details, use built-in PHP types (``string``, ``int``, etc.)
+    and validate the values with constraints::
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        final class OrderDto
+        {
+            public function __construct(
+                #[Assert\Choice(callback: [OrderStatus::class, 'values'])]
+                public readonly string $status,
+            ) {}
+        }
+
 .. _controller_map-uploaded-file:
 
 Mapping Uploaded Files