From ed2ca6c7d905afc0ed31b15e8d9286efb46b4685 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Jun 2025 17:05:42 +0200 Subject: [PATCH 1/3] [Doc] Update the docs about the mount() method of Twig components --- src/TwigComponent/doc/index.rst | 65 +++++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 19 deletions(-) diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst index de3cb4e242e..89a541578fa 100644 --- a/src/TwigComponent/doc/index.rst +++ b/src/TwigComponent/doc/index.rst @@ -447,15 +447,25 @@ need to populate, you can render it with: Mounting Data ------------- -Most of the time, you will create public properties and then pass values -to those as "props" when rendering. But there are several hooks in case -you need to do something more complex. +Most of the time, you will create public properties and pass values to them +as "props" when rendering the component. However, there are several hooks +available when you need to perform more complex logic. The mount() Method ~~~~~~~~~~~~~~~~~~ -For more control over how your "props" are handled, you can create a method -called ``mount()``:: +The ``mount()`` method gives you more control over how your "props" are handled. +It is called only once: immediately after your component is instantiated. +The ``mount()`` method **cannot access the values of the public properties** +passed when rendering the component. + +For example, if you call your component like this: + +.. code-block:: twig + + + +The following code won't work as expected: // src/Twig/Components/Alert.php // ... @@ -466,29 +476,46 @@ called ``mount()``:: public string $message; public string $type = 'success'; - public function mount(bool $isSuccess = true): void + public function mount(): void { - $this->type = $isSuccess ? 'success' : 'danger'; + {# ❌ this won't work: at this point, the $type property still has its + default value. Passed properties are not yet available. #} + if ('error' === $this->type) { + // ... + } } // ... } -The ``mount()`` method is called just one time: immediately after your -component is instantiated. Because the method has an ``$isSuccess`` -argument, if we pass an ``isSuccess`` prop when rendering, it will be -passed to ``mount()``. +Instead, define the values you need in the ``mount()`` method as arguments:: -.. code-block:: html+twig + #[AsTwigComponent] + class Alert + { + public string $message; + public string $type = 'success'; - + public function mount(bool $isError = false): void + { + {# ✅ this works as expected #} + if ($isError) { + // ... + } + } + + // ... + } + +Now, pass the ``mount()`` argument like any other prop: + +.. code-block:: twig + + -If a prop name (e.g. ``isSuccess``) matches an argument name in ``mount()``, -the prop will be passed as that argument and the component system will -**not** try to set it directly on a property or use it for the component +If a prop name (e.g. ``isError``) matches an argument name in ``mount()``, +its value will be passed to the method. In that case, the component system +**will not** set it on a public property or use it in the component's ``attributes``. PreMount Hook From a054563fd1a1598eaf2a81ad7a0f77e217846871 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Jun 2025 17:12:22 +0200 Subject: [PATCH 2/3] Fix RST issues --- src/TwigComponent/doc/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst index 89a541578fa..ef8c47138de 100644 --- a/src/TwigComponent/doc/index.rst +++ b/src/TwigComponent/doc/index.rst @@ -461,7 +461,7 @@ passed when rendering the component. For example, if you call your component like this: -.. code-block:: twig +.. code-block:: html+twig @@ -509,7 +509,7 @@ Instead, define the values you need in the ``mount()`` method as arguments:: Now, pass the ``mount()`` argument like any other prop: -.. code-block:: twig +.. code-block:: html+twig From e0c22792384266639915a4d9565f4f04a0f09921 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 18 Jun 2025 11:55:54 +0200 Subject: [PATCH 3/3] Reword --- src/TwigComponent/doc/index.rst | 52 ++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst index ef8c47138de..59b2be4d80a 100644 --- a/src/TwigComponent/doc/index.rst +++ b/src/TwigComponent/doc/index.rst @@ -455,9 +455,8 @@ The mount() Method ~~~~~~~~~~~~~~~~~~ The ``mount()`` method gives you more control over how your "props" are handled. -It is called only once: immediately after your component is instantiated. -The ``mount()`` method **cannot access the values of the public properties** -passed when rendering the component. +It is called once, immediately after the component is instantiated, **but before** +the component system assigns the props you passed when rendering. For example, if you call your component like this: @@ -465,7 +464,7 @@ For example, if you call your component like this: -The following code won't work as expected: +The following code won't work as expected:: // src/Twig/Components/Alert.php // ... @@ -478,8 +477,8 @@ The following code won't work as expected: public function mount(): void { - {# ❌ this won't work: at this point, the $type property still has its - default value. Passed properties are not yet available. #} + {# ❌ this won't work: at this point $type still has its default value. + Passed values are not yet available in props. #} if ('error' === $this->type) { // ... } @@ -488,7 +487,32 @@ The following code won't work as expected: // ... } -Instead, define the values you need in the ``mount()`` method as arguments:: +Inside ``mount()``, each prop has only its *default* value (or ``null`` if it is +untyped and has no default). If you need a prop's value, declare a parameter in +``mount()`` whose name matches the prop instead of reading the public property:: + + public function mount(string $type): void + { + {# ✅ this works as expected: the $type argument in PHP has the value + passed to the 'type' prop in the Twig template #} + if ('error' === $type) { + // ... + } + } + +If a prop name (e.g. ``type``) matches an argument name in ``mount()``, +its value will be passed only to the method. The component system **will not** +set it on a public property or use it in the component's ``attributes``. + +``mount()`` can also receive props **even when no matching public property +exists**. For example, pass an ``isError`` prop instead of ``type``: + +.. code-block:: html+twig + + + +Define a ``$isError`` argument to capture the prop and initialize other +properties using that value:: #[AsTwigComponent] class Alert @@ -498,26 +522,14 @@ Instead, define the values you need in the ``mount()`` method as arguments:: public function mount(bool $isError = false): void { - {# ✅ this works as expected #} if ($isError) { - // ... + $this->type = 'danger'; } } // ... } -Now, pass the ``mount()`` argument like any other prop: - -.. code-block:: html+twig - - - -If a prop name (e.g. ``isError``) matches an argument name in ``mount()``, -its value will be passed to the method. In that case, the component system -**will not** set it on a public property or use it in the component's -``attributes``. - PreMount Hook ~~~~~~~~~~~~~