Pumukit Paella Player Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Prerequisites Check:

   • Ensure your project uses PuMuKIT v5.0+ and Symfony 5.x/6.x with PHP 8.2+.
   • Verify compatibility with your existing bundles.php, routing.yaml, and pumukit_player.yaml configurations.

2. Installation:

   composer require teltek/pumukit-paella-player-bundle
   

3. Configuration:

   • Remove the default player bundle from config/bundles.php:

     // Remove this line:
     Pumukit\PlayerBundle\PumukitPlayerBundle::class => ['all' => true],
     

   • Add the Paella Player bundle:

     Pumukit\PaellaPlayerBundle\PumukitPaellaPlayerBundle::class => ['all' => true],
     

   • Update config/routes/annotations.yaml to point to the new bundle:

     pumukit_player:
       resource: "@PumukitPaellaPlayerBundle/Resources/config/routing.yml"
       prefix:   /
     

   • Remove config/packages/pumukit_player.yaml.

4. Clear Caches and Reinstall Assets:

   php bin/console cache:clear
   php bin/console cache:clear --env=prod
   php bin/console assets:install
   

5. First Test:

   • Access a video page in your PuMuKIT portal to verify the Paella Player loads and functions correctly.
   • Check browser console for errors (e.g., missing Paella Player assets or JavaScript conflicts).

Implementation Patterns

Common Workflows

1. Basic Integration:

   • Follow the minimal steps above to replace the default player globally across the PuMuKIT portal.
   • Ideal for projects where the default player’s UX or features are insufficient, and Paella Player’s capabilities (e.g., adaptive bitrate, custom skins) are required.

2. Customizing Paella Player:

   • Theming: Paella Player supports custom skins. Override its CSS/JS by extending its asset pipeline in Symfony. Example:

     # config/packages/paella_player.yaml
     paella_player:
         theme:
             path: '%kernel.project_dir%/public/paella-themes/custom-theme'
             name: 'custom-theme'
     

   • Plugins: Enable/disable Paella Player plugins (e.g., subtitles, analytics) via configuration or by extending its JavaScript initialization:

     // In your custom JS file (e.g., app.js)
     PaellaPlayer.prototype.initPlugins = function() {
         this.plugins = ['subtitles', 'analytics', 'ads'];
         // Custom plugin logic
     };
     

3. Hybrid Approach (Advanced):

   • If you need the Paella Player for specific routes only, create a custom controller that renders the Paella Player template instead of relying on the bundle’s routing. Example:

     // src/Controller/CustomPlayerController.php
     namespace App\Controller;
     
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Routing\Annotation\Route;
     
     class CustomPlayerController extends AbstractController {
         #[Route('/custom-player/{id}', name: 'custom_player')]
         public function show($id) {
             return $this->render('@PumukitPaellaPlayer/player.html.twig', [
                 'videoId' => $id,
             ]);
         }
     }
     

4. Asset Management:

   • Paella Player relies on Symfony’s asset pipeline. For CDN or custom asset handling:
     • Configure assets:install to symlink Paella Player assets to your public/ directory.
     • Use Symfony’s asset() function in Twig templates to reference Paella Player JS/CSS:

       {{ asset('bundles/pumukitpaellaplayer/js/paella-player.js') }}
       

5. Debugging Workflow:

   • Enable Symfony’s profiler to inspect Paella Player-related routes and templates.
   • Check browser console for errors (e.g., 404s on Paella Player assets or JS conflicts).
   • Use Paella Player’s built-in debug mode (if available) to validate initialization:

     // Add to your custom JS
     PaellaPlayer.prototype.debug = true;
     

Gotchas and Tips

Pitfalls

1. Bundle Conflict:

   • Issue: Forgetting to remove the default PumukitPlayerBundle or its routing/configuration can cause conflicts, leading to broken player functionality or duplicate routes.
   • Fix: Double-check config/bundles.php, routing.yaml, and pumukit_player.yaml for leftover traces of the default player.

2. Asset Loading Failures:

   • Issue: Paella Player assets (JS/CSS) may fail to load if Symfony’s asset pipeline is misconfigured or assets aren’t installed.
   • Fix:
     • Run php bin/console assets:install after installation.
     • Verify assets are symlinked in public/bundles/pumukitpaellaplayer/.
     • Check for typos in asset paths in Twig templates.

3. JavaScript Conflicts:

   • Issue: Paella Player may conflict with existing JavaScript libraries (e.g., jQuery, other video players) if they manipulate the same DOM elements or use overlapping event handlers.
   • Fix:
     • Load Paella Player’s JS after other libraries.
     • Use data-paella-player attributes to scope its initialization to specific elements.
     • Wrap Paella Player initialization in a $(document).ready() or DOMContentLoaded event.

4. Caching Issues:

   • Issue: After replacing the player, cached routes or templates may still reference the old player, causing mixed content or broken functionality.
   • Fix:
     • Clear all caches (cache:clear --env=prod and cache:pool:clear).
     • Invalidate browser cache or use hard refresh (Ctrl + F5).
     • Check Symfony’s profiler for cached responses.

5. Paella Player Version Mismatch:

   • Issue: The bundle uses Paella Player 7, but your project may need a different version (e.g., for specific features or bug fixes).
   • Fix:
     • Fork the bundle and update the Paella Player version in composer.json.
     • Monitor Paella Player’s releases for compatibility.

6. Missing Configuration:

   • Issue: Paella Player may require additional configuration (e.g., API endpoints, plugins) that isn’t documented in the bundle’s README.
   • Fix:
     • Refer to the Paella Player documentation for advanced setup.
     • Check PumukitPaellaPlayerBundle’s Resources/config/ for default configurations you may need to override.

7. DRM or Advanced Features:

   • Issue: Paella Player 7 may lack support for DRM (e.g., Widevine) or advanced analytics out of the box.
   • Fix:
     • Verify Paella Player’s feature list.
     • Use Paella Player’s plugin system to integrate third-party solutions (e.g., Paella DRM plugins).

Debugging Tips

1. Enable Symfony Debug Mode:

   • Set APP_DEBUG=1 in .env to enable the profiler and detailed error logs.
   • Access /_profiler/ to inspect routes, templates, and asset loading.

2. Check Paella Player Console Logs:

   • Open browser dev tools (F12) and navigate to the Console tab to catch JS errors (e.g., PaellaPlayer is not defined).
   • Look for warnings about missing dependencies (e.g., HLS.js, Dash.js).

3. Validate Twig Templates:

   • Ensure the Paella Player template (@PumukitPaellaPlayer/player.html.twig) is being rendered correctly. Override it if needed:

     mkdir -p templates/PumukitPaellaPlayer
     cp vendor/pumukit/paella-player-bundle/Resources/views/player.html.twig templates/PumukitPaellaPlayer/
     

4. Test with Minimal Configuration:

   • Start with a single video and default Paella Player settings to isolate issues.
   • Gradually add customizations (themes, plugins) and test incrementally.

5. Network Tab Inspection:

   • Use the browser’s Network tab to verify Paella Player assets (JS/CSS) are loading without 404s.
   • Check for mixed content warnings (e.g., HTTP vs. HTTPS assets).

Extension Points

1. Custom Player Initialization:
   • Override Paella Player’s initialization by extending its JavaScript prototype:

     // app.js
     PaellaPlayer.prototype.customInit = function() {
         this.options