minor #1378 [LiveComponent] Add docblocks on attributes (smnandre)

kbond · kbond · commit a13bae32f0c2 · 2024-01-04T15:57:10.000-05:00
This PR was squashed before being merged into the 2.x branch. Discussion ---------- [LiveComponent] Add docblocks on attributes That was on my todo for too long :) Commits ------- e4f3b38 [LiveComponent] Add docblocks on attributes
diff --git a/src/LiveComponent/src/Attribute/AsLiveComponent.php b/src/LiveComponent/src/Attribute/AsLiveComponent.php
@@ -14,13 +14,26 @@
 use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
 
 /**
+ * An attribute to register a LiveComponent.
+ *
+ * @see https://symfony.com/bundles/ux-live-component
+ *
  * @author Kevin Bond <kevinbond@gmail.com>
  *
  * @experimental
  */
 #[\Attribute(\Attribute::TARGET_CLASS)]
 final class AsLiveComponent extends AsTwigComponent
 {
+    /**
+     * @param string|null $name              The component name (ie: TodoList)
+     * @param string|null $template          The template path of the component (ie: components/TodoList.html.twig).
+     * @param string|null $defaultAction     The default action to call when the component is mounted (ie: __invoke)
+     * @param bool        $exposePublicProps Whether to expose every public property as a Twig variable
+     * @param string      $attributesVar     The name of the special "attributes" variable in the template
+     * @param bool        $csrf              Whether to enable CSRF protection (default: true)
+     * @param string      $route             The route used to render the component & handle actions (default: ux_live_component)
+     */
     public function __construct(
         string $name = null,
         string $template = null,
diff --git a/src/LiveComponent/src/Attribute/LiveAction.php b/src/LiveComponent/src/Attribute/LiveAction.php
@@ -12,6 +12,10 @@
 namespace Symfony\UX\LiveComponent\Attribute;
 
 /**
+ * An attribute to register a LiveAction method.
+ *
+ * @see https://symfony.com/bundles/ux-live-component/current/index.html#actions
+ *
  * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
diff --git a/src/LiveComponent/src/Attribute/LiveArg.php b/src/LiveComponent/src/Attribute/LiveArg.php
@@ -12,15 +12,23 @@
 namespace Symfony\UX\LiveComponent\Attribute;
 
 /**
+ * An attribute to configure a LiveArg (custom argument passed to a LiveAction).
+ *
+ * @see https://symfony.com/bundles/ux-live-component/current/index.html#actions-arguments
+ *
  * @author Tomas Norkūnas <norkunas.tom@gmail.com>
  *
  * @experimental
  */
 #[\Attribute(\Attribute::TARGET_PARAMETER)]
 final class LiveArg
 {
-    public function __construct(public ?string $name = null)
-    {
+    public function __construct(
+        /**
+         * @param string|null $name The name of the argument received by the LiveAction
+         */
+        public ?string $name = null,
+    ) {
     }
 
     /**
diff --git a/src/LiveComponent/src/Attribute/LiveListener.php b/src/LiveComponent/src/Attribute/LiveListener.php
@@ -12,11 +12,21 @@
 namespace Symfony\UX\LiveComponent\Attribute;
 
 /**
+ * An Attribute to register a LiveListener method.
+ *
+ * When any component emits the event, an Ajax call will be made to call this
+ * method and re-render the component.
+ *
+ * @see https://symfony.com/bundles/ux-live-component/current/index.html#listeners
+ *
  * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
 class LiveListener extends LiveAction
 {
+    /**
+     * @param string $eventName The name of the event to listen to (e.g. "itemUpdated")
+     */
     public function __construct(private string $eventName)
     {
     }
diff --git a/src/LiveComponent/src/Attribute/LiveProp.php b/src/LiveComponent/src/Attribute/LiveProp.php
@@ -12,6 +12,10 @@
 namespace Symfony\UX\LiveComponent\Attribute;
 
 /**
+ * An attribute to mark a property as a "LiveProp".
+ *
+ * @see https://symfony.com/bundles/ux-live-component/current/index.html#liveprops-stateful-component-properties
+ *
  * @experimental
  */
 #[\Attribute(\Attribute::TARGET_PROPERTY)]
@@ -23,87 +27,83 @@ final class LiveProp
      */
     public const IDENTITY = '@identity';
 
-    /** @var bool|string[] */
-    private bool|array $writable;
-
-    private ?string $hydrateWith;
-
-    private ?string $dehydrateWith;
-
-    private bool $useSerializerForHydration;
-
-    private array $serializationContext;
-
-    /**
-     * The "frontend" field name that should be used for this property.
-     *
-     * This can be used, for example, to have a property called "foo", which actually
-     * maps to a frontend data model called "bar".
-     *
-     * If you pass a string that ends in () - like "getFieldName()" - that
-     * method on the component will be called to determine this.
-     */
-    private ?string $fieldName;
-
-    private ?string $format;
-
-    private bool $acceptUpdatesFromParent;
-
-    /**
-     * @var string|string[]|null
-     *
-     * A hook that will be called after the property is updated.
-     * Set it to a method name on the Live Component that should be called.
-     * The old value of the property will be passed as an argument to it.
-     */
-    private null|string|array $onUpdated;
-
-    /**
-     * Tells if this property should be bound to the URL.
-     */
-    private bool $url;
-
-    /**
-     * @param bool|array  $writable                  If true, this property can be changed by the frontend.
-     *                                               Or set to an array of paths within this object/array
-     *                                               that are writable.
-     * @param bool        $useSerializerForHydration If true, the serializer will be used to
-     *                                               dehydrate then hydrate this property.
-     *                                               Incompatible with hydrateWith and dehydrateWith.
-     * @param string|null $format                    The format to be used if the value is a DateTime of some sort.
-     *                                               For example: 'Y-m-d H:i:s'. If this property is writable, set this
-     *                                               to the format that your frontend field will use/set.
-     * @param bool        $updateFromParent          if true, while a parent component is re-rendering,
-     *                                               if the parent passes in this prop and it changed
-     *                                               from the value used when originally rendering
-     *                                               this child, the value in the child will be updated
-     *                                               to match the new value and the child will be re-rendered
-     * @param bool        $url                       if true, this property will be synchronized with a query parameter
-     *                                               in the URL
-     */
     public function __construct(
-        bool|array $writable = false,
-        string $hydrateWith = null,
-        string $dehydrateWith = null,
-        bool $useSerializerForHydration = false,
-        array $serializationContext = [],
-        string $fieldName = null,
-        string $format = null,
-        bool $updateFromParent = false,
-        string|array $onUpdated = null,
-        bool $url = false,
+        /**
+         * If true, this property can be changed by the frontend.
+         *
+         * Or set to an array of paths within this object/array
+         * that are writable.
+         *
+         * @var bool|string[]
+         */
+        private bool|array $writable = false,
+
+        /**
+         * Method to call to hydrate this property.
+         */
+        private ?string $hydrateWith = null,
+
+        /**
+         * Method to call to dehydrate this property.
+         */
+        private ?string $dehydrateWith = null,
+
+        /**
+         * If true, the serializer will be used to dehydrate then hydrate
+         * this property.
+         *
+         * Incompatible with hydrateWith and dehydrateWith.
+         */
+        private bool $useSerializerForHydration = false,
+
+        /**
+         * @var array<string, mixed>
+         */
+        private array $serializationContext = [],
+
+        /**
+         * The "frontend" field name that should be used for this property.
+         *
+         * This can be used, for example, to have a property called "foo", which
+         * actually maps to a frontend data model called "bar".
+         *
+         * If you pass a string that ends in () - like "getFieldName()" - that
+         * method on the component will be called to determine this.
+         */
+        private ?string $fieldName = null,
+
+        /**
+         * The format to be used if the value is a DateTime of some sort.
+         *
+         * For example: 'Y-m-d H:i:s'. If this property is writable, set this
+         * to the format that your frontend field will use/set.
+         */
+        private ?string $format = null,
+
+        /**
+         * If true, while a parent component is re-rendering, if the parent
+         * passes in this prop and it changed from the value used when
+         * originally rendering this child, the value in the child will be
+         * updated to match the new value and the child will be re-rendered.
+         */
+        private bool $updateFromParent = false,
+
+        /**
+         * A hook that will be called after the property is updated.
+         *
+         * Set it to a method name on the Live Component that should be called.
+         * The old value of the property will be passed as an argument to it.
+         *
+         * @var string|string[]|null
+         */
+        private null|string|array $onUpdated = null,
+
+        /**
+         * If true, this property will be synchronized with a query parameter
+         * in the URL.
+         */
+        private bool $url = false,
     ) {
-        $this->writable = $writable;
-        $this->hydrateWith = $hydrateWith;
-        $this->dehydrateWith = $dehydrateWith;
-        $this->useSerializerForHydration = $useSerializerForHydration;
-        $this->serializationContext = $serializationContext;
-        $this->fieldName = $fieldName;
-        $this->format = $format;
-        $this->acceptUpdatesFromParent = $updateFromParent;
-        $this->onUpdated = $onUpdated;
-        $this->url = $url;
-
         if ($this->useSerializerForHydration && ($this->hydrateWith || $this->dehydrateWith)) {
             throw new \InvalidArgumentException('Cannot use useSerializerForHydration with hydrateWith or dehydrateWith.');
         }
@@ -190,7 +190,7 @@ public function format(): ?string
 
     public function acceptUpdatesFromParent(): bool
     {
-        return $this->acceptUpdatesFromParent;
+        return $this->updateFromParent;
     }
 
     public function onUpdated(): null|string|array
diff --git a/src/LiveComponent/src/Attribute/PostHydrate.php b/src/LiveComponent/src/Attribute/PostHydrate.php
@@ -12,6 +12,8 @@
 namespace Symfony\UX\LiveComponent\Attribute;
 
 /**
+ * An attribute to register a PostHydrate hook.
+ *
  * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
diff --git a/src/LiveComponent/src/Attribute/PreDehydrate.php b/src/LiveComponent/src/Attribute/PreDehydrate.php
@@ -12,6 +12,8 @@
 namespace Symfony\UX\LiveComponent\Attribute;
 
 /**
+ * An attribute to register a PreDehydrate hook.
+ *
  * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
