Symfony UX Live Component

https://github.com/symfony/ux-live-component
Admin
Symfony UX Live Component enables automatic frontend updates for Twig components as users interact...
Tokens:110,978
Snippets:798
Trust Score:9.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install assets with npm

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Installs JavaScript assets and starts the watch process for WebpackEncore.

```terminal
$ npm install --force
$ npm run watch
```

--------------------------------

### Install with Composer

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Installs the live component bundle using Composer.

```terminal
$ composer require symfony/ux-live-component
```

--------------------------------

### ValueStore usage example

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/value-store.md

Example usage of the ValueStore. Shows creation, checking a property, setting a non-normalized name, getting the normalized value, flushing dirty props, and reinitializing all props.

```ts
import ValueStore from './Component/ValueStore';

const store = new ValueStore({ query: 'hello', user: { firstName: 'Ryan' } });

store.has('query'); // true
store.set('user[firstName]', 'Kevin'); // true (normalized to user.firstName)
store.get('user.firstName'); // 'Kevin'
store.flushDirtyPropsToPending();
store.reinitializeAllProps({ query: 'bye', user: { firstName: 'Kevin' } });
```

--------------------------------

### Example: using getComponent, on, and action

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component.md

Shows how to get a live component, listen for model:set events, and call a live action with error handling. The commented line component.set('query', 'milk', true, 250) is shown as an alternative but not executed.

```typescript
import { getComponent } from '@symfony/ux-live-component';

const element = document.querySelector('#my-live-component');
const component = await getComponent(element);

component.on('model:set', (model, value) => {
    console.log(`model ${model} changed to`, value);
});

try {
    const response = await component.action('addTodo', { label: 'Buy milk' });
    // component.set('query', 'milk', true, 250);
} catch (error) {
    console.error('Live action failed', error);
}
```

--------------------------------

### Example: Using BackendRequest

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/backend.md

Shows how to import the Backend class, create a backend instance, make a request, and use the returned BackendRequest. The example calls containsOneOfActions and accesses the promise to log the response status.

```typescript
import Backend from './Backend/Backend';

const backend = new Backend('/_components/todo', 'post', 'same-origin');
const request = backend.makeRequest(
    { name: 'Ryan', food: 5 },
    [{ name: 'save', args: { status: 'published' } }],
    { name: 'Kevin' },
    {},
    {},
    {}
);

request.containsOneOfActions(['save']); // true
request.promise.then((response) => console.log(response.status));
```

--------------------------------

### Install phpdocumentor/reflection-docblock

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Command to install the required library for docblock collection type extraction.

```terminal
$ composer require phpdocumentor/reflection-docblock
```

--------------------------------

### Install symfony/ux-live-component with Composer and npm

Source: https://github.com/symfony/ux-live-component/blob/3.x/assets/README.md

Commands to install the PHP package and the matching npm package. Ensure the version X.Y.Z exactly matches the PHP package version. This is for advanced users who want to decouple JavaScript dependencies from PHP dependencies.

```shell
composer require symfony/ux-live-component:X.Y.Z
npm add @symfony/ux-live-component@X.Y.Z
```

--------------------------------

### HookManager usage example

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/hook-manager.md

Shows how to create a HookManager, register a callback, trigger it, unregister it, and trigger again (which logs nothing).

```TypeScript
import HookManager from './HookManager';

const hooks = new HookManager();

const onRender = (component) => console.log('rendered', component.name);
hooks.register('render:finished', onRender);
hooks.triggerHook('render:finished', myComponent);

hooks.unregister('render:finished', onRender);
hooks.triggerHook('render:finished', myComponent); // nothing logged
```

--------------------------------

### connect(): void

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component.md

Registers the component in the registry, triggers the connect hook, activates the unsynced-inputs tracker and starts the external mutation tracker.

```APIDOC
## connect(): void

### Description
Registers the component in the registry, triggers the connect hook, activates the unsynced-inputs tracker and starts the external mutation tracker.

### Method
connect

### Signature
`connect(): void`
```

--------------------------------

### render method implementation

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component.md

Starts a request immediately and returns the promise for the next response.

```typescript
render(): Promise<BackendResponse> {
    const promise = this.nextRequestPromise;
    this.tryStartingRequest();
    return promise;
}
```

--------------------------------

### Configure ux_live_component route in config/routes.php

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/endpoints.md

Defines the dynamic route for live components with a default action of 'get'. The route accepts GET and POST methods and can be overridden via AsLiveComponent(route: ...).

```php
// config/routes.php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes) {
    $routes->add('ux_live_component', '/{_live_component}/{_live_action}')
        ->defaults([
            '_live_action' => 'get',
        ])
    ;
};
```

--------------------------------

### Using AsLiveComponent on a class

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-attributes.md

Example of applying the AsLiveComponent attribute to a class, with a LiveProp property for state.

```php
#[AsLiveComponent]
class ProductSearch
{
    #[LiveProp]
    public string $query = '';
}
```

--------------------------------

### Hook ordering example

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/hook-manager.md

Demonstrates that hooks with the same name are invoked in registration order. The first registered callback runs first.

```TypeScript
// Ordering example: first registered hook runs first
component.on('render:started', () => console.log('a'));
component.on('render:started', () => console.log('b'));
// logs: a, then b
```

--------------------------------

### GET request (default action, no actions/files)

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/endpoints.md

A GET request is sent when there are no actions, no files, the configured method is 'get', and the encoded data fits in the URL (less than 1500 characters). The request includes query parameters as JSON strings.

```APIDOC
## GET /{_live_component}

### Description
Sends a GET request to the Live Component endpoint when there are no actions, no files, the configured method is `get`, and the encoded data fits in the URL (< 1500 chars).

### Method
GET

### Endpoint
`/{_live_component}`

### Parameters
#### Query Parameters
- **props** (JSON object) - Required - Original dehydrated props
- **updated** (JSON object) - Required - Updated (dirty) models
- **children** (JSON object) - Optional - Child fingerprints, keyed by id
- **propsFromParent** (JSON object) - Optional - Props from parent component

### Request Example
```
GET /{_live_component}?props={"name":"Kevin"}&updated={"name":"Kevin"}
```

### Response
#### Success Response (200)
- **body** (string) - The rendered HTML response

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: text/html

<html>...</html>
```
```

--------------------------------

### Example: linking components with getComponent

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component-registry.md

Shows how to use getComponent to retrieve components and link them, e.g., pushing model changes from a product component into a cart component.

```typescript
import { getComponent } from '@symfony/ux-live-component';

async function linkComponents() {
    const cart = await getComponent(document.querySelector('#cart'));
    const product = await getComponent(document.querySelector('#product-1'));

    product.on('model:set', (model, value) => {
        cart.set(model, value, true); // push changes from product into cart
    });
}
```

--------------------------------

### Handle uploaded files in LiveAction (PHP)

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Files sent with the 'files' modifier are available in the regular $request->files bag. Use $request->files->get('my_file') for a single file and $request->files->all('multiple') for multiple files. This example shows a LiveAction method in a LiveComponent.

```php
// src/Twig/Components/FileUpload.php
namespace App\Twig\Components;

use Symfony\Component\HttpFoundation\Request;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveAction;
use Symfony\UX\LiveComponent\DefaultActionTrait;

#[AsLiveComponent]
class FileUpload
{
    use DefaultActionTrait;

    #[LiveAction]
    public function myAction(Request $request)
    {
        $file = $request->files->get('my_file');
        $multiple = $request->files->all('multiple');

        // Handle files
    }
}
```

--------------------------------

### Input model validation modifiers examples

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Examples of min_length and min_value/max_value modifiers to reduce server requests and provide frontend validation.

```html
<!-- Do not trigger model update until 3 characters are typed -->
<input data-model="min_length(3)|username" type="text" value="" />

<!-- Only trigger updates when value number is between 10 and 100 -->
<input data-model="min_value(10)|max_value(100)|quantity" type="number" value="20" />
```

--------------------------------

### connect(): void

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/live-controller.md

Connects the component (registers it, triggers connect hooks), starts observing attribute mutations on the element, registers the input and change listeners, and dispatches the live:connect event.

```APIDOC
## connect(): void

### Description
Connects the component (registers it, triggers `connect` hooks), starts observing attribute mutations on the element, registers the `input` and `change` listeners, and dispatches the `live:connect` event.

### Method
connect

### Returns
- **void**
```

--------------------------------

### LiveProp with hydrateWith and dehydrateWith methods

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Take full control of hydration by setting 'hydrateWith' and 'dehydrateWith' options. The example shows custom methods for dehydrating and hydrating an AddressDto.

```php
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']);
    }
}
```

--------------------------------

### LiveResponse::downloadUrl() example

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-live-response.md

Points the browser at a URL it downloads itself, while the component re-renders as usual. Throws \InvalidArgumentException when $url is blank.

```php
#[LiveAction]
public function export(): LiveResponse
{
    return LiveResponse::downloadUrl($this->generateUrl('app_export_download'));
}
```

--------------------------------

### Example usage of DefaultActionTrait

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-traits.md

Example live component SearchForm that uses DefaultActionTrait and other traits. The #[LiveProp(writable: true)] attribute makes the query property writable.

```php
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\DefaultActionTrait;
use Symfony\UX\LiveComponent\ValidatableComponentTrait;

#[AsLiveComponent]
class SearchForm
{
    use DefaultActionTrait;
    use ValidatableComponentTrait;
    use ComponentToolsTrait;

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

--------------------------------

### Stream large file download with resource (PHP)

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Pass a resource to downloadFile() to stream the file, avoiding holding it in memory. This example uses a filesystem readStream and includes the file size as the fourth argument.

```php
#[LiveAction]
public function exportLarge(): LiveResponse
{
    return LiveResponse::downloadFile(
        $this->filesystem->readStream('reports/2026.csv'),
        'report.csv',
        'text/csv',
        $this->filesystem->fileSize('reports/2026.csv'),
    );
}
```

--------------------------------

### LiveProp with UrlMapping attribute

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-metadata.md

Example of using the UrlMapping attribute to map a LiveProp to the URL query parameter 'q'. The mapPath is set to false, so the prop is used as a query parameter.

```php
#[LiveProp(url: new UrlMapping(as: 'q', mapPath: false))]
public string $query = '';
```

--------------------------------

### render(): Promise<BackendResponse>

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component.md

Starts a request immediately (no debounce) and returns the promise that resolves with the BackendResponse once the render is processed.

```APIDOC
## render(): Promise<BackendResponse>

### Description
Starts a request immediately (no debounce) and returns the promise that resolves with the BackendResponse once the render is processed.

### Method
render

### Signature
`render(): Promise<BackendResponse>`

### Returns
- **Promise<BackendResponse>** - The promise that resolves with the BackendResponse.

### Example
```ts
render(): Promise<BackendResponse> {
    const promise = this.nextRequestPromise;
    this.tryStartingRequest();
    return promise;
}
```
```

--------------------------------

### set method usage example

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component.md

Sets the firstName model to 'Ryan' with re-render and a 100ms debounce.

```typescript
await component.set('firstName', 'Ryan', true, 100);
```

--------------------------------

### LiveProp with DateTime format option

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Use the 'format' option on a writable LiveProp to control the frontend model format for DateTime instances. The example uses 'Y-m-d' format and binds to an input with data-model.

```php
#[LiveProp(writable: true, format: 'Y-m-d')]
public ?\DateTime $publishOn = null;
```

```html+twig
<input type="date" data-model="publishOn">
```

--------------------------------

### action(name, args?, debounce?): Promise<BackendResponse>

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component.md

Queues a live action and starts a debounced request. Returns the pending request promise.

```APIDOC
## action(name, args?, debounce?): Promise<BackendResponse>

### Description
Queues a live action and starts a debounced request. Returns the pending request promise.

### Method
action

### Signature
`action(name: string, args: any = {}, debounce: number | boolean = false): Promise<BackendResponse>`

### Parameters
- **name** (string) - Required - Live action name
- **args** (any) - Optional - Default: `{}` - Action arguments
- **debounce** (number | boolean) - Optional - Default: `false` - Debounce before the request

### Returns
- **Promise<BackendResponse>** - The pending request promise.

### Example
```ts
const response = await component.action('save', { id: 42 }, true);
```
```

--------------------------------

### GET /{_live_component}/{_live_action}

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/endpoints.md

The main dynamic route for live component rendering and actions. It handles initial renders, single actions, and batch actions depending on the path and HTTP method.

```APIDOC
## [GET] /{_live_component}/{_live_action}

### Description
This route is used for initial renders and action calls. The `_live_action` defaults to `get` for re-rendering. Path variants include `/{_live_component}` or `/{_live_component}/get` for default action, `/{_live_component}/{actionName}` for a single action (POST), and `/{_live_component}/_batch` for batch action (POST).

### Method
GET

### Endpoint
/{_live_component}/{_live_action}

### Parameters
#### Path Parameters
- **_live_component** (string) - Required - The component name (URL-encoded).
- **_live_action** (string) - Optional - The action name; defaults to `get`.

### Request Example
GET /my-component/get

### Response
#### Success Response (200)
- Returns the rendered component HTML.

#### Response Example
(HTML content)

```

--------------------------------

### TodoComponentTest using InteractsWithLiveComponents

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-test-utilities.md

Example test class extending `KernelTestCase` and using the `InteractsWithLiveComponents` trait. It creates a live component, calls a method, and asserts the rendered output contains a string.

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

class TodoComponentTest extends KernelTestCase
{
    use InteractsWithLiveComponents;

    public function testAddTodo(): void
    {
        $component = $this->createLiveComponent('TodoList', ['items' => ['one']]);
        $component->call('addItem', ['label' => 'two']);

        $this->assertStringContainsString('two', $component->render()->toString());
    }
}
```

--------------------------------

### LiveResponse::downloadFile() example

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-live-response.md

Sends a file along with the re-rendered component in a single response. Throws \InvalidArgumentException for unsupported content type, missing/blank filename, size contradiction, or line break in content type.

```php
#[LiveAction]
public function exportCsv(): LiveResponse
{
    $csv = "id,name\n1,Ryan\n";

    return LiveResponse::downloadFile($csv, 'export.csv', 'text/csv');
}
```

--------------------------------

### Testing Live Components with InteractsWithLiveComponents

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Complete example of using the InteractsWithLiveComponents trait to render, interact, and assert on Live Components. Covers calling live actions, emitting events, dispatching browser events, setting props, submitting forms, and accessing the component object.

```php
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(...)]);

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

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

            // Assert that the event was emitted
            $this->assertComponentEmitEvent($testComponent->render(), 'increaseEvent')
                // optionally, you can assert that the event was emitted with specific data...
                ->withData(['amount' => 2, 'unit' => 'kg'])
                // ... or only with a subset of data
                ->withDataSubset(['amount' => 2])
            ;

            // Assert that an event was not emitted
            $this->assertComponentNotEmitEvent($testComponent->render(), 'decreaseEvent');

            // dispatch browser events
            $testComponent
                ->dispatchBrowserEvent('browserEvent')
                ->dispatchBrowserEvent('browserEvent', ['amount' => 2, 'unit' => 'kg']) // dispatch a browser event with arguments
            ;

            // Assert that the event was dispatched
            $this->assertComponentDispatchBrowserEvent($testComponent->render(), 'browserEvent')
                // optionally, you can assert that the event was dispatched with specific data...
                ->withPayload(['amount' => 2, 'unit' => 'kg'])
                // ... or only with a subset of data
                ->withPayloadSubset(['amount' => 2])
            ;

            // Assert that an event was not dispatched
            $this->assertComponentNotDispatchBrowserEvent($testComponent->render(), 'otherBrowserEvent');

            // 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);
        }
    }
```

--------------------------------

### buildRequest(props, actions, updated, children, updatedPropsFromParent, files): { url: string; fetchOptions: RequestInit }

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/request-builder.md

Builds the request URL and fetch options for a live component request. It decides between GET and POST, and between single action and batch URLs. It sets shared headers and handles file uploads.

```APIDOC
## buildRequest(props, actions, updated, children, updatedPropsFromParent, files)

### Description
Builds the URL and fetch options for a live component request. It decides between a GET (query-string) request and a POST (multipart form) request, and between a single action URL and the `_batch` URL.

### Parameters
- **props** (any) - Required - Original props.
- **actions** (BackendAction[]) - Required - Actions to execute.
- **updated** ({ [key: string]: any }) - Required - Updated models.
- **children** (ChildrenFingerprints) - Required - Child fingerprints.
- **updatedPropsFromParent** ({ [key: string]: any }) - Required - Props from parent.
- **files** ({ [key: string]: FileList }) - Required - Files to upload.

### Returns
- **url** (string) - The request URL.
- **fetchOptions** (RequestInit) - The fetch options.

### Behavior

**Shared headers** on every request:

```
Accept: application/vnd.live-component+html
X-Requested-With: XMLHttpRequest
X-Live-Url: <current pathname + search>
```

**GET request** is used only when all of these hold:
- there are no actions (`actions.length === 0`);
- there are no files;
- the configured method is `'get'`;
- the encoded JSON data fits in the URL (`willDataFitInUrl` — the combined length stays under 1500 characters).

The query parameters are: `props` (JSON), `updated` (JSON), `children` (JSON, only when non-empty) and `propsFromParent` (JSON, only when non-empty). `fetchOptions.method = 'GET'`.

**POST request** is used otherwise:
- `fetchOptions.method = 'POST'`;
- the body is a `FormData` with a `data` field containing a JSON string:
  ```json
  { "props": {}, "updated": {}, "args": {}, "actions": [], "children": {}, "propsFromParent": {} }
  ```
- files are appended to the `FormData` under their model key;
- with a single action: `url += '/' + encodeURIComponent(action.name)` and `requestData.args = actions[0].args`;
- with multiple actions: `url += '/_batch'` and `requestData.actions = actions`.

The `credentials` option is copied into `fetchOptions.credentials`.

### Example
```ts
import RequestBuilder from './Backend/RequestBuilder';

const builder = new RequestBuilder('http://localhost/_components/todo', 'post', 'same-origin');
const { url, fetchOptions } = builder.buildRequest(
    { title: 'Hello' },
    [{ name: 'save', args: {} }],
    { title: 'Hello world' },
    {},
    {},
    {}
);

// POST http://localhost/_components/todo/save with FormData { data: '{"props":{...},"updated":{...},"args":{}}' }
```
```

--------------------------------

### Using ComponentWithFormTrait in a ProductForm live component

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-traits.md

Shows a live component class that uses ComponentWithFormTrait and implements the required instantiateForm() method. The example creates a ProductType form bound to the $this->product property. The trait automatically handles form submission, validation, and rendering.

```php
use Symfony\UX\LiveComponent\ComponentWithFormTrait;

#[AsLiveComponent]
class ProductForm
{
    use ComponentWithFormTrait;

    protected function instantiateForm(): FormInterface
    {
        return $this->createForm(ProductType::class, $this->product);
    }
}
```

--------------------------------

### Example usage of RequestBuilder

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/request-builder.md

Creates a RequestBuilder instance and calls buildRequest with sample props, actions, and updated models. The resulting URL and fetchOptions are destructured. The comment shows the expected POST request to the single action URL with FormData.

```typescript
import RequestBuilder from './Backend/RequestBuilder';

const builder = new RequestBuilder('http://localhost/_components/todo', 'post', 'same-origin');
const { url, fetchOptions } = builder.buildRequest(
    { title: 'Hello' },
    [{ name: 'save', args: {} }],
    { title: 'Hello world' },
    {},
    {},
    {}
);

// POST http://localhost/_components/todo/save with FormData { data: '{"props":{...},"updated":{...},"args":{}}' }
```

--------------------------------

### LiveController usage in a Stimulus controller

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/live-controller.md

Shows how to access the LiveController instance from a custom Stimulus controller and call its action() method. The example imports LiveController and Stimulus Controller, then in connect() it queries the element with data-controller~="live" and assigns its __component property. The save() method calls action('save', { status: 'published' }) and logs the response body length, catching errors.

```typescript
import LiveController from '@symfony/ux-live-component';

// Inside a custom Stimulus controller wrapping the live component:
import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
    connect() {
        const live = this.element.querySelector('[data-controller~="live"]');
        this.component = window.__live = live.__component;
    }

    async save() {
        try {
            const response = await this.component.action('save', { status: 'published' });
            console.log('rendered, body length', (await response.getBody()).length);
        } catch (e) {
            console.error('request failed', e);
        }
    }
}
```

--------------------------------

### initialize(): void

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/live-controller.md

Called once by Stimulus. Creates the MutationObserver, then calls createComponent(), which instantiates the Component, wraps it with proxifyComponent() and exposes it on this.element.__component. It also attaches the built-in plugins.

```APIDOC
## initialize(): void

### Description
Called once by Stimulus. Creates the `MutationObserver`, then calls `createComponent()`, which instantiates the `Component`, wraps it with `proxifyComponent()` and exposes it on `this.element.__component`. It also attaches the built-in plugins: `LoadingPlugin`, `LazyPlugin`, `ValidatedFieldsPlugin`, `PageUnloadingPlugin`, `PollingPlugin`, `SetValueOntoModelFieldsPlugin` and `ChildComponentPlugin`.

### Method
initialize

### Returns
- **void**
```

--------------------------------

### Example usage of parseDirectives and getModelBinding

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/directives.md

Parses a data-model directive string and interprets it into a ModelBinding. The example shows the resulting binding with modelName 'user.firstName', debounce 250, and targetEventName 'change'.

```typescript
import { parseDirectives } from './Directive/directives_parser';
import getModelBinding from './Directive/get_model_binding';

const [directive] = parseDirectives('on(change)|debounce(250)|user[firstName]');
const binding = getModelBinding(directive);

// binding = {
//   modelName: 'user.firstName',
//   innerModelName: null,
//   shouldRender: true,
//   debounce: 250,
//   targetEventName: 'change',
//   minLength: null, maxLength: null, minValue: null, maxValue: null,
// }
```

--------------------------------

### ComponentHooks type definition

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/types.md

Defines the shape of all lifecycle hooks for a live component. Each hook receives specific parameters, such as `component`, `requestConfig`, or `html, backendResponse, controls`, and may return a promise. `render:started` can set `shouldRender = false` via `PageUnloadingPlugin`; `request:started` is used by `ChildComponentPlugin` to inject `children`.

```typescript
type ComponentHooks = {
    connect: (component: Component) => MaybePromise;
    disconnect: (component: Component) => MaybePromise;
    'request:started': (requestConfig: any) => MaybePromise;
    'render:started': (
        html: string,
        backendResponse: BackendResponse,
        controls: { shouldRender: boolean }
    ) => MaybePromise;
    'render:finished': (component: Component) => MaybePromise;
    'response:error': (backendResponse: BackendResponse, controls: { displayError: boolean }) => MaybePromise;
    'loading.state:started': (element: HTMLElement, request: BackendRequest) => MaybePromise;
    'loading.state:finished': (element: HTMLElement) => MaybePromise;
    'model:set': (model: string, value: any, component: Component) => MaybePromise;
};
```

--------------------------------

### createLiveComponent

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-test-utilities.md

Creates a live component test wrapper. Throws `\LogicException` if not used on a `KernelTestCase`, or if the component is not live.

```APIDOC
## `createLiveComponent(string $name, array $data = [], ?KernelBrowser $client = null)`

### Description
Creates a live component test wrapper. Throws `\LogicException` if not used on a `KernelTestCase`, or if the component is not live.

### Parameters
- **name** (string) - Required - The name of the live component.
- **data** (array) - Optional - Initial data for the component. Defaults to `[]`.
- **client** (`?KernelBrowser`) - Optional - A kernel browser instance. Defaults to `null`.

### Returns
`TestLiveComponent` - A test wrapper for the live component.
```

--------------------------------

### Backend

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/backend.md

Documentation for the Backend class, including its constructor and makeRequest method.

```APIDOC
## Backend (default export)

### Description
Creates a backend instance that can make requests to the Live Component endpoint.

### Constructor
`new Backend(url: string, method: string, fetchOptions?: object)`

### Methods

#### `makeRequest(data: object, actions: object[], updatedModels: object, ...): BackendRequest`
Creates a new `BackendRequest` with the given data, actions, and updated models.

### Example
```ts
import Backend from './Backend/Backend';

const backend = new Backend('/_components/todo', 'post', 'same-origin');
const request = backend.makeRequest(
    { name: 'Ryan', food: 5 },
    [{ name: 'save', args: { status: 'published' } }],
    { name: 'Kevin' },
    {},
    {},
    {}
);
```
```

--------------------------------

### Configure live_component bundle options

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/configuration.md

Configure the Symfony UX Live Component bundle. The secret is used for fingerprints and checksums, defaults to '%kernel.secret%', and must not be empty. The fetch_credentials option defaults to 'same-origin' and accepts 'include' or 'omit'.

```yaml
# config/packages/live_component.yaml
live_component:
    secret: '%env(APP_SECRET)%'      # default: '%kernel.secret%'
    fetch_credentials: 'same-origin' # 'same-origin' | 'include' | 'omit'
```

--------------------------------

### action method usage example

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component.md

Triggers the 'save' action with an id argument and debounce enabled.

```typescript
const response = await component.action('save', { id: 42 }, true);
```

--------------------------------

### EditPost component class

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Full example of an embedded component with writable LiveProp and a LiveAction to save the entity.

```php
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');
    }
}
```

--------------------------------

### emitUp(event: any): void

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/live-controller.md

Same as emit, but calls component.emitUp(...) (targets parent components).

```APIDOC
## emitUp(event: any): void

### Description
Same as `emit`, but calls `component.emitUp(...)` (targets parent components).

### Method
emitUp

### Parameters
- **event** (any) - The DOM event containing the `data-live-event-param` attribute.

### Returns
- **void**
```

--------------------------------

### max_length validation modifier example

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Validate that a text-like input has a value length not higher than the specified length.

```html
<!-- Validates that the username is not longer than 10 characters -->
<input type="text" data-model="max_length(10)|username">
```

--------------------------------

### min_length validation modifier example

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Validate that a text-like input has a value length not less than the specified length.

```html
<!-- Validate the search term is at least 3 characters long-->
<input type="search" data-model="min_length(3)|search">
```

--------------------------------

### Configure fetch credentials

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Set fetchCredentials to 'include' to send credentials on cross-origin requests. Default is 'same-origin'.

```diff
// src/Twig/Components/RandomNumber.php
  use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
  use Symfony\UX\LiveComponent\DefaultActionTrait;

- #[AsLiveComponent]
+ #[AsLiveComponent(fetchCredentials: 'include')]
  class RandomNumber
  {
      use DefaultActionTrait;
  }
```

--------------------------------

### max_value validation modifier example

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Validate that a number or range input has a numeric value not higher than the specified value.

```html
<!-- Validate that the year is not higher than 2025 -->
<input type="number" data-model="max_value(2025)|year">
```

--------------------------------

### min_value validation modifier example

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Validate that a number or range input has a numeric value not less than the specified value.

```html
<!-- Validate that the age is not less than 18 -->
<input type="number" data-model="min_value(18)|age">
```

--------------------------------

### Map LiveProp to route path with UrlMapping(mapPath: true)

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Shows how to bind a LiveProp to a route parameter instead of a query parameter by using the mapPath option in UrlMapping. The route must define a matching parameter; otherwise it falls back to a query parameter.

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

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

    // ...
}
```

```php
// src/Controller/SearchController.php
// ...

#[Route('/search/{query}')]
public function __invoke(string $query): Response
{
    // ... render template that uses SearchModule component ...
}
```

--------------------------------

### debug:live-component

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-twig-and-runtime.md

Lists all live components or shows details for a specific component, including its LiveProps and LiveListeners. Returns success or failure based on component name resolution.

```APIDOC
## debug:live-component

### Description
Lists all live components in a table, or shows details for a specific component including its LiveProps and LiveListeners.

### Method
CLI Command

### Endpoint
`debug:live-component`

### Parameters
#### Arguments
- **name** (string) - Optional - A LiveComponent name or part of the name.

#### Options
- **--listening** (string) - Optional - Filter to components listening to the given event.

### Response
#### Success Response
- Returns `Command::SUCCESS` when the component is found or when listing all components.

#### Error Response
- Returns `Command::FAILURE` when an unknown component name is provided.

### Example
```
php bin/console debug:live-component
php bin/console debug:live-component MyComponent
php bin/console debug:live-component --listening=my-event
```
```

--------------------------------

### files(key: string, input: HTMLInputElement): void

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/component.md

Schedules a file input to be sent with the next request, keyed by the model name.

```APIDOC
## files(key: string, input: HTMLInputElement): void

### Description
Schedules a file input to be sent with the next request, keyed by the model name.

### Method
files

### Signature
`files(key: string, input: HTMLInputElement): void`

### Parameters
- **key** (string) - Required - The model name key.
- **input** (HTMLInputElement) - Required - The file input element.
```

--------------------------------

### PostHydrate hook with priority

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Shows how to use the #[PostHydrate] hook with a priority argument to control execution order. Higher priority runs first.

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

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

--------------------------------

### constructor(response: Response)

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/backend-response.md

Creates a new BackendResponse instance wrapping the fetch Response object.

```APIDOC
## Constructor

### Description
Creates a new BackendResponse instance wrapping the fetch Response object.

### Method
constructor

### Parameters
- **response** (Response) - Required - The fetch Response object

### Response
No return value.
```

--------------------------------

### Listen to browser event in Stimulus controller

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Example Stimulus controller that listens for the 'modal:close' event and hides a Bootstrap modal.

```javascript
// assets/controllers/bootstrap-modal-controller.js
import { Controller } from '@hotwired/stimulus';
import Modal from 'bootstrap/js/dist/modal';

export default class extends Controller {
    modal = null;

    initialize() {
        this.modal = Modal.getOrCreateInstance(this.element);
        window.addEventListener('modal:close', () => this.modal.hide());
    }
}
```

--------------------------------

### LiveProp with DTO type

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Use a DTO with LiveProp as long as the property has the correct type. The example shows a simple DTO property.

```php
class ComponentWithAddressDto
{
    #[LiveProp]
    public AddressDto $addressDto;
}
```

--------------------------------

### LiveController.action()

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/live-controller.md

Executes a live component action with optional parameters. Returns a response object that can be used to inspect the rendered body.

```APIDOC
## action()

### Description
Triggers a live component action, sending a request to the server to execute the action and re-render the component. Returns a response object with a `getBody()` method to retrieve the rendered HTML.

### Method
POST (implied by usage)

### Endpoint
Not specified (internal to the live component system)

### Parameters
- **actionName** (string) - Required - The name of the action to execute.
- **params** (object) - Optional - Additional parameters to pass to the action.

### Request Example
ts
const response = await this.component.action('save', { status: 'published' });


### Response
#### Success Response
- **response** (object) - Contains a `getBody()` method that returns a Promise resolving to the response body string.

#### Response Example
ts
const body = await response.getBody();
console.log('rendered, body length', body.length);


### Errors
- Throws `Error` when `data-live-action-param` is missing.

```

--------------------------------

### Twig component with block content

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Example of a Twig component template that sets a message variable inside a block, demonstrating that it works during re-rendering.

```twig
{# templates/some_page.html.twig #}
{% component Alert %}
    {% block content %}
        {% set message = 'this works during re-rendering!' %}
        {{ message }}
    {% endblock %}
{% endcomponent %}
```

--------------------------------

### Using BackendResponse methods after an action

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/backend-response.md

Example of calling component.action('export') and then using getBody, getLiveUrl, getDownload, and isRemoved to access the response data.

```typescript
import { getComponent } from '@symfony/ux-live-component';

const component = await getComponent(document.querySelector('#counter'));
const response = await component.action('export');

const html = await response.getBody();           // re-rendered component HTML
const liveUrl = response.getLiveUrl();           // URL reflecting current state
const download = response.getDownload();         // { filename, blob } if a file rode along
const isRemoved = response.isRemoved();          // true if component is being removed
```

--------------------------------

### Test live action redirect and customize test client

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Shows how to test a live action that redirects, authenticate a user, set the '_locale' route parameter, and customize the test client before creating a live component. The InteractsWithLiveComponents trait requires extending KernelTestCase.

```php
// 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,
);
```

--------------------------------

### Create a live component with make:twig-component

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Command to create a new live component using Symfony MakerBundle.

```terminal
$ php bin/console make:twig-component --live EditPost
```

--------------------------------

### Poll with custom action and optional delay

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Triggers the 'save' action on each poll. Includes a commented example showing how to add a delay(2000) modifier.

```html+twig
<div
    {{ attributes }}

    data-poll="save"
    {#
    Or add a delay() modifier:
    data-poll="delay(2000)|save"
    #}
>
```

--------------------------------

### Dynamic template with FromMethod

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Uses the FromMethod class to dynamically choose a template based on a writable 'layout' property.

```php
#[AsLiveComponent(template: new FromMethod('getTemplate'))]
class SearchResults
{
    #[LiveProp(writable: true)]
    public string $layout = 'rows';

    public function getTemplate(): string
    {
        return 'rows' === $this->layout
            ? 'components/SearchResults/rows.html.twig'
            : 'components/SearchResults/grid.html.twig';
    }
}
```

--------------------------------

### PHP: Action with LiveArg parameters

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Defines an action that accepts arguments using the #[LiveArg] attribute. Shows how to map action parameters to component properties.

```php
// 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;
    }
}
```

--------------------------------

### Validate on change with on(change) modifier

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Use the on(change) modifier on data-model to validate only when the field changes, not on every input event. Example for an email input.

```html+twig
<input
    type="email"
    data-model="on(change)|user.email"
    class="{{ _errors.has('user.email') ? 'is-invalid' : '' }}"
>
```

--------------------------------

### LiveComponentRuntime class with constructor and methods

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/php-twig-and-runtime.md

Shows the runtime class that implements the Twig functions. The constructor injects dependencies, and the methods getComponentUrl and liveAction are defined with their signatures.

```php
final class LiveComponentRuntime
{
    public function __construct(
        private LiveComponentHydrator $hydrator,
        private ComponentFactory $factory,
        private UrlGeneratorInterface $urlGenerator,
        private LiveComponentMetadataFactory $metadataFactory,
        private StimulusHelper $stimulusHelper,
    ) { }

    public function getComponentUrl(string $name, array $props = []): string { ... }
    public function liveAction(string $actionName, array $parameters = [], array $modifiers = [], ?string $event = null): StimulusAttributes { ... }
}
```

--------------------------------

### Custom hydration extension for Food object

Source: https://github.com/symfony/ux-live-component/blob/3.x/doc/index.rst

Create a custom hydration extension by implementing HydrationExtensionInterface. The example shows a class that supports Food subclasses.

```php
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);
    }
}
```

--------------------------------

### Example output of parseDirectives

Source: https://github.com/symfony/ux-live-component/blob/3.x/_autodocs/api-reference/directives.md

Shows the parsed structure for the input 'addClass(foo) removeAttribute(bar)'. Each directive has an action, args array, and empty modifiers array.

```typescript
[
    { action: 'addClass', args: ['foo'], modifiers: [] },
    { action: 'removeAttribute', args: ['bar'], modifiers: [] }
]
```
Tokens:
Raw