Mustache Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bobthecow/mustache-bundle
   

   Verify the package appears in composer.json under require.

2. Register the Bundle: Add to config/bundles.php (Symfony 4+):

   Bobthecow\Bundle\MustacheBundle\BobthecowMustacheBundle::class => ['all' => true],
   

   For Symfony <4, add to AppKernel.php:

   new Bobthecow\Bundle\MustacheBundle\BobthecowMustacheBundle(),
   

3. Configure Templating Engine: Update config/packages/framework.yaml (Symfony 4+):

   framework:
       templating:
           engines: ['twig', 'mustache']
   

   For Symfony <4, add to config.yml:

   framework:
       templating:
           engines: ['twig', 'mustache']
   

4. First Template: Create a Mustache file at templates/Hello/index.html.mustache:

   <h1>Hello, {{ name }}!</h1>
   

   Render in a controller:

   return $this->render('Hello/index.html.mustache', ['name' => 'World']);
   

Implementation Patterns

Core Workflows

1. Template Rendering:

   • Use render() method in controllers:

     return $this->render('Bundle:Path:template.mustache', $data);
     

   • Supports annotations (Symfony <4):

     /**
      * @Template("Bundle:Path:template.mustache")
      */
     public function showAction() { return ['key' => 'value']; }
     

2. Partial Templates: Include reusable components:

   {{> partials/header.mustache }}
   

   Store partials in templates/partials/.

3. Dynamic Logic: Use Mustache’s built-in helpers (e.g., {{#if}}, {{^else}}):

   {{#items}}
     <li>{{.}}</li>
   {{/items}}
   

4. Asset Integration: Combine with Symfony’s asset system:

   <img src="{{ asset('images/logo.png') }}">
   

   Pass asset() helper via controller:

   return $this->render('template.mustache', [
       'asset' => $this->get('assets.packages')->getUrlGenerator()
   ]);
   

5. Configuration Overrides: Customize Mustache settings in config/packages/bobthecow_mustache.yaml:

   bobthecow_mustache:
       cache: true
       partials_dir: '%kernel.project_dir%/templates/partials'
   

Gotchas and Tips

Common Pitfalls

1. Cache Invalidation:

   • Mustache templates are cached by default (Symfony 4+). Clear cache after changes:

     php bin/console cache:clear
     

   • Disable caching in config/packages/bobthecow_mustache.yaml:

     bobthecow_mustache:
         cache: false
     

2. Template Paths:

   • Mustache files must use .mustache extension (e.g., template.html.mustache).
   • Paths are case-sensitive. Use Bundle:Controller:template.mustache format for consistency.

3. Partial Loading:

   • Partials must be in a directory named partials (default) or configured via partials_dir.
   • Relative paths in {{> partial }} are resolved from the template’s directory.

4. Symfony 4+ Twist:

   • The bundle may not fully support Symfony Flex auto-configuration. Manually register the bundle in config/bundles.php.

5. Deprecated Features:

   • The bundle is abandoned (last release: 2014). Avoid for new projects; consider alternatives like league/mustache or symfony/mustache.

Debugging Tips

1. Template Errors: Mustache throws generic errors. Enable Symfony’s profiler to inspect rendered output:

   if ($this->get('kernel')->isDebug()) {
       return new Response($this->renderView('template.mustache', $data));
   }
   

2. Variable Dumping: Use {{{dump}}} in templates to debug variables (requires custom helper):

   $mustache->addHelper('dump', function($vars) {
       return print_r($vars, true);
   });
   

3. Configuration Validation: Validate config/packages/bobthecow_mustache.yaml exists and is correctly formatted. Defaults:

   bobthecow_mustache:
       cache: true
       partials_dir: '%kernel.project_dir%/templates/partials'
   

Extension Points

1. Custom Helpers: Register Mustache helpers in a compiler pass or service:

   $mustache->addHelper('formatDate', function($date) {
       return (new \DateTime($date))->format('Y-m-d');
   });
   

2. Template Events: Listen to mustache.render events (Symfony <4) to modify output:

   $dispatcher->addListener('mustache.render', function($event) {
       $event->setTemplate($event->getTemplate()->replace('{{title}}', 'Custom Title'));
   });
   

3. Override Default Loader: Replace the template loader for custom paths:

   bobthecow_mustache:
       loader:
           class: App\Mustache\CustomLoader
           arguments: ['%kernel.project_dir%/custom_templates']