minor #21838 [Security] Document this variable in #[IsGranted] subject expression (lacatoire)

This PR was merged into the 8.1 branch.

Discussion
----------

[Security] Document `this` variable in `#[IsGranted]` subject expression

 This PR documents the new `this` variable available in `#[IsGranted]` subject expressions, introduced in Symfony 8.1.

  This allows accessing the controller/component instance directly, which is particularly useful with Live Components.

  Fixes #21836

Commits
-------

7690891 [Security] Document `this` variable in #[IsGranted] subject expression

Author: javiereguiluz

security/expressions.rst

@@ -193,13 +193,37 @@ You can also use the current request as the subject::
         // ...
     }
 
-Inside the subject's expression, you have access to two variables:
+Inside the subject's expression, you have access to these variables:
 
 ``request``
     The :ref:`Symfony Request <component-http-foundation-request>` object that
     represents the current request.
 ``args``
     An array of controller arguments that are passed to the controller.
+``this``
+    The controller instance itself, allowing access to its properties and methods.
+
+    .. versionadded:: 8.1
+
+        The ``this`` variable was introduced in Symfony 8.1.
+
+    This is useful when you need to access controller properties in the subject
+    expression::
+
+        use Symfony\Component\ExpressionLanguage\Expression;
+        use Symfony\Component\HttpFoundation\Response;
+        use Symfony\Component\Security\Http\Attribute\IsGranted;
+
+        class PostController
+        {
+            public string $defaultCategory = 'blog';
+
+            #[IsGranted('CATEGORY_ACCESS', subject: new Expression('this.defaultCategory'))]
+            public function index(): Response
+            {
+                // ...
+            }
+        }
 
 Additionally to expressions, the ``#[IsGranted]`` attribute also accepts
 closures that return a boolean value. The subject can also be a closure that