Cafe Smag Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   • Add the repository to composer.json under "repositories":

     "repositories": {
       "bibsdb/cafe-smag-bundle": {
         "type": "vcs",
         "url": "https://github.com/bibsdb/cafe-smag-bundle"
       }
     }
     

   • Require the bundle:

     composer require bibsdb/cafe-smag-bundle
     

   • Enable the bundle in config/bundles.php (Laravel 5.4+) or AppKernel.php (older versions):

     Bibsdb\CafeSmagBundle\BibsdbCafeSmagBundle::class => ['all' => true],
     

   • Load the template:

     php artisan bibsdb:core:templates:load
     

2. First Use Case:

   • Enable the template in your admin panel (e.g., SonataAdmin, EasyAdmin, or custom backend).
   • Embed a video using the provided Twig template (e.g., {{ bibsdb_cafe_smag(videoId) }}).
   • Ensure the video URL is from a PLUS account (or a user with ads/controls disabled) to avoid unwanted UI elements.

Implementation Patterns

Core Workflows

1. Video Embedding:

   • Use the Twig extension bibsdb_cafe_smag to render the player:

     {{ bibsdb_cafe_smag('YOUR_VIDEO_ID', {
       'width': 800,
       'height': 450,
       'autoplay': false
     }) }}
     

   • Pass optional parameters like width, height, autoplay, or controls (if allowed by the video source).

2. Admin Integration:

   • If using SonataAdmin/EasyAdmin, extend the entity class to include a CafeSmagVideo field:

     $builder
         ->add('videoId', CafeSmagVideoType::class, [
             'label' => 'Cafe Smag Video',
             'required' => false,
         ]);
     

   • The bundle provides a CafeSmagVideoType form type for easy integration.

3. Dynamic Loading:

   • Load the template dynamically via JavaScript if needed:

     // Example: Fetch and render a video after page load
     fetch('/api/video/embed?videoId=123')
         .then(response => response.text())
         .then(html => {
             document.getElementById('video-container').innerHTML = html;
         });
     

4. API Integration:

   • Use the bundle’s service container to fetch video metadata (if extended):

     $videoService = $this->container->get('bibsdb_cafe_smag.video_service');
     $metadata = $videoService->getMetadata('VIDEO_ID');
     

Integration Tips

• Asset Management: The bundle auto-registers the player.js from CafeSmag. Ensure your Laravel mix/webpack config doesn’t conflict with its asset paths. Example (if overriding):

  // webpack.mix.js
  mix.js('resources/js/cafe-smag-player.js', 'public/js')
      .alias({
          'cafe-smag-player': path.resolve(__dirname, 'node_modules/cafe-smag/player.js')
      });
  

• Caching: Preload the template in your cache layer (e.g., Symfony’s HTTP cache) if serving static video pages:

  # config/cache.php
  'default' => [
      'pool' => 'file_cache',
      'prefix' => 'cafe_smag_',
  ],
  

• Localization: Override the bundle’s translations in config/packages/bibsdb_cafe_smag.yaml:

  twig:
      globals:
          cafe_smag:
              player_title: "Custom Player Title"
  

Gotchas and Tips

Pitfalls

1. Ads/Controls Persistence:

   • Videos must originate from a PLUS account (or a user with ads/controls disabled at cafe-smag.com).
   • Debugging: Check the network tab for blocked requests or unexpected UI elements (e.g., cafe-smag.com/ads/ calls).

2. Template Loading:

   • The bibsdb:core:templates:load command must run post-installation. Skipping this will break Twig rendering.
   • Fix: Manually clear the cache if the command fails:

     php artisan cache:clear
     php artisan config:clear
     

3. JavaScript Conflicts:

   • If player.js fails to load, ensure:
     • No other script is overriding window.CafeSmagPlayer.
     • The bundle’s assets are not being minified/obfuscated by Laravel Mix.
   • Workaround: Explicitly load the script in your layout:

     {{ encore_entry_script_tags('cafe-smag-player') }}
     

4. Video ID Validation:

   • The bundle assumes videoId is a string. Pass invalid IDs (e.g., null, 0) to trigger errors.
   • Tip: Add validation in your form type:

     $builder->add('videoId', CafeSmagVideoType::class, [
         'constraints' => [new NotBlank(), new Length(min: 3)],
     ]);
     

Debugging Tips

• Log Player Events: Extend the player’s event system by overriding the Twig template:

  {% extends 'BibsdbCafeSmagBundle:default:player.html.twig' %}
  {% block cafe_smag_events %}
      {{ parent() }}
      <script>
          document.addEventListener('CafeSmagPlayerReady', (e) => {
              console.log('Player loaded:', e.detail.player);
          });
      </script>
  {% endblock %}
  

• Check Console Errors: Common issues:

  • Uncaught ReferenceError: CafeSmagPlayer is not defined: Missing JS asset.
  • Failed to load resource: net::ERR_BLOCKED_BY_CLIENT: Ad-blocker interfering (disable temporarily for testing).

Extension Points

1. Custom Player Config: Override the default player options in your Twig template:

   {{ bibsdb_cafe_smag(videoId, {
       'playerOptions': {
           'theme': 'dark',
           'quality': 'hd'
       }
   }) }}
   

2. Hook into Video Events: Use the bundle’s event system (if available) or attach listeners via JavaScript:

   document.querySelector('.cafe-smag-player').addEventListener('play', (e) => {
       console.log('Video started');
   });
   

3. Add Metadata Fields: Extend the CafeSmagVideoType to include custom fields (e.g., title, description):

   // src/Form/Extension/CafeSmagVideoExtension.php
   public function buildForm(FormBuilderInterface $builder, array $options) {
       $builder->add('title', TextType::class);
   }
   

4. Server-Side Video Processing: Use the bundle’s service to pre-process video URLs (e.g., add tracking parameters):

   $processedUrl = $this->container->get('bibsdb_cafe_smag.video_processor')
       ->process('VIDEO_ID', ['utm_source' => 'laravel']);