Pumukit Template Bundle Laravel Package

Getting Started

This bundle is effectively a companion module for WebTVBundle inside the PuMuKIT platform. Treat it as an extension of that bundle rather than a standalone library — it is not useful outside a PuMuKIT install.

Minimal steps:

1. Confirm your stack first. Open the package's composer.json and check the symfony/* and pumukit/* constraints. PuMuKIT historically runs on Symfony 2.8/3.x with MongoDB ODM, so this bundle will not drop into a modern Laravel or Symfony 6 app without porting.
2. Install via Composer inside the PuMuKIT monorepo:

   composer require teltek/pumukit-template-bundle
   

3. Register the bundle in the kernel (app/AppKernel.php for legacy Symfony, or config/bundles.php if you've upgraded). Add it after PumukitWebTVBundle so template overrides win.
4. Import routing in app/config/routing.yml (or config/routes.yaml):

   pumukit_template:
       resource: "@PumukitTemplateBundle/Resources/config/routing.yml"
       prefix: /
   

5. Clear caches (php app/console cache:clear) and confirm the bundle appears under the admin/WebTV menu.

Where to look first, in order:

• README.md — usually a paragraph or two of Spanish/English install notes.
• Resources/config/ — services, routing, and any DI parameters you can override.
• Resources/views/ — the Twig templates this bundle injects into WebTVBundle; this is where the "editor" surface actually lives.
• Controller/ — the endpoints backing the editor UI.
• Document/ (if present) — the MongoDB ODM document that persists a template.

First use case: log in as an editor, open the WebTV page in the PuMuKIT admin, and use the template editor to select/customize which blocks (header, playlist, categories, live events) render on the public web TV page. Your payoff is overriding the default WebTV layout without forking WebTVBundle.

Implementation Patterns

1. Twig-override workflow (the primary pattern). This bundle exists to let you change WebTVBundle markup without touching the parent bundle. The pattern is to place your custom Twig under app/Resources/PumukitWebTVBundle/views/ (or the equivalent override path) so the loader resolves yours before the bundle's. Keep the bundle's original filenames — it renders by convention, not by explicit path.

2. Template selection at render time. Typical integration: the WebTV controller resolves a template identifier (from config, a request parameter, or a MongoDB document) and passes it into the view. In your own controller action, mirror that:

return $this->render('PumukitWebTVBundle:Default:index.html.twig', [
    'template' => $templateName,
    // ...
]);

Then in Twig, branch on template to include the right partial. This keeps the editor's choices data-driven rather than hardcoded.

3. Persisting templates. If the bundle ships an ODM document, treat it as the source of truth. Save through the DocumentManager, not raw arrays, so PuMuKIT's existing serialization and caching stay consistent. When extending, add fields to the document via your own bundle's document rather than editing the vendor copy.

4. Composing with WebTVBundle blocks. PuMuKIT pages are assembled from named blocks. The reliable pattern is to keep your template as a thin wrapper of {% include %} calls to WebTVBundle partials, then let the editor toggle which includes are active. Avoid copying large chunks of parent markup — you'll inherit maintenance pain on every WebTVBundle upgrade.

5. Service and DI customization. Override the bundle's services in your app's services.yml by alias rather than editing vendor files. This is the intended extension point for changing the controller or template resolver.

6. Config-driven defaults. Use the bundle's DependencyInjection/Configuration.php (if present) to expose defaults in config.yml, e.g. a default template id. This lets different environments (staging vs. prod web TV) behave differently without code changes.

7. CI / deployment workflow. Because the bundle ships Twig and config, include a cache-warm step in deploy (cache:warmup), and add a smoke test that hits the WebTV route to catch broken template references before they reach editors.

Gotchas and Tips

• This is a low-maintenance, low-adoption package (2 stars, 0 dependents). Do not expect active bug fixes. Pin the exact version in composer.json and vendor the bundle or fork it if you rely on it in production. Read the source before upgrading — there is no changelog worth trusting.
• Symfony version lock-in. PuMuKIT bundles are tied to legacy Symfony (2.8/3.x). Registering on Symfony 4+ requires the bundles.php change and a check for deprecated APIs (getContainer, KernelInterface constants, container:compile-era service definitions).
• MongoDB ODM dependency. If the bundle persists documents, you need the doctrine/mongodb-odm-bundle configured. A missing document mapping manifests as a "class not found" or an empty editor, not an obvious error — check app/console doctrine:mongodb:mapping:info.
• Twig cache hides edits. After changing override templates, run cache:clear; otherwise you'll debug a file that isn't the one being rendered. Use twig:debug or the profiler's template panel to confirm the resolved path.
• No documentation for the editor's data shape. Inspect the document/entity and the controller that saves it to learn the expected payload. Save through the editor once and dump the persisted record to reverse-engineer it.
• Routing prefix collisions. If WebTVBundle already mounts similar routes, a conflicting prefix silently shadows one of them. Use app/console router:debug | grep template to verify what actually loaded.
• Bundle ordering matters. Register this bundle after PumukitWebTVBundle in the kernel; otherwise its Twig overrides lose to the parent's defaults.
• Debugging the render path. When the wrong template appears: (1) confirm the bundle is registered, (2) confirm the route resolves to this bundle's controller, (3) inspect the Twig loader's resolved template via the profiler, (4) grep the override path for a stale copy of the file.
• Extension point of last resort. Because the package is small and quiet, the cleanest long-term move is often to copy the editor controller + Twig into your own bundle, keeping only the data model from this one. That gives you a supported fork with a clear upgrade story.
• Security. The editor mutates public-facing layout; ensure the bundle's routes sit behind PuMuKIT's role checks (ROLE_ADMIN/ROLE_EDITOR) if they aren't already, and never expose the template save endpoint unauthenticated.