Mthaml Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alexvasilyev/mthaml-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+):

   return [
       // ...
       Alexvasilyev\MtHamlBundle\AlexvasilyevMtHamlBundle::class => ['all' => true],
   ];
   

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

   %h1 Hello, {name}!
   %p Welcome to HAML templating.
   

   Render it in a controller:

   use Alexvasilyev\MtHamlBundle\Templating\Engine\MtHamlEngine;
   
   public function index(MtHamlEngine $hamlEngine)
   {
       return $hamlEngine->render('hello.haml', ['name' => 'World']);
   }
   

3. First Use Case Replace Twig templates for views requiring cleaner syntax (e.g., forms, layouts). Example:

   = form_start('path', 'post')
   %label(for="email") Email
   %input#email{:type => "email", :name => "email"}
   = form_end()
   

Implementation Patterns

Workflows

1. View Rendering

   • Use dependency injection for MtHamlEngine in controllers/services.
   • Store templates in resources/views/ (e.g., user/show.haml).
   • Pass variables via associative arrays:

     $hamlEngine->render('user/show.haml', ['user' => $userData]);
     

2. Layouts and Inheritance

   • Use haml_include for partials:

     = haml_include('partials/header.haml', {title: 'Page Title'})
     

   • Nest layouts with haml_layout (if supported by the engine).

3. Asset Integration

   • Combine with Symfony’s Asset component for static files:

     %link{:rel => "stylesheet", :href => asset('css/style.css')}
     

4. Form Handling

   • Generate forms with HAML’s concise syntax:

     = form_row('text', 'username', {label: 'Username', value: $user->username})
     

Integration Tips

• Symfony Forms: Use form_row() helper for seamless integration with Symfony’s FormBuilder.
• Twig Compatibility: Replace Twig extensions with HAML equivalents (e.g., path() → url_for()).
• Testing: Mock MtHamlEngine in PHPUnit:

  $this->mockBuilder()
       ->disableOriginalConstructor()
       ->getMock()
       ->method('render')
       ->willReturn('<h1>Test</h1>');
  

Gotchas and Tips

Pitfalls

1. Deprecation Warnings

   • The bundle is unmaintained (last release: 2017). Test thoroughly in your environment.
   • PHP 7.0+ may trigger deprecation notices (e.g., foreach syntax).

2. Namespace Conflicts

   • Avoid naming HAML files after existing Twig templates (e.g., index.html.haml vs. index.html.twig).

3. Limited Documentation

   • Refer to original MtHaml for advanced features (e.g., filters, custom tags).

Debugging

• Syntax Errors: HAML is whitespace-sensitive. Use an editor with HAML support (e.g., VSCode with HAML plugin).
• Missing Variables: Check for typos in variable names (HAML throws cryptic errors for undefined vars).
• Caching: Clear Symfony cache (php bin/console cache:clear) if templates fail to update.

Extension Points

1. Custom Filters Add filters via services.yaml:

   alexvasilyev_mthaml.twig.filter.my_filter:
       class: App\Twig\MyFilterExtension
       tags:
           - { name: 'alexvasilyev_mthaml.filter' }
   

2. Override Engine Extend MtHamlEngine for custom logic (e.g., auto-escaping):

   class CustomHamlEngine extends MtHamlEngine
   {
       protected function escape($str) { /* custom logic */ }
   }
   

3. Asset Pipeline Integrate with Webpack Encore for preprocessing:

   %script{:src => mix('js/app.js')}
   

Performance

• Precompile Templates: Use Symfony’s assetic to precompile HAML to HTML for static sites.
• Avoid Overuse: HAML’s indentation can bloat files. Use sparingly for complex layouts.