Ai Twig Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aimeos/ai-twig
   

   Ensure aimeos/aimeos-twig (or the core Aimeos package) is also installed as a dependency.

2. Register the Service Provider In config/app.php, add to the providers array:

   Aimeos\Twig\Provider::class,
   

3. Configure Aimeos Add Twig as a template engine in config/aimeos.php:

   'template' => [
       'engine' => 'twig',
       'path' => base_path('resources/views/aimeos'),
   ],
   

4. First Use Case Render a simple Aimeos block in a Twig template:

   {% aimeos_block 'product/list' %}
   

   Ensure your Twig view extends a layout that includes Aimeos' Twig extensions.

Implementation Patterns

Core Workflows

1. Block Rendering Use aimeos_block to render any Aimeos block (e.g., product lists, cart, search):

   {% aimeos_block 'product/list', {
       'product': { 'list': { 'limit': 10 } }
   } %}
   

2. Dynamic Data Binding Pass Aimeos context data to Twig:

   // In your Laravel controller
   $context = \Aimeos\MShop::createContext();
   return view('your.view', ['aimeos' => $context]);
   

   Access in Twig:

   {% set context = aimeos %}
   {% aimeos_block 'product/list', context %}
   

3. Customizing Blocks Override block templates by placing them in resources/views/aimeos/blocks/. Example: Copy product/list.twig to extend it.

4. Integration with Laravel Views Use Aimeos blocks alongside Laravel Blade:

   @extends('layouts.app')
   @section('content')
       {% aimeos_block 'product/list' %}
   @endsection
   

5. Client-Side Integration For SPAs or JavaScript-heavy apps, use Aimeos' REST API and render blocks via AJAX:

   fetch('/aimeos/rest/product/list')
       .then(response => response.text())
       .then(html => document.getElementById('product-list').innerHTML = html);
   

Gotchas and Tips

Pitfalls

1. Namespace Collisions Avoid naming Twig templates or variables aimeos to prevent conflicts with the package's global functions.

2. Caching Quirks Aimeos blocks are cached by default. Clear the cache after template changes:

   php artisan cache:clear
   php artisan view:clear
   

3. Context Management Ensure the Aimeos context is passed to Twig views. Missing context causes Undefined variable "aimeos" errors.

4. Block Dependencies Some blocks (e.g., cart) require specific context data. Check the Aimeos documentation for dependencies.

5. Twig Extensions The package registers global Twig functions (aimeos_block, aimeos_url). Disable them if needed:

   // In a service provider
   $twig->addFunction(new \Twig\TwigFunction('aimeos_block', [...], 'never'));
   

Debugging Tips

1. Enable Aimeos Debugging Set in config/aimeos.php:

   'debug' => true,
   

   Logs errors to storage/logs/aimeos.log.

2. Inspect Block Output Use Twig's dump to debug block data:

   {% aimeos_block 'product/list' %}
   {{ dump(_context.getBlockData()) }}
   

3. Check Template Paths Verify template.path in config/aimeos.php points to an existing directory.

4. Fallback Templates If a block template is missing, Aimeos falls back to its default. Override by copying the default template from:

   vendor/aimeos/aimeos-twig/resources/views/aimeos/blocks/
   

Extension Points

1. Custom Twig Functions Extend the package by adding your own Twig functions:

   $twig->addFunction(new \Twig\TwigFunction('custom_aimeos_func', function() {
       return \Aimeos\MShop::createContext()->getSomething();
   }));
   

2. Modify Block Data Filter or transform block data before rendering:

   {% set blockData = _context.getBlockData()|merge({'custom': 'value'}) %}
   {% aimeos_block 'product/list', blockData %}
   

3. Hook into Aimeos Events Use Laravel's service container to bind Aimeos events:

   $this->app->bind(\Aimeos\MShop\Context\Item\Address\Event\Manager::class, function() {
       return new class {
           public function onAddressSave(\Aimeos\MShop\Context\Item\Address\Event\Address\Save $event) {
               // Custom logic
           }
       };
   });
   

4. Override Block Logic Extend Aimeos classes (e.g., \Aimeos\MShop\Twig\Block\Product\List) in a custom package to modify block behavior.