Renderer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require windwalker/renderer ^4.0
   

2. Basic Usage:

   use Windwalker\Renderer\Renderer;
   
   $renderer = new Renderer();
   $output = $renderer->render('Hello, {{ name }}!', ['name' => 'World']);
   echo $output; // Outputs: Hello, World!
   

3. First Use Case:

   • Replace hardcoded HTML strings in Blade templates with dynamic rendering logic.
   • Example: Render a reusable component (e.g., a card) with dynamic data.

Where to Look First

• Documentation for API references and examples.
• src/ directory for core classes like Renderer, Engine, and Template.
• tests/ for practical usage examples and edge cases.

Implementation Patterns

Core Workflow

1. Template Registration:

   $renderer = new Renderer();
   $renderer->registerEngine('blade', new \Windwalker\Renderer\Engine\BladeEngine());
   $renderer->registerEngine('twig', new \Windwalker\Renderer\Engine\TwigEngine());
   

   • Supports Blade, Twig, Plain PHP, and custom engines.

2. Dynamic Rendering:

   $output = $renderer->render('engine:blade', 'path/to/template.blade.php', ['data' => 'value']);
   

   • Use engine:engineName prefix to specify the engine.

3. Component-Based Rendering:

   $renderer->addComponent('card', function ($data) {
       return $this->render('components/card.blade.php', $data);
   });
   $output = $renderer->component('card', ['title' => 'Example']);
   

Integration Tips

• Laravel Integration: Bind the renderer to the service container in AppServiceProvider:

  $app->singleton(Renderer::class, function ($app) {
      $renderer = new Renderer();
      $renderer->registerEngine('blade', new \Windwalker\Renderer\Engine\BladeEngine($app['blade.compiler']));
      return $renderer;
  });
  

  Inject via constructor:

  public function __construct(private Renderer $renderer) {}
  

• Reusable Layouts: Use render() with nested templates:

  $renderer->render('layouts/app.blade.php', [
      'content' => $renderer->render('partials/header.blade.php', $headerData)
  ]);
  

• Caching: Enable template caching for performance:

  $renderer->setCache(new \Windwalker\Renderer\Cache\FileCache(__DIR__.'/cache'));
  

Gotchas and Tips

Pitfalls

1. Engine Initialization:

   • Forgetting to register engines (e.g., Blade/Twig) will throw EngineNotFoundException.
   • Fix: Always register engines before rendering.

2. Template Paths:

   • Relative paths are resolved from the current working directory, not the project root.
   • Fix: Use absolute paths or configure a base path:

     $renderer->setBasePath(__DIR__.'/resources/views');
     

3. Variable Escaping:

   • Plain PHP engine does not auto-escape variables (unlike Blade/Twig).
   • Fix: Use htmlspecialchars() or switch to Blade/Twig for built-in escaping.

4. Component Scope:

   • Components are not automatically shared across requests in Laravel.
   • Fix: Register components in a service provider or use dependency injection.

Debugging Tips

• Enable Debug Mode:

  $renderer->setDebug(true); // Logs template paths and errors
  

• Check Engine Errors: Wrap rendering in a try-catch to handle engine-specific exceptions:

  try {
      $output = $renderer->render('engine:blade', 'template.blade.php', $data);
  } catch (\Windwalker\Renderer\Exception\EngineException $e) {
      Log::error($e->getMessage());
  }
  

Extension Points

1. Custom Engines: Implement \Windwalker\Renderer\Engine\EngineInterface:

   class MyEngine implements EngineInterface {
       public function render(string $template, array $data): string {
           // Custom logic (e.g., parse Mustache templates)
       }
   }
   

2. Template Preprocessing: Use Renderer::addFilter() to modify templates before rendering:

   $renderer->addFilter('minify', function ($template) {
       return preg_replace('/\s+/', ' ', $template);
   });
   $renderer->render('template.blade.php', [], ['minify']);
   

3. Event Hooks: Listen to Renderer.Rendering and Renderer.Rendered events for logging/auditing:

   $renderer->on('Rendering', function ($event) {
       Log::debug('Rendering template:', [$event->getTemplate(), $event->getData()]);
   });
   

Performance Quirks

• Template Compilation: Blade/Twig engines compile templates to PHP on first render. Cache compiled files for repeated use.
• Memory Usage: Avoid passing large arrays to templates. Use lazy-loading or chunking for complex data.