diff --git a/src/LiveComponent/src/Attribute/AsLiveComponent.php b/src/LiveComponent/src/Attribute/AsLiveComponent.php index ebbee14f6fe..7513df39fe6 100644 --- a/src/LiveComponent/src/Attribute/AsLiveComponent.php +++ b/src/LiveComponent/src/Attribute/AsLiveComponent.php @@ -14,6 +14,10 @@ use Symfony\UX\TwigComponent\Attribute\AsTwigComponent; /** + * An attribute to register a LiveComponent. + * + * @see https://symfony.com/bundles/ux-live-component + * * @author Kevin Bond * * @experimental @@ -21,6 +25,15 @@ #[\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 index 56f8ef43839..b2fcbbb2232 100644 --- 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 index 8d41a0f2c22..97bf9df9bc5 100644 --- a/src/LiveComponent/src/Attribute/LiveArg.php +++ b/src/LiveComponent/src/Attribute/LiveArg.php @@ -12,6 +12,10 @@ 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 * * @experimental @@ -19,8 +23,12 @@ #[\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 index 18f1a679c46..3698797aabe 100644 --- 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 index 392e2215846..90afc678744 100644 --- 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 + */ + 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 index 2abac5dfd2b..24732beaeaa 100644 --- 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 index d764b83e5a9..b4061082969 100644 --- 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)]