Live Components

1
2
3
4
5
6
7
8
9
10
11

use App\Entity\Post;

#[AsLiveComponent]
class EditPost
{
    #[LiveProp(writable: ['title', 'content'])]
    public Post $post;

    #[LiveProp(writable: ['allow_markdown'])]
    public array $options = ['allow_markdown' => true, 'allow_html' => false];
}

1
2
3
4
5
6
7
8
9
10
11

#[AsLiveComponent]
class EditPost
{
    // ...

    #[LiveProp(writable: true)]
    public array $options = ['allow_markdown' => true, 'allow_html' => false];

    #[LiveProp(writable: true)]
    public array $todoItems = ['Train tiger', 'Feed tiger', 'Pet tiger'];
}

1
2
3
4
5
6
7
8
9
10
11

#[AsLiveComponent]
class EditPost
{
    // ...

    #[LiveProp(writable: true)]
    public string $meal = 'lunch';

    #[LiveProp(writable: true)]
    public array $foods = ['pizza', 'tacos'];
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

class ComponentWithAddressDto
{
    #[LiveProp(hydrateWith: 'hydrateAddress', dehydrateWith: 'dehydrateAddress')]
    public AddressDto $addressDto;

    public function dehydrateAddress(AddressDto $address)
    {
        return [
            'street' => $address->street,
            'city' => $address->city,
            'state' => $address->state,
        ];
    }

    public function hydrateAddress($data): AddressDto
    {
        return new AddressDto($data['street'], $data['city'], $data['state']);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use App\Model\Food;
use Symfony\UX\LiveComponent\Hydration\HydrationExtensionInterface;

class FoodHydrationExtension implements HydrationExtensionInterface
{
    public function supports(string $className): bool
    {
        return is_subclass_of($className, Food::class);
    }

    public function hydrate(mixed $value, string $className): ?object
    {
        return new Food($value['name'], $value['isCooked']);
    }

    public function dehydrate(object $object): mixed
    {
        return [
            'name' => $object->getName(),
            'isCooked' => $object->isCooked(),
        ];
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// src/Twig/Components/RandomNumber.php
namespace App\Twig\Components;

// ...
use Psr\Log\LoggerInterface;

class RandomNumber
{
    // ...

    #[LiveAction]
    public function resetMax(LoggerInterface $logger)
    {
        $this->max = 1000;
        $logger->debug('The min/max were reset!');
    }

    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// src/Twig/Components/ItemList.php
namespace App\Twig\Components;

// ...
use Psr\Log\LoggerInterface;
use Symfony\UX\LiveComponent\Attribute\LiveArg;

class ItemList
{
    // ...
    #[LiveAction]
    public function addItem(#[LiveArg] int $id, #[LiveArg('itemName')] string $name)
    {
        $this->id = $id;
        $this->name = $name;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// src/Twig/Components/RandomNumber.php
namespace App\Twig\Components;

// ...
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class RandomNumber extends AbstractController
{
    // ...

    #[LiveAction]
    public function resetMax()
    {
        // ...

        $this->addFlash('success', 'Max has been reset!');

        return $this->redirectToRoute('app_random_number');
    }

    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

namespace App\Form;

use App\Entity\Post;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class PostType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('title')
            ->add('slug')
            ->add('content')
        ;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults([
            'data_class' => Post::class,
        ]);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

namespace App\Twig\Components;

use App\Entity\Post;
use App\Form\PostType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use Symfony\UX\LiveComponent\ComponentWithFormTrait;
use Symfony\UX\LiveComponent\DefaultActionTrait;

#[AsLiveComponent]
class PostForm extends AbstractController
{
    use DefaultActionTrait;
    use ComponentWithFormTrait;

    /**
     * The initial data used to create the form.
     */
    #[LiveProp]
    public ?Post $initialFormData = null;

    protected function instantiateForm(): FormInterface
    {
        // we can extend AbstractController to get the normal shortcuts
        return $this->createForm(PostType::class, $this->initialFormData);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// ...
use Doctrine\ORM\EntityManagerInterface;
use Symfony\UX\LiveComponent\Attribute\LiveAction;

class PostForm extends AbstractController
{
    // ...

    #[LiveAction]
    public function save(EntityManagerInterface $entityManager)
    {
        // Submit the form! If validation fails, an exception is thrown
        // and the component is automatically re-rendered with the errors
        $this->submitForm();

        /** @var Post $post */
        $post = $this->getForm()->getData();
        $entityManager->persist($post);
        $entityManager->flush();

        $this->addFlash('success', 'Post saved!');

        return $this->redirectToRoute('app_post_show', [
            'id' => $post->getId(),
        ]);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// src/Controller/PostController.php
class PostController extends AbstractController
{
    #[Route('/admin/post/{id}/edit', name: 'app_post_edit')]
    public function edit(Request $request, Post $post, EntityManagerInterface $entityManager): Response
    {
        $form = $this->createForm(PostType::class, $post);
        $form->handleRequest($request);

        if ($form->isSubmitted() && $form->isValid()) {
            // save, redirect, etc
        }

        return $this->render('post/edit.html.twig', [
            'post' => $post,
            'form' => $form, // use $form->createView() in Symfony <6.2
        ]);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// ...

#[LiveAction]
public function save()
{
    // $this->initialFormData will *not* contain the latest data yet!

    // submit the form
    $this->submitForm();

    // now you can access the latest data
    $post = $this->getForm()->getData();
    // (same as above)
    $post = $this->initialFormData;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// ...

#[LiveAction]
public function generateTitle()
{
    // this works!
    // (the form will be submitted automatically after this method, now with the new title)
    $this->formValues['title'] = '... some auto-generated-title';

    // this would *not* work
    // $this->submitForm();
    // $post = $this->getForm()->getData();
    // $post->setTitle('... some auto-generated-title');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

namespace App\Form;

use App\Entity\BlogPost;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\CollectionType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class BlogPostFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('title', TextType::class)
            // ...
            ->add('comments', CollectionType::class, [
                'entry_type' => CommentFormType::class,
                'allow_add' => true,
                'allow_delete' => true,
                'by_reference' => false,
            ])
        ;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(['data_class' => BlogPost::class]);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

namespace App\Twig;

use App\Entity\BlogPost;
use App\Entity\Comment;
use App\Form\BlogPostFormType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveAction;
use Symfony\UX\LiveComponent\ComponentWithFormTrait;
use Symfony\UX\LiveComponent\DefaultActionTrait;

#[AsLiveComponent]
class BlogPostCollectionType extends AbstractController
{
    use ComponentWithFormTrait;
    use DefaultActionTrait;

    #[LiveProp]
    public Post $initialFormData;

    protected function instantiateForm(): FormInterface
    {
        return $this->createForm(BlogPostFormType::class, $this->initialFormData);
    }

    #[LiveAction]
    public function addComment()
    {
        // "formValues" represents the current data in the form
        // this modifies the form to add an extra comment
        // the result: another embedded comment form!
        // change "comments" to the name of the field that uses CollectionType
        $this->formValues['comments'][] = [];
    }

    #[LiveAction]
    public function removeComment(#[LiveArg] int $index)
    {
        unset($this->formValues['comments'][$index]);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

namespace App\Form;

use App\Entity\BlogPost;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\UX\LiveComponent\Form\Type\LiveCollectionType;

class BlogPostFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('title', TextType::class)
            // ...
            ->add('comments', LiveCollectionType::class, [
                'entry_type' => CommentFormType::class,
            ])
        ;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(['data_class' => BlogPost::class]);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

namespace App\Twig;

use App\Entity\BlogPost;
use App\Form\BlogPostFormType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use Symfony\UX\LiveComponent\DefaultActionTrait;
use Symfony\UX\LiveComponent\LiveCollectionTrait;

#[AsLiveComponent]
class BlogPostCollectionType extends AbstractController
{
    use LiveCollectionTrait;
    use DefaultActionTrait;

    #[LiveProp]
    public BlogPost $initialFormData;

    protected function instantiateForm(): FormInterface
    {
        return $this->createForm(BlogPostFormType::class, $this->initialFormData);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// ...
$builder
    // ...
    ->add('comments', LiveCollectionType::class, [
        'entry_type' => CommentFormType::class,
        'label' => false,
        'button_delete_options' => [
            'label' => 'X',
            'attr' => [
                'class' => 'btn btn-outline-danger',
            ],
        ]
    ])
;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// ...
class EditUser
{
    // ...

    #[LiveAction]
    public function save()
    {
        // validate, save, etc

        // reset your live props to the original state
        $this->user = new User();
        $this->agreeToTerms = false;
        // clear the validation state
        $this->resetValidation();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

// ...
#[AsLiveComponent]
class SearchModule
{
    #[LiveProp(writable: true, url: true)]
    public string $query = '';

    #[LiveProp(writable: true, url: true)]
    public string $mode = 'fulltext';

    // ...
}

1
2
3
4
5
6
7
8
9
10
11

// ...
use Symfony\UX\LiveComponent\Metadata\UrlMapping;

#[AsLiveComponent]
class SearchModule
{
    #[LiveProp(writable: true, url: new UrlMapping(as: 'q'))]
    public string $query = '';

    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// ...
use Symfony\UX\LiveComponent\Metadata\UrlMapping;

#[AsLiveComponent]
class SearchModule
{
    #[LiveProp(writable: true, url: true, modifier: 'modifyQueryProp')]
    public string $query = '';

    #[LiveProp]
    public ?string $alias = null;

    public function modifyQueryProp(LiveProp $liveProp): LiveProp
    {
        if ($this->alias) {
            $liveProp = $liveProp->withUrl(new UrlMapping(as: $this->alias));
        }
        return $liveProp;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// ...
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\UX\LiveComponent\ValidatableComponentTrait;
use Symfony\UX\TwigComponent\Attribute\PostMount;

#[AsLiveComponent]
class SearchModule
{
    use ValidatableComponentTrait;

    #[LiveProp(writable: true, url: true)]
    public string $query = '';

    #[LiveProp(writable: true, url: true)]
    #[Assert\NotBlank]
    public string $mode = 'fulltext';

    #[PostMount]
    public function postMount(): void
    {
        // Validate 'mode' field without throwing an exception, so the component can
        // be mounted anyway and a validation error can be shown to the user
        if (!$this->validateField('mode', false)) {
            // Do something when validation fails
        }
    }

    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

namespace App\Twig\Components;

use App\Entity\Post;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveAction;
use Symfony\UX\LiveComponent\Attribute\LiveProp;

#[AsLiveComponent]
final class EditPost extends AbstractController
{
    #[LiveProp(writable: ['title', 'content'])]
    public Post $post;

    #[LiveAction]
    public function save(EntityManagerInterface $entityManager)
    {
        $entityManager->flush();

        return $this->redirectToRoute('some_route');
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

namespace App\Twig\Components;

use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;

#[AsLiveComponent]
final class MarkdownTextarea
{
    #[LiveProp]
    public string $label;

    #[LiveProp]
    public string $name;

    #[LiveProp(writable: true)]
    public string $value = '';
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// src/Twig/InvoiceLineItemForm.php
// ...

#[AsLiveComponent]
final class InvoiceLineItemForm
{
    // ...

    #[LiveProp]
    #[Valid]
    public ?InvoiceLineItem $lineItem = null;

    #[PostMount]
    public function postMount(): void
    {
        if (!$this->lineItem) {
            $this->lineItem = new InvoiceLineItem();
        }
    }

    #[LiveAction]
    public function save(EntityManagerInterface $entityManager)
    {
        if (!$this->lineItem->getId()) {
            $this->emit('lineItem:created', $this->lineItem);
        }

        $entityManager->persist($this->lineItem);
        $entityManager->flush();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// src/Twig/InvoiceCreator.php
// ...

#[AsLiveComponent]
final class InvoiceCreator
{
    // ...

    #[LiveListener('lineItem:created')]
    public function addLineItem()
    {
        // no need to do anything here: the component will re-render
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// src/Twig/InvoiceLineItemForm.php
// ...

#[AsLiveComponent]
class InvoiceLineItemForm
{
    // ...

    #[LiveAction]
    public function save(EntityManagerInterface $entityManager)
    {
        $isNew = null === $this->lineItem->getId();

        $entityManager->persist($this->lineItem);
        $entityManager->flush();

        if ($isNew) {
            // reset the state of this component
            $this->emit('lineItem:created', $this->lineItem);
            $this->lineItem = new InvoiceLineItem();
            // if you're using ValidatableComponentTrait
            $this->clearValidation();
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11

#[PostHydrate(priority: 10)]
public function highPriorityHook(): void
{
    // Runs first
}

#[PostHydrate(priority: 1)]
public function lowPriorityHook(): void
{
    // Runs last
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#[AsLiveComponent]
class ProductSearch
{
    #[LiveProp(writable: true, onUpdated: 'onQueryUpdated')]
    public string $query = '';

    // ...

    public function onQueryUpdated($previousValue): void
    {
        // $this->query already contains a new value
        // and its previous value is passed as an argument
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use App\Entity\Post;

#[AsLiveComponent]
class EditPost
{
    #[LiveProp(writable: ['title', 'content'], onUpdated: ['title' => 'onTitleUpdated'])]
    public Post $post;

    // ...

    public function onTitleUpdated($previousValue): void
    {
        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

#[AsLiveComponent]
class ProductSearch
{
    #[LiveProp(writable: true, modifier: 'modifyAddedDate')]
    public ?\DateTimeImmutable $addedDate = null;

    #[LiveProp]
    public string $dateFormat = 'Y-m-d';

    // ...

    public function modifyAddedDate(LiveProp $prop): LiveProp
    {
        return $prop->withFormat($this->dateFormat);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Symfony\UX\LiveComponent\Test\InteractsWithLiveComponents;

class MyComponentTest extends KernelTestCase
{
    use InteractsWithLiveComponents;

    public function testCanRenderAndInteract(): void
    {
        $testComponent = $this->createLiveComponent(
            name: 'MyComponent', // can also use FQCN (MyComponent::class)
            data: ['foo' => 'bar'],
        );

        // render the component html
        $this->assertStringContainsString('Count: 0', $testComponent->render());

        // call live actions
        $testComponent
            ->call('increase')
            ->call('increase', ['amount' => 2]) // call a live action with arguments
        ;

        $this->assertStringContainsString('Count: 3', $testComponent->render());

        // call live action with file uploads
        $testComponent
            ->call('processUpload', files: ['file' => new UploadedFile(...)]);

        // emit live events
        $testComponent
            ->emit('increaseEvent')
            ->emit('increaseEvent', ['amount' => 2]) // emit a live event with arguments
        ;

        // set live props
        $testComponent
            ->set('count', 99)
        ;

        // Submit form data ('my_form' for your MyFormType form)
        $testComponent
            ->submitForm(['my_form' => ['input' => 'value']], 'save');

        $this->assertStringContainsString('Count: 99', $testComponent->render());

        // refresh the component
        $testComponent->refresh();

        // access the component object (in its current state)
        $component = $testComponent->component(); // MyComponent

        $this->assertSame(99, $component->count);

        // test a live action that redirects
        $response = $testComponent->call('redirect')->response(); // Symfony\Component\HttpFoundation\Response

        $this->assertSame(302, $response->getStatusCode());

        // authenticate a user ($user is instance of UserInterface)
        $testComponent->actingAs($user);

        // set the '_locale' route parameter (if the component route is localized)  
        $testComponent->setRouteLocale('fr');

        // customize the test client
        $client = self::getContainer()->get('test.client');

        // do some stuff with the client (ie login user via form)

        $testComponent = $this->createLiveComponent(
            name: 'MyComponent',
            data: ['foo' => 'bar'],
            client: $client,
        );
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

use Symfony\UX\LiveComponent\Form\Type\LiveCollectionType;

// Parent FormType used in the Live Component
class LiveCollectionFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder->add('children', LiveCollectionType::class, [
                'entry_type' => ChildFormType::class,
            ])
        ;
    }
}

// Child Form Type used for each entry in the collection
class ChildFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('name', TextType::class)
            ->add('age', IntegerType::class)
        ;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

// Call the addCollectionItem method as many times as needed, specifying the name of the collection field.
$component->call('addCollectionItem', ['name' => 'children']);
$component->call('addCollectionItem', ['name' => 'children']);
//... can be called as many times as you need entries in your 'children' field

// ... then submit the form by providing data for all the fields in the ChildFormType for each added entry:
$component->submitForm([ 'live_collection_form' => [
    'children' => [
        ['name' => 'childName1', 'age' => 10],
        ['name' => 'childName2', 'age' => 15],
    ]
]]);