Php Liquid Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require codemade-xyz/php-liquid-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       CodeMade\LiquidBundle\LiquidBundle::class => ['all' => true],
   ];
   

2. First Use Case Create a Liquid template at templates/liquid/example.liquid:

   {% for item in items %}
       <p>{{ item.name }} - {{ item.price | price }}</p>
   {% endfor %}
   

   Render it in a Symfony controller:

   use CodeMade\LiquidBundle\Liquid\Engine;
   
   public function index(Engine $engine)
   {
       $template = $engine->getTemplate('example.liquid');
       $output = $template->render([
           'items' => [
               ['name' => 'Product 1', 'price' => 19.99],
               ['name' => 'Product 2', 'price' => 29.99],
           ],
       ]);
       return new Response($output);
   }
   

3. Where to Look First

   • Documentation: Check the GitHub README for basic syntax and filters.
   • Filters: Explore built-in filters like price, prettyprint, and paragraph in src/CodeMade/LiquidBundle/Filter/.
   • Configuration: Review config/packages/liquid.yaml for cache and path settings.

Implementation Patterns

Usage Patterns

1. Dynamic Template Rendering Use Liquid for dynamic content generation (e.g., emails, notifications, or CMS-driven pages):

   $template = $engine->getTemplate('emails/welcome.liquid');
   $template->render(['user' => $user]);
   

2. Reusable Components Create modular Liquid templates (e.g., _header.liquid, _footer.liquid) and include them:

   {% render 'partials/header' %}
   <main>{{ content }}</main>
   {% render 'partials/footer' %}
   

3. Custom Filters Extend Liquid with custom filters (e.g., for formatting dates or truncating text):

   # config/packages/liquid.yaml
   liquid:
       filters:
           - App\Filter\CustomFilter
   

   // src/Filter/CustomFilter.php
   namespace App\Filter;
   use CodeMade\LiquidBundle\Filter\FilterInterface;
   
   class CustomFilter implements FilterInterface {
       public function filter($input) {
           return strtoupper($input);
       }
   }
   

4. Caching Leverage Symfony’s cache for performance:

   liquid:
       cache: '%kernel.cache_dir%/liquid'
   

Workflows

1. Symfony Twig Integration Use Liquid alongside Twig for hybrid templating (e.g., Liquid for dynamic content, Twig for layouts):

   {# templates/base.html.twig #}
   <div id="dynamic-content">
       {{ include('liquid/_dynamic.liquid', {'data': data})|raw }}
   </div>
   

2. API-Driven Templates Fetch Liquid templates dynamically from a database or API:

   $templateContent = $db->fetchTemplate($templateId);
   $engine->getTemplateFromString($templateContent)->render($data);
   

3. Testing Mock the Engine service in PHPUnit:

   $engine = $this->createMock(Engine::class);
   $engine->method('getTemplate')->willReturn($templateMock);
   

Integration Tips

• Frontend Frameworks: Use Liquid for server-side rendering (SSR) with Vue/React by passing rendered HTML to the frontend.
• CMS Integration: Pair with Doctrine to fetch dynamic content (e.g., blog posts) and render via Liquid.
• CLI Scripts: Use Liquid for generating static files (e.g., sitemaps, RSS feeds) via Symfony’s console commands.

Gotchas and Tips

Pitfalls

1. Deprecated Bundle

   • Last release in 2020; verify compatibility with Symfony 5.1+ (may require patches).
   • Check for forks (e.g., liquid-template) if issues arise.

2. Cache Invalidation

   • Clear cache manually after template changes:

     php bin/console cache:clear
     

   • Disable caching in liquid.yaml during development:

     liquid:
         cache: null
     

3. Filter Conflicts

   • Custom filters must implement FilterInterface; otherwise, they won’t register.
   • Override built-in filters cautiously (e.g., price) to avoid breaking expected behavior.

4. Security

   • Liquid templates are not auto-escaping by default. Use |escape filter for user-generated content:

     {{ unsafeInput | escape }}
     

   • Avoid exposing sensitive data in templates (e.g., passwords, API keys).

5. Namespace Collisions

   • If using custom tags/filters, prefix classes to avoid conflicts:

     namespace App\Liquid\Tag;
     

Debugging

1. Template Errors

   • Enable debug mode in config/packages/dev/liquid.yaml:

     liquid:
         debug: true
     

   • Errors will show detailed tracebacks in logs (var/log/dev.log).

2. Missing Templates

   • Verify default_path in liquid.yaml points to the correct directory:

     liquid:
         default_path: '%kernel.project_dir%/templates/liquid'
     

3. Filter Issues

   • Check if filters are autoloaded (Composer autoload-dev may be needed for custom filters).

Tips

1. Performance

   • Pre-compile templates for production by setting cache to a persistent directory.

2. Extending Liquid

   • Add custom tags by implementing CodeMade\LiquidBundle\Tag\TagInterface:

     class MyTag implements TagInterface {
         public function parse(Parser $parser) { ... }
         public function render(Engine $engine, array $params) { ... }
     }
     

   • Register tags in liquid.yaml:

     liquid:
         tags:
             - App\Liquid\Tag\MyTag
     

3. IDE Support

   • Use Liquid language server for syntax highlighting in VSCode/PHPStorm.

4. Fallbacks

   • Provide default values for optional template variables:

     {% for product in products | default([]) %}
     

5. Testing Edge Cases

   • Test with empty arrays, null values, and nested objects to ensure robustness:

     {{ user.address.city | default('N/A') }}