Pmk2 Cmar Live Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require campusdomar/pmk2-cmar-live-bundle
   

   Ensure your project meets Symfony 5.4+ and Laravel 8+ (via Symfony Bridge) requirements.

2. Enable the Bundle In config/bundles.php (Symfony) or bootstrap/app.php (Laravel):

   return [
       // ...
       CampusDomar\PuMuKIT2\CMARLiveBundle\PuMuKIT2CMARLiveBundle::class => ['all' => true],
   ];
   

3. First Use Case: Embed a Live Stream with Chat

   • Configure config/packages/pumukit2_cmar_live.yaml (default paths: config/packages/).
   • Use the Twig template for the live player in your view:

     {{ include('@PuMuKIT2CMARLive/Player/player.html.twig', {
         'streamKey': 'your_stream_key',
         'chatEnabled': true
     }) }}
     

   • For Laravel Blade, create a custom directive or use Symfony’s Twig integration:

     // routes/web.php
     Route::get('/live/{stream}', [LiveController::class, 'show']);
     

     // LiveController.php
     public function show($stream) {
         return view('live.player', ['streamKey' => $stream]);
     }
     

Implementation Patterns

Core Workflows

1. Stream Management

   • Use the Pumukit\LiveBundle\Manager\LiveManager service to start/stop streams programmatically:

     $liveManager = $this->container->get('pumukit.live.manager');
     $liveManager->startStream('your_stream_key');
     

   • Laravel service container binding (if not auto-wired):

     $this->app->bind('pumukit.live.manager', function ($app) {
         return new \Pumukit\LiveBundle\Manager\LiveManager(
             $app['pumukit.live.configuration']
         );
     });
     

2. Chat Integration

   • Enable chat via Twig/Blade template variables:

     {# Enable chat with custom CSS/JS #}
     {{ include('@PuMuKIT2CMARLive/Player/chat.html.twig', {
         'chatTheme': 'dark',
         'moderators': ['admin@example.com']
     }) }}
     

   • Listen to chat events via JavaScript (bundled with the player):

     document.addEventListener('pumukitChatMessage', (e) => {
         console.log('New message:', e.detail);
     });
     

3. Customization

   • Override default templates by copying files from: vendor/campusdomar/pmk2-cmar-live-bundle/Resources/views/ to templates/PuMuKIT2CMARLive/.
   • Extend player configuration via YAML:

     # config/packages/pumukit2_cmar_live.yaml
     pumukit2_cmar_live:
         player:
             default_chat_position: 'bottom-right'
             allowed_chat_commands: ['!kick', '!ban']
     

4. API-Driven Workflows

   • Use the bundle’s REST API endpoints (if enabled) for programmatic control:

     # Example: Start a stream via HTTP
     POST /api/live/start
     Headers: Authorization: Bearer {token}
     Body: { "streamKey": "your_key" }
     

Gotchas and Tips

Common Pitfalls

1. Symfony vs. Laravel Integration

   • Issue: Laravel’s service container may not auto-register Symfony bundles. Fix: Manually bind services in AppServiceProvider:

     public function register() {
         $this->app->register(\Symfony\Bundle\FrameworkBundle\FrameworkBundle::class);
         $this->app->boot();
     }
     

   • Tip: Use symfony/var-dumper for debugging:

     use Symfony\Component\VarDumper\Cloner\VarCloner;
     $cloner = new VarCloner();
     $cloner->dump($this->container->get('pumukit.live.manager'));
     

2. Chat Permissions

   • Issue: Chat moderation rules may not persist across sessions. Fix: Store moderators in a database table (e.g., chat_moderators) and fetch them dynamically:

     {% set moderators = app.service('moderator.repository').findByStream(streamKey) %}
     

3. Stream Key Validation

   • Issue: Invalid stream keys may silently fail. Fix: Validate keys in a form request or middleware:

     public function rules() {
         return ['streamKey' => 'required|regex:/^[a-z0-9_-]{8,}$/'];
     }
     

4. Template Overrides

   • Issue: Overrides may not take effect due to caching. Fix: Clear Symfony’s cache:

     php bin/console cache:clear
     

     Or Laravel’s:

     php artisan cache:clear
     php artisan view:clear
     

Debugging Tips

• Enable Debug Mode: Set APP_DEBUG=true in .env and check Symfony’s profiler at /_profiler.
• Log Chat Events: Configure Monolog in config/packages/monolog.yaml:

  handlers:
      chat:
          type: stream
          path: "%kernel.logs_dir%/chat.log"
          level: debug
          channels: ["pumukit_chat"]
  

• Network Issues: Use browser dev tools to inspect WebSocket connections (chat relies on ws:// endpoints).

Extension Points

1. Custom Chat Commands Extend the chat system by creating a command handler:

   namespace App\Chat;
   
   class CustomCommandHandler implements \Pumukit\LiveBundle\Chat\CommandHandlerInterface {
       public function handle(string $command, string $sender): ?string {
           if (str_starts_with($command, '!custom')) {
               return "Custom response for $sender";
           }
           return null;
       }
   }
   

   Register it in services.yaml:

   services:
       App\Chat\CustomCommandHandler:
           tags: ['pumukit.chat.command_handler']
   

2. Webhook Integration Trigger external actions (e.g., Slack alerts) when chat events occur:

   // config/packages/pumukit2_cmar_live.yaml
   pumukit2_cmar_live:
       chat:
           webhooks:
               - url: 'https://hooks.slack.com/...'
                 events: ['message', 'moderation']
   

3. Laravel Notifications Convert chat messages to Laravel notifications:

   use Pumukit\LiveBundle\Event\ChatMessageEvent;
   
   public function onChatMessage(ChatMessageEvent $event) {
       Notification::route('mail', $event->getSender())
           ->notify(new ChatMessageNotification($event));
   }
   

   Register the listener in EventServiceProvider.