Twiew Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require a-proud/twiew-bundle:dev-main
   

   Ensure TwigBundle is installed (dependency) and registered in config/bundles.php.

2. Configure Twig Paths Add the Twiew template path to config/packages/twig.yaml:

   twig:
       paths:
           "%kernel.project_dir%/vendor/a-proud/twiew-bundle/templates": twiew
   

3. First Use Case: Render a Basic Page Define a YAML config (e.g., config/twiew/page.yml):

   default:
       css: ["css/main.css"]
       js_top: []
       header: { tpl: "header.twig", blocks: [] }
       main: { tpl: "main.twig", blocks: [{ tpl: "content_block.twig", cols: 12 }] }
       footer: { tpl: "footer.twig", blocks: [] }
       js_bottom: ["js/script.js"]
   

   Render it in a controller:

   use AProud\TwiewBundle\Renderer\TwiewRenderer;
   
   public function renderPage(TwiewRenderer $renderer)
   {
       $config = yaml_parse_file(__DIR__.'/../../config/twiew/page.yml');
       return $renderer->render($config['default']);
   }
   

Implementation Patterns

Workflow: Template-Driven Page Assembly

1. Modular Configuration Split page logic into reusable YAML files (e.g., header.yml, footer.yml) and merge them:

   $config = array_merge(
       yaml_parse_file('config/twiew/header.yml'),
       yaml_parse_file('config/twiew/main.yml')
   );
   

2. Dynamic Content Injection Pass variables to templates via data key in YAML:

   main:
       tpl: "dashboard.twig"
       blocks: [{ tpl: "stats_block.twig", data: { stats: $stats } }]
   

   Access in Twig:

   {% for stat in stats %}
       {{ stat.value }}
   {% endfor %}
   

3. Layout Inheritance Extend base templates (e.g., base.twig) and override sections:

   extends: "base.twig"
   header: { tpl: "custom_header.twig" }
   

4. Asset Management Use css/js_top/js_bottom for global assets. For dynamic scripts:

   js_bottom:
       - "js/vendor/jquery.js"
       - { src: "js/app.js", defer: true }
   

5. Component Reusability Create shared blocks (e.g., sidebar.twig) and reuse across pages:

   main:
       blocks:
           - { tpl: "sidebar.twig", cols: 3 }
           - { tpl: "content.twig", cols: 9 }
   

Gotchas and Tips

Pitfalls

1. Template Path Resolution

   • Issue: Twig fails to find templates if paths in twig.yaml is misconfigured.
   • Fix: Verify the path points to vendor/a-proud/twiew-bundle/templates and clear cache:

     php bin/console cache:clear
     

2. YAML Parsing Quirks

   • Issue: Nested arrays in YAML may break if indentation is inconsistent.
   • Fix: Use tools like YAML Lint or PHP’s yaml_parse_file() with error handling:

     $config = yaml_parse_file('config.yml') ?: throw new \RuntimeException('Invalid YAML');
     

3. Block Column Constraints

   • Issue: Blocks with cols exceeding 12 (default grid) may render incorrectly.
   • Fix: Validate column sums per row (e.g., cols: 6 + cols: 6 = 12).

4. Circular Dependencies

   • Issue: Extending templates that rely on undefined parent blocks (e.g., extends: "nonexistent.twig").
   • Fix: Use extends: "base.twig" as a fallback and validate template existence.

5. Asset Loading Order

   • Issue: JavaScript/CSS loaded out of order (e.g., js_bottom before js_top).
   • Fix: Explicitly order arrays or use priority keys in config.

Debugging Tips

1. Template Dumping Enable Twig debug mode in config/packages/dev/twig.yaml:

   twig:
       debug: true
       strict_variables: true
   

   Access debug toolbar at /_profiler.

2. Config Validation Add runtime checks for mandatory keys:

   $mandatory = ['css', 'js_top', 'header', 'main', 'footer', 'js_bottom'];
   foreach ($mandatory as $key) {
       if (!isset($config[$key])) {
           throw new \InvalidArgumentException("Missing mandatory key: {$key}");
       }
   }
   

3. Extension Points

   • Custom Components: Override default templates by placing them in templates/twiew/ (higher priority than vendor).
   • Event Listeners: Extend rendering logic via Symfony events (e.g., twiew.render):

     // src/EventListener/TwiewListener.php
     public function onRender(TwiewEvent $event) {
         $event->getConfig()->set('custom_key', 'value');
     }
     

     Register in services.yaml:

     services:
         App\EventListener\TwiewListener:
             tags:
                 - { name: kernel.event_listener, event: twiew.render, method: onRender }
     

4. Performance

   • Caching: Cache rendered pages for static content:

     $renderer->render($config, ['cache_key' => 'homepage']);
     

   • Asset Fingerprinting: Use Symfony’s asset() function with versioning for JS/CSS:

     js_bottom:
         - { src: "{{ asset('js/app.js', 'sha1') }}" }