Mthaml Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer in your Laravel project (though note this is a Symfony bundle, so integration requires a bridge or custom setup):

   composer require dnl/mthaml-bundle
   

   For Laravel, you’ll need to manually register the bundle in config/app.php under extra.bundles (if using Symfony components) or create a custom wrapper.

2. Basic Usage Create a .haml file (e.g., resources/views/example.haml):

   %html
     %head
       %title My Page
     %body
       %h1 Hello, HAML!
       = "Dynamic content: " + $variable
   

   Render it in a Laravel controller:

   use DNL\MtHamlBundle\Engine\HamlEngine;
   
   public function show()
   {
       $haml = new HamlEngine();
       $content = $haml->render(file_get_contents(resource_path('views/example.haml')), [
           'variable' => 'World'
       ]);
       return response($content);
   }
   

3. First Use Case Replace a single Blade template with HAML for a component (e.g., a modal or form) to reduce verbosity. Compare:

   • Blade: <div class="modal">...</div>
   • HAML: .modal

Implementation Patterns

Workflow Integration

1. Hybrid Templating Use HAML for complex UI components (e.g., dashboards) while keeping Blade for dynamic logic-heavy views. Example:

   - $user = Auth::user()
   %nav
     %ul
       - if ($user->isAdmin())
         %li= link_to_route('admin.dashboard', 'Admin')
       - else
         %li= link_to_route('user.dashboard', 'User')
   

2. Partial Reuse Extract reusable HAML snippets into partials (e.g., _card.haml):

   %div.card{:class => "bg-#{$color}"}
     %h3= $title
     = $content
   

   Include them in other views:

   = render_partial('card', title: "Feature", content: "Lorem...", color: "blue")
   

3. Asset Pipeline Compile HAML alongside Laravel Mix:

   // webpack.mix.js
   mix.haml('resources/views', 'public/views');
   

   Note: Requires custom Webpack loader setup (see Gotchas).

4. Form Handling Generate forms with HAML’s concise syntax:

   = form_open(route('posts.store'))
     = text_field('post', 'title', placeholder: 'Title')
     = text_area('post', 'body')
     = submit_tag('Publish')
   

Laravel-Specific Tips

• Service Provider Bind the HAML engine to Laravel’s view factory in AppServiceProvider:

  public function register()
  {
      $this->app->extend('view', function ($view) {
          $view->engineResolver()->register('haml', function () {
              return new HamlEngine();
          });
      });
  }
  

  Now use .haml files directly in view() calls:

  return view('example.haml', ['variable' => 'World']);
  

• Blade-HAML Interop Embed Blade directives in HAML for dynamic logic:

  - if (old('status') === 'draft')
    .alert= __("Post is a draft")
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency

   • The bundle is Symfony-first. Laravel integration requires:
     • Manual service registration (no auto-discovery).
     • Potential conflicts with Symfony’s ContainerInterface.
   • Workaround: Use a wrapper like symfony/var-dumper for debugging.

2. Caching Quirks

   • HAML templates are not cached by default in Laravel’s view system. Add this to AppServiceProvider:

     $view->addExtension('haml', new HamlExtension());
     

   • Clear config cache after changes:

     php artisan config:clear
     

3. Asset Paths

   • HAML’s asset() helper won’t resolve Laravel’s mix-manifest.json. Use:

     = asset('css/app.css') # Fails
     = mix('css/app.css')  # Use Laravel Mix helper
     

4. Indentation Sensitivity

   • HAML is whitespace-sensitive. Mixing tabs/spaces or trailing newlines can break rendering.
   • Fix: Use a linter like haml-lint in your CI.

5. Dynamic Content

   • Avoid complex PHP logic in HAML. Offload to controllers or Blade:

     -// BAD: Heavy logic in HAML
     - $filtered = collect($items)->where(...)->sortBy(...)
     
     -// GOOD: Pre-process in controller
     

Debugging

• Errors: HAML throws cryptic errors for syntax issues. Enable Symfony’s profiler:

  $this->app->register(Symfony\Bundle\DebugBundle\DebugBundle::class);
  

• Output: Use {{ dump($variable) }} in HAML to inspect data (requires Blade-HAML interop).

Extension Points

1. Custom Filters Extend HAML’s syntax with custom filters:

   HamlEngine::addFilter('uppercase', function ($str) {
       return strtoupper($str);
   });
   

   Usage:

   = "hello".uppercase
   

2. Layouts Use haml-layout gem (not bundled) for shared layouts:

   -# resources/views/layouts/application.haml
   !! 5
   %html
     %head= yield_head
     %body= yield_body
   

3. Testing Mock the HAML engine in PHPUnit:

   $this->app->instance(HamlEngine::class, Mockery::mock(HamlEngine::class));