Twig Components Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bitbirddev/twig-components-bundle
   

   Ensure bitbirddev/web-components and vidstack/player are also installed (handled automatically via dependencies).

2. Register the Bundle: Add to config/bundles.php:

   return [
       // ...
       BitbirdDev\TwigComponentsBundle\BitbirdDevTwigComponentsBundle::class => ['all' => true],
   ];
   

3. First Use Case: Embed a YouTube video in a Twig template:

   <twig:media-player video="https://www.youtube.com/watch?v=DFYRQ_zQ-gk" />
   

   Verify the bundle is registered by checking if the twig:media-player tag renders the player.

Where to Look First

• Documentation: The README provides clear examples for Pimcore-specific integrations (e.g., pimcore_video(), pimcore_asset()).
• Configuration: Check config/packages/bitbirddev_twig_components.yaml for default settings (e.g., privacy wall options).
• Templates: Override default Twig templates in templates/bundles/BitbirdDevTwigComponents/media_player.html.twig.

Implementation Patterns

Core Workflows

1. Pimcore Integration:

   • Use pimcore_video() or pimcore_asset() for CMS-managed videos:

     <twig:media-player :video="pimcore_video('video_field_name')" />
     

   • For custom DataObjects, implement a VideoHandler (see README).

2. Dynamic Sources: Pass an array of sources for adaptive playback:

   <twig:media-player :video="['/path/to/video.mp4', '//cdn.example.com/fallback.mp4']" />
   

3. Privacy Wall (Usercentrics): Enable via config (usercentrics: true) and pass consent status:

   <twig:media-player video="..." consent="{{ consent_status }}" />
   

Integration Tips

• VidStack Customization: Extend the player’s capabilities by passing VidStack-specific attributes:

  <twig:media-player video="..." :config="{
      'controls': false,
      'autoplay': true
  }" />
  

• Asset Pipeline: Use the class attribute to apply CSS classes for styling:

  <twig:media-player video="..." class="w-full max-w-md" />
  

• Lazy Loading: Combine with Twig’s {% autoescape %} or JavaScript lazy-load libraries for performance.

Gotchas and Tips

Pitfalls

1. Pimcore-Specific Dependencies:

   • The bundle assumes Pimcore’s pimcore_video() helper. Without Pimcore, use raw URLs or implement a VideoHandler for your ORM.
   • Fix: Mock the helper or extend the bundle’s VideoResolver service.

2. Privacy Wall Misconfiguration:

   • If usercentrics is enabled but consent logic is missing, videos may fail to load.
   • Fix: Ensure consent is passed to the component or handle it via JavaScript.

3. VidStack Version Conflicts: The bundle pins vidstack/player to a specific version. Upgrades may break compatibility.

   • Fix: Check the bundle’s composer.json and test thoroughly after updates.

4. CORS Issues: Direct asset URLs (e.g., http://example.com/video.mp4) may block playback due to CORS.

   • Fix: Use proxy endpoints or ensure CORS headers are configured on the server.

Debugging

• Template Overrides: If the component renders unexpectedly, verify overrides in templates/bundles/BitbirdDevTwigComponents/. Clear cache (php bin/console cache:clear) after changes.

• Console Logs: VidStack emits errors to the browser console. Inspect for:

  • Failed to load resource (CORS/URL issues).
  • Invalid source (malformed input).

Extension Points

1. Custom Video Handlers: Extend the BitbirdDev\TwigComponentsBundle\Video\VideoHandlerInterface to support non-Pimcore sources:

   // src/Service/CustomVideoHandler.php
   class CustomVideoHandler implements VideoHandlerInterface {
       public function resolve($input): string {
           // Transform input (e.g., API response) into a playable URL.
           return $playableUrl;
       }
   }
   

   Register as a service with the tag bitbirddev.twig_components.video_handler.

2. Twig Extensions: Add custom attributes to the component by extending the MediaPlayerExtension:

   // src/Twig/MediaPlayerExtension.php
   class CustomMediaPlayerExtension extends \BitbirdDev\TwigComponentsBundle\Twig\MediaPlayerExtension {
       public function getFunctions() {
           return array_merge(parent::getFunctions(), [
               new \Twig\TwigFunction('custom_media_player', [$this, 'renderCustomPlayer']),
           ]);
       }
   }
   

3. Configuration Overrides: Override default settings in config/packages/bitbirddev_twig_components.yaml:

   bitbirddev_twig_components:
       media_player:
           default_config:
               controls: true
               autoplay: false
           usercentrics:
               enabled: true
               consent_attribute: 'data-consent'
   

Performance Tips

• Preload Assets: Use VidStack’s preload config to hint browsers about resource priority:

  <twig:media-player :video="..." :config="{'preload': 'auto'}" />
  

• Fallback Sources: Always provide fallback sources (e.g., HLS for mobile) to avoid playback failures.