Ux Twig Component Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require danmartuszewski/ux-twig-component
   

   Ensure your Laravel project uses Symfony’s Twig bridge (if not, install via composer require symfony/twig-bundle).

2. Register the Twig Component Bundle Add to config/app.php under providers:

   Symfony\UX\TwigComponent\TwigComponentBundle::class,
   

3. Create Your First Component Generate a component class (e.g., AlertComponent) in app/Components/:

   namespace App\Components;
   use Symfony\UX\TwigComponent\AbstractComponent;
   
   class AlertComponent extends AbstractComponent {
       public string $type = 'success';
       public string $message;
       public static function getComponentName(): string { return 'alert'; }
       public static function getTemplate(): ?string { return '@App/components/alert.html.twig'; }
   }
   

4. Define the Twig Template Create resources/views/components/alert.html.twig:

   <div class="alert alert-{{ this.type }}">
       {{ this.message }}
   </div>
   

5. Use the Component in Twig In any Twig template (e.g., resources/views/home.blade.php):

   {{ component('alert', { message: 'Hello Twig Components!' }) }}
   

Implementation Patterns

Component Workflows

1. Reusable UI Units

   • Use for modular elements (e.g., modals, cards, alerts).
   • Example: A CardComponent with dynamic title/body/slot support.

2. Data Binding

   • Bind PHP objects to Twig via component properties:

     $user = User::find(1);
     return view('profile', ['user' => $user]);
     

     {{ component('user-card', { user: user }) }}
     

3. Slot-Based Layouts Extend AbstractComponent to support slots (like Vue/React):

   public function getSlots(): array { return ['header', 'footer']; }
   

   {{ component('card') }}
       {% slot('header') %}Title{% endslot %}
       Content
   {{ endcomponent('card') }}
   

4. Integration with Live Components Combine with symfony/ux-live-component for interactivity:

   use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
   
   #[AsLiveComponent]
   class InteractiveAlert extends AlertComponent { ... }
   

Best Practices

• Template Organization: Store templates in resources/views/components/ for clarity.
• Type Safety: Use PHP 8+ typed properties for IDE autocompletion.
• Component Registration: Avoid hardcoding paths; use @App/components/ namespace conventions.

Gotchas and Tips

Pitfalls

1. Template Paths

   • Ensure getTemplate() returns a valid Twig path (e.g., @App/components/alert.html.twig).
   • Fix: Use resources/views/components/ and prefix with @App/.

2. Caching Issues

   • Twig components may not auto-update during development.
   • Fix: Clear cache after changes:

     php artisan view:clear
     

3. Experimental Status

   • API may change; avoid heavy reliance on undocumented features.

4. Slot Scope

   • Slots are not automatically available in child components. Pass data explicitly:

     {{ component('child', { slotData: slot('header') }) }}
     

Debugging Tips

• Check Component Registration:

  php artisan twig:debug
  

• Validate Properties: Use dd($this) in the component class to inspect bound data.

Extension Points

1. Custom Component Traits Extend functionality via traits (e.g., for form handling):

   trait FormComponentTrait {
       public function getForm(): FormInterface { ... }
   }
   

2. Dynamic Templates Override getTemplate() to fetch templates dynamically:

   public static function getTemplate(): string {
       return '@App/components/' . self::getComponentName() . '.html.twig';
   }
   

3. Live Component Events Use Symfony UX’s event system for real-time updates:

   use Symfony\UX\LiveComponent\DefaultActionTrait;
   
   class LiveAlert extends AlertComponent {
       use DefaultActionTrait;
       public function dismiss(): void { ... }
   }