minor #51974 [Console][EventDispatcher][Security][Serializer][Workflow] Add PHPDoc to attribute classes and properties (alexandre-daubois)

nicolas-grekas · nicolas-grekas · commit 0685c42a41f5 · 2024-01-02T11:02:38.000+01:00
This PR was merged into the 7.1 branch. Discussion ---------- [Console][EventDispatcher][Security][Serializer][Workflow] Add PHPDoc to attribute classes and properties | Q | A | ------------- | --- | Branch? | 7.1 | Bug fix? | no | New feature? | yes | Deprecations? | no | Tickets | Part of #51920 | License | MIT One more round. :information_source: A first review of this kind is being done [here](#51971), I'll adjust this PR accordingly once done 🙂 Commits ------- 8a2ac5a [Console][EventDispatcher][Security][Serializer][Workflow] Add PHPDoc to attribute classes and properties
diff --git a/src/Symfony/Component/Console/Attribute/AsCommand.php b/src/Symfony/Component/Console/Attribute/AsCommand.php
@@ -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,
diff --git a/src/Symfony/Component/Security/Http/Attribute/CurrentUser.php b/src/Symfony/Component/Security/Http/Attribute/CurrentUser.php
@@ -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);
diff --git a/src/Symfony/Component/Security/Http/Attribute/IsGranted.php b/src/Symfony/Component/Security/Http/Attribute/IsGranted.php
@@ -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,
     ) {
     }
diff --git a/src/Symfony/Component/Serializer/Attribute/Context.php b/src/Symfony/Component/Serializer/Attribute/Context.php
@@ -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
      */
diff --git a/src/Symfony/Component/Serializer/Attribute/DiscriminatorMap.php b/src/Symfony/Component/Serializer/Attribute/DiscriminatorMap.php
@@ -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,
diff --git a/src/Symfony/Component/Serializer/Attribute/Groups.php b/src/Symfony/Component/Serializer/Attribute/Groups.php
@@ -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)
     {
diff --git a/src/Symfony/Component/Serializer/Attribute/MaxDepth.php b/src/Symfony/Component/Serializer/Attribute/MaxDepth.php
@@ -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) {
diff --git a/src/Symfony/Component/Serializer/Attribute/SerializedName.php b/src/Symfony/Component/Serializer/Attribute/SerializedName.php
@@ -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) {
diff --git a/src/Symfony/Component/Serializer/Attribute/SerializedPath.php b/src/Symfony/Component/Serializer/Attribute/SerializedPath.php
@@ -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 {
diff --git a/src/Symfony/Component/Workflow/Attribute/AsAnnounceListener.php b/src/Symfony/Component/Workflow/Attribute/AsAnnounceListener.php
@@ -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,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsCompletedListener.php b/src/Symfony/Component/Workflow/Attribute/AsCompletedListener.php
@@ -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,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsEnterListener.php b/src/Symfony/Component/Workflow/Attribute/AsEnterListener.php
@@ -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,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsEnteredListener.php b/src/Symfony/Component/Workflow/Attribute/AsEnteredListener.php
@@ -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,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsGuardListener.php b/src/Symfony/Component/Workflow/Attribute/AsGuardListener.php
@@ -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,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsLeaveListener.php b/src/Symfony/Component/Workflow/Attribute/AsLeaveListener.php
@@ -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,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsTransitionListener.php b/src/Symfony/Component/Workflow/Attribute/AsTransitionListener.php
@@ -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 number	Diff line change
`@@ -20,6 +20,10 @@`
`20`	`20`	`#[\Attribute(\Attribute::TARGET_PARAMETER)]`
`21`	`21`	`class CurrentUser extends ValueResolver`
`22`	`22`	`{`
	`23`	`+ /**`
	`24`	`+ * @param bool $disabled Whether this value resolver is disabled, which allows to enable a value resolver globally while disabling it in specific cases`
	`25`	`+ * @param string $resolver The class name of the resolver to use`
	`26`	`+ */`
`23`	`27`	`public function __construct(bool $disabled = false, string $resolver = UserValueResolver::class)`
`24`	`28`	`{`
`25`	`29`	`parent::__construct($resolver, $disabled);`
Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@ class Groups`
`25`	`25`	`private readonly array $groups;`
`26`	`26`
`27`	`27`	`/**`
`28`		`- * @param string\|string[] $groups`
	`28`	`+ * @param string\|string[] $groups The groups to define on the attribute target`
`29`	`29`	`*/`
`30`	`30`	`public function __construct(string\|array $groups)`
`31`	`31`	`{`
Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,9 @@`
`19`	`19`	`#[\Attribute(\Attribute::TARGET_METHOD \| \Attribute::TARGET_PROPERTY)]`
`20`	`20`	`class MaxDepth`
`21`	`21`	`{`
	`22`	`+ /**`
	`23`	`+ * @param int $maxDepth The maximum serialization depth`
	`24`	`+ */`
`22`	`25`	`public function __construct(private readonly int $maxDepth)`
`23`	`26`	`{`
`24`	`27`	`if ($maxDepth <= 0) {`
Original file line number	Diff line number	Diff line change
`@@ -23,6 +23,9 @@ class SerializedPath`
`23`	`23`	`{`
`24`	`24`	`private PropertyPath $serializedPath;`
`25`	`25`
	`26`	`+ /**`
	`27`	`+ * @param string $serializedPath A path using a valid PropertyAccess syntax where the value is stored in a normalized representation`
	`28`	`+ */`
`26`	`29`	`public function __construct(string $serializedPath)`
`27`	`30`	`{`
`28`	`31`	`try {`