From 8715665642d67a087b9ec685ab2289e3839bb074 Mon Sep 17 00:00:00 2001
From: Santiago San Martin <sanmartindev@gmail.com>
Date: Tue, 3 Jun 2025 23:04:40 -0300
Subject: [PATCH] [HttpFoundation] Add documentation for #[IsSignatureValid]
 attribute with usage examples and options

---
 routing.rst | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/routing.rst b/routing.rst
index bf3946b343d..0e6667d7271 100644
--- a/routing.rst
+++ b/routing.rst
@@ -3031,6 +3031,104 @@ If you need to know the reason why a signed URI is invalid, you can use the
     Support for :doc:`Symfony Clock </components/clock>` in ``UriSigner`` was
     introduced in Symfony 7.3.
 
+Another way to validate incoming requests is to use the ``#[IsSignatureValid]`` attribute.
+
+In the following example, all incoming requests to this controller action will be verified for
+a valid signature. If the signature is missing or invalid,
+a **404 Not Found** response will be returned by default:
+
+.. code-block:: php-attributes
+
+    // src/Controller/SomeController.php
+    // ...
+
+    use App\Security\Attribute\IsSignatureValid;
+
+    #[IsSignatureValid]
+    public function someAction(): Response
+    {
+        // ...
+    }
+
+
+You can customize the failure behavior by changing the HTTP status code returned
+when validation fails, using the ``validationFailedStatusCode`` argument::
+
+
+    // src/Controller/SomeController.php
+    // ...
+
+    use App\Security\Attribute\IsSignatureValid;
+
+    #[IsSignatureValid(validationFailedStatusCode: 401)]
+    public function someAction(): Response
+    {
+        // ...
+    }
+
+To restrict signature validation to specific HTTP methods,
+use the ``methods`` argument. This can be a string or an array of methods::
+
+    // Only validate POST requests
+    #[IsSignatureValid(methods: 'POST')]
+    public function createItem(): Response
+    {
+        // ...
+    }
+
+    // Validate both POST and PUT requests
+    #[IsSignatureValid(methods: ['POST', 'PUT'])]
+    public function updateItem(): Response
+    {
+        // ...
+    }
+
+If you prefer to throw an exception instead of returning a response,
+pass ``throw: true``. This is useful when you want to handle the failure globally
+(e.g., via an exception listener)::
+
+    // src/Controller/SomeController.php
+    // ...
+
+    use App\Security\Attribute\IsSignatureValid;
+
+    #[IsSignatureValid(throw: true)]
+    public function someAction(): Response
+    {
+        // ...
+    }
+
+You can also apply ``#[IsSignatureValid]`` at the controller class level.
+This way, all actions within the controller will automatically
+be protected by signature validation::
+
+    // src/Controller/SecureController.php
+    // ...
+
+    use App\Security\Attribute\IsSignatureValid;
+
+    #[IsSignatureValid]
+    class SecureController extends AbstractController
+    {
+        public function index(): Response
+        {
+            // ...
+        }
+
+        public function submit(): Response
+        {
+            // ...
+        }
+    }
+
+
+This attribute provides a declarative way to enforce request signature validation directly
+at the controller level, helping to keep your security logic consistent and maintainable.
+
+.. versionadded:: 7.4
+
+    The ``#[IsSignatureValid]`` attribute was introduced in Symfony 7.4.
+
 Troubleshooting
 ---------------