Symfony UX Live Component

The #[LiveProp] attribute marks a property as "stateful". When a component re-renders (e.g., via an Ajax call), LiveProps are automatically re-hydrated with their previous values. This allows the component to "remember" user input or configuration across interactions.

Key behaviors:

• Statefulness: Without #[LiveProp], properties will not persist their values during a re-render.
• Services: You do not need to mark services as #[LiveProp] because they are autowired by Symfony each time the component is rendered.
• Supported Types: LiveProps must be serializable to JavaScript. Supported types include:
  • Scalars (int, float, string, bool, null)
  • Arrays of scalars
  • Enums
  • DateTime objects
  • Doctrine entities
  • DTOs (and arrays of DTOs)

Example usage:

#[AsLiveComponent]
class RandomNumber
{
    use DefaultActionTrait;

    #[LiveProp]
    public int $max = 1000;

    public function getRandomNumber(): int
    {
        return rand(0, $this->max);
    }
}

Render the component with specific state:

{{ component('RandomNumber', { max: 500 }) }}

Live components behave like real Symfony controllers. This provides several advantages:

1. Autowiring: You can autowire services (like LoggerInterface) directly into your #[LiveAction] methods.
2. Security: You can use standard Symfony security attributes like #[IsGranted] on the entire component class or specific actions.
3. Redirects: By extending AbstractController, your component can use standard controller shortcuts like $this->redirectToRoute() or $this->addFlash() within your actions.
4. CSRF Protection: Actions are sent via POST with a custom Accept header that is automatically validated. To maintain security, ensure your CORS configuration does not use Access-Control-Allow-Origin: *.

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

use Symfony\Component\Security\Http\Attribute\IsGranted;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\UX\LiveComponent\Attribute\LiveAction;
use Psr\Log\LoggerInterface;

class RandomNumber extends AbstractController
{
    #[LiveAction]
    #[IsGranted('ROLE_USER')]
    public function resetMax(LoggerInterface $logger)
    {
        $this->max = 1000;
        $logger->debug('The min/max were reset!');
        
        $this->addFlash('success', 'Max has been reset!');
        return $this->redirectToRoute('app_random_number');
    }
}

As of version 3.5, you can trigger file downloads from a LiveAction by returning a LiveResponse. The component will still re-render, allowing state changes to persist on the page while the browser handles the download.

Best Practices

• Use LiveResponse::downloadUrl() whenever possible. This points the browser to a dedicated route. It is more efficient as it uses native browser downloading, supports range requests/resuming, and doesn't consume server memory for the file content.
• Use LiveResponse::downloadFile() only when a dedicated URL cannot exist, such as when the action generates the file content dynamically.

Constraints

• You can only return a LiveResponse from a LiveAction or a LiveListener via a POST request.
• Do not return a LiveResponse from the default action (which runs on every re-render) or from a GET request.
• An action can return either a LiveResponse or a redirect, but not both.

You can use Data Transfer Objects (DTOs) as LiveProp values.

Requirements:

• The property must have the correct type hint.
• The DTO cannot have constructor arguments.
• It uses Symfony's PropertyAccess component, so it supports both public properties and getter/setter methods.
• For collections of DTOs, use PHPDoc (e.g., /** @var AddressDto[] */).

Hydration Strategies:

1. Default: Uses public properties or getter/setter methods.
2. Serializer: Use #[LiveProp(useSerializerForHydration: true)] to use Symfony's Serializer. You can also provide a serializationContext.
3. Manual Methods: Use hydrateWith and dehydrateWith to specify custom method names for the process.
4. Hydration Extensions: Implement HydrationExtensionInterface for global, type-based custom logic.

// Option 1: Manual Methods
#[LiveProp(hydrateWith: 'hydrateAddress', dehydrateWith: 'dehydrateAddress')]
public AddressDto $addressDto;

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

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