symfony · nicolas-grekas · Jan 2, 2024 · Oct 10, 2023
@@ -17,6 +17,12 @@
 #[\Attribute(\Attribute::TARGET_CLASS)]
 class AsCommand
 {
+    /**
+     * @param string      $name        The name of the command, used when calling it (i.e. "cache:clear")
+     * @param string|null $description The description of the command, displayed with the help page
+     * @param string[]    $aliases     The list of aliases of the command. The command will be executed when using one of them (i.e. "cache:clean")
+     * @param bool        $hidden      If true, the command won't be shown when listing all the available commands, but it can still be run as any other command
+     */
     public function __construct(
         public string $name,
         public ?string $description = null,

diff --git a/src/Symfony/Component/EventDispatcher/Attribute/AsEventListener.php b/src/Symfony/Component/EventDispatcher/Attribute/AsEventListener.php
@@ -19,6 +19,12 @@
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 class AsEventListener
 {
+    /**
+     * @param string|null $event      The event name to listen to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same event
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         public ?string $event = null,
         public ?string $method = null,

@@ -20,6 +20,10 @@
 #[\Attribute(\Attribute::TARGET_PARAMETER)]
 class CurrentUser extends ValueResolver
 {
+    /**
+     * @param bool   $disabled Whether this value resolver is disabled, which allows to enable a value resolver globally while disabling it in specific cases
+     * @param string $resolver The class name of the resolver to use
+     */
     public function __construct(bool $disabled = false, string $resolver = UserValueResolver::class)
     {
         parent::__construct($resolver, $disabled);

@@ -14,38 +14,27 @@
 use Symfony\Component\ExpressionLanguage\Expression;
 
 /**
+ * Checks if user has permission to access to some resource using security roles and voters.
+ *
+ * @see https://symfony.com/doc/current/security.html#roles
+ *
  * @author Ryan Weaver <ryan@knpuniversity.com>
  */
 #[\Attribute(\Attribute::IS_REPEATABLE | \Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_FUNCTION)]
 final class IsGranted
 {
+    /**
+     * @param string|Expression            $attribute     The attribute that will be checked against a given authentication token and optional subject
+     * @param array|string|Expression|null $subject       An optional subject - e.g. the current object being voted on
+     * @param string|null                  $message       A custom message when access is not granted
+     * @param int|null                     $statusCode    If set, will throw HttpKernel's HttpException with the given $statusCode; if null, Security\Core's AccessDeniedException will be used
+     * @param int|null                     $exceptionCode If set, will add the exception code to thrown exception
+     */
     public function __construct(
-        /**
-         * Sets the first argument that will be passed to isGranted().
-         */
         public string|Expression $attribute,
-
-        /**
-         * Sets the second argument passed to isGranted().
-         *
-         * @var array<string|Expression>|string|Expression|null
-         */
         public array|string|Expression|null $subject = null,
-
-        /**
-         * The message of the exception - has a nice default if not set.
-         */
         public ?string $message = null,
-
-        /**
-         * If set, will throw HttpKernel's HttpException with the given $statusCode.
-         * If null, Security\Core's AccessDeniedException will be used.
-         */
         public ?int $statusCode = null,
-
-        /**
-         * If set, will add the exception code to thrown exception.
-         */
         public ?int $exceptionCode = null,
     ) {
     }

@@ -22,7 +22,10 @@ class Context
     private array $groups;
 
     /**
-     * @param string|string[] $groups
+     * @param array<string, mixed> $context                The common context to use when serializing or deserializing
+     * @param array<string, mixed> $normalizationContext   The context to use when serializing
+     * @param array<string, mixed> $denormalizationContext The context to use when deserializing
+     * @param string|string[]      $groups                 The groups to use when serializing or deserializing
      *
      * @throws InvalidArgumentException
      */

@@ -19,6 +19,12 @@
 #[\Attribute(\Attribute::TARGET_CLASS)]
 class DiscriminatorMap
 {
+    /**
+     * @param string                      $typeProperty The property holding the type discriminator
+     * @param array<string, class-string> $mapping      The mapping between types and classes (i.e. ['admin_user' => AdminUser::class])
+     *
+     * @throws InvalidArgumentException
+     */
     public function __construct(
         private readonly string $typeProperty,
         private readonly array $mapping,

@@ -25,7 +25,7 @@ class Groups
     private readonly array $groups;
 
     /**
-     * @param string|string[] $groups
+     * @param string|string[] $groups The groups to define on the attribute target
      */
     public function __construct(string|array $groups)
     {

@@ -19,6 +19,9 @@
 #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY)]
 class MaxDepth
 {
+    /**
+     * @param int $maxDepth The maximum serialization depth
+     */
     public function __construct(private readonly int $maxDepth)
     {
         if ($maxDepth <= 0) {

@@ -19,6 +19,9 @@
 #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY)]
 class SerializedName
 {
+    /**
+     * @param string $serializedName The name of the property as it will be serialized
+     */
     public function __construct(private readonly string $serializedName)
     {
         if ('' === $serializedName) {

@@ -23,6 +23,9 @@ class SerializedPath
 {
     private PropertyPath $serializedPath;
 
+    /**
+     * @param string $serializedPath A path using a valid PropertyAccess syntax where the value is stored in a normalized representation
+     */
     public function __construct(string $serializedPath)
     {
         try {

@@ -14,13 +14,22 @@
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
 
 /**
+ * Defines a listener for the "announce" event of a workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 final class AsAnnounceListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $transition The transition name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same transition
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $transition = null,

@@ -14,13 +14,22 @@
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
 
 /**
+ * Defines a listener for the "completed" event of a workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 final class AsCompletedListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $transition The transition name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same transition
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $transition = null,

@@ -14,13 +14,22 @@
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
 
 /**
+ * Defines a listener for the "enter" event of a workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 final class AsEnterListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $place      The place name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same place
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $place = null,

@@ -14,13 +14,22 @@
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
 
 /**
+ * Defines a listener for the "entered" event of a workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 final class AsEnteredListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $place      The place name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same place
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $place = null,

@@ -14,13 +14,22 @@
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
 
 /**
+ * Defines a listener for a guard event of a workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 final class AsGuardListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $transition The transition name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same transition
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $transition = null,

@@ -14,13 +14,22 @@
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
 
 /**
+ * Defines a listener for the "leave" event of a workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 final class AsLeaveListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $place      The place name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same place
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $place = null,

@@ -14,13 +14,22 @@
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
 
 /**
+ * Defines a listener for a transition event of a workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 final class AsTransitionListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $transition The transition name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same transition
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $transition = null,
-Original file line number
+Diff line change
@@ Expand Up / @@ -23,6 +23,9 @@ class SerializedPath @@
     {
         private PropertyPath $serializedPath;
+        /**
+         * @param string $serializedPath A path using a valid PropertyAccess syntax where the value is stored in a normalized representation
+         */
         public function __construct(string $serializedPath)
         {
             try {
@@ Expand Down @@