Mthaml Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require alexvasilyev/mthaml
   

   Add the service provider to config/app.php under providers:

   Alexvasilyev\Mthaml\MthamlServiceProvider::class,
   

2. Basic Usage:

   • Create a .haml.php file (e.g., resources/views/layouts/haml.php).
   • Write HAML syntax:

     !! 5
     %html
       %head
         %title My App
       %body
         = $message
     

   • Render it in a Laravel controller:

     use Alexvasilyev\Mthaml\Mthaml;
     
     public function index(Mthaml $haml)
     {
         return $haml->render('layouts.haml', ['message' => 'Hello, World!']);
     }
     

3. First Use Case:

   • Convert an existing Blade template to HAML for cleaner markup.
   • Useful for rapid prototyping or teams preferring HAML’s conciseness.

Implementation Patterns

Workflows

1. Hybrid Blade + HAML:

   • Use HAML for layout files (e.g., layouts.haml) and Blade for dynamic components.
   • Example:

     // In a controller
     return view('layouts.haml', [
         'content' => view('components.card', ['data' => $data])
     ]);
     

2. Partial Reusability:

   • Store reusable HAML snippets in resources/views/partials/_*.haml.
   • Render them via:

     $haml->renderPartial('partials._header', ['title' => 'Home']);
     

3. Dynamic Compilation:

   • Cache compiled HAML templates for performance:

     $haml->setCachePath(storage_path('framework/views'));
     

Integration Tips

• Laravel Mix: Combine HAML compilation with asset pipelines by extending mix.js() or mix.webpack() to trigger HAML preprocessing.

• Form Handling: Use HAML for form layouts while leveraging Laravel’s Form facade for inputs:

  = Form::open()
  %div.field
    = Form::label('email')
    = Form::email('email')
  = Form::close()
  

• API Responses: Return HAML-rendered HTML for API-driven frontend frameworks (e.g., React/Vue):

  return response($haml->render('api.response.haml', $data), 200);
  

Gotchas and Tips

Pitfalls

1. Deprecated Syntax:

   • The package is outdated (last release: 2017). Avoid modern PHP features (e.g., typed properties) in templates.
   • Workaround: Use a wrapper class or abstract the HAML layer.

2. No Blade Directives:

   • HAML lacks Blade’s @stack, @yield, or @include directives. Use partials or manual concatenation:

     $content = $haml->render('partials._sidebar');
     echo $haml->render('layout.haml', ['sidebar' => $content]);
     

3. Escaping Issues:

   • Unescaped variables may cause XSS. Explicitly escape with |raw or use Laravel’s @escape equivalent:

     = e($user->input)  // Manual escaping (if supported)
     

4. Namespace Conflicts:

   • HAML files are resolved via Laravel’s view system. Ensure filenames don’t clash with Blade views (e.g., home.haml vs. home.blade.php).

Debugging

• Compilation Errors:

  • Enable HAML’s verbose mode (if available) or check compiled output in storage/framework/views.
  • Tip: Use dd($haml->render('view.haml', $data)) to inspect raw output.

• Caching Quirks:

  • Clear cached views after HAML template changes:

    php artisan view:clear
    

Extension Points

1. Custom Filters:

   • Extend the package by adding filters (e.g., |upcase):

     // In a service provider
     $haml->addFilter('upcase', function($value) {
         return strtoupper($value);
     });
     

     Usage in HAML:

     = $message | upcase
     

2. Multi-Language Support:

   • Override the Mthaml class to support additional languages (e.g., Twig) by extending the base parser.

3. Preprocessing:

   • Hook into Laravel’s View::composer() to preprocess HAML before rendering:

     View::composer('*.haml', function($view) {
         $view->with('preprocessed_data', $this->transform($view->data));
     });