Layout Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cleverage/layout-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Cleverage\LayoutBundle\CleverAgeLayoutBundle::class => ['all' => true],
   ];
   

2. First Layout File Create a YAML layout file (e.g., config/layouts/base.yml):

   layout:
       blocks:
           header:
               code: "@App/Block/HeaderBlock"
               position: absolute
               top: 0
               left: 0
           content:
               code: "@App/Block/ContentBlock"
               position: relative
               top: 50px
   

3. First Block Class Create a block (e.g., src/Block/HeaderBlock.php):

   namespace App\Block;
   
   use Cleverage\LayoutBundle\Block\AbstractBlock;
   
   class HeaderBlock extends AbstractBlock
   {
       public function render()
       {
           return $this->renderView('blocks/header.html.twig');
       }
   }
   

4. Render the Layout In a controller:

   use Cleverage\LayoutBundle\Layout\LayoutManager;
   
   public function index(LayoutManager $layoutManager)
   {
       $layout = $layoutManager->getLayout('base');
       return new Response($layout->render());
   }
   

First Use Case

Dynamic Layout Composition Use the bundle to define reusable layouts (e.g., admin.yml, public.yml) and swap them via configuration or runtime logic.

Implementation Patterns

Layout Inheritance

1. Extend Layouts Define a child layout (config/layouts/admin.yml):

   extends: base
   layout:
       blocks:
           sidebar:
               code: "@App/Block/AdminSidebarBlock"
               position: absolute
               right: 0
   

2. Override Blocks Reuse parent blocks while overriding specific ones:

   extends: base
   layout:
       blocks:
           header:
               code: "@App/Block/AdminHeaderBlock"  # Override
           footer:
               code: "@App/Block/DefaultFooterBlock" # Inherit from parent
   

Block Management

1. Dynamic Block Registration Register blocks programmatically in a service:

   $container->set('app.block.custom', function () {
       return new CustomBlock();
   });
   

2. Parameterized Blocks Pass parameters via YAML:

   blocks:
       content:
           code: "@App/Block/ContentBlock"
           params:
               title: "Welcome"
               items: ["item1", "item2"]
   

   Access in block:

   $this->getParameter('title'); // "Welcome"
   

3. Slot-Based Layouts Use slots for flexible content injection:

   layout:
       slots:
           main:
               blocks:
                   - "@App/Block/Slot1Block"
                   - "@App/Block/Slot2Block"
   

Integration with Twig

1. Embed Blocks in Twig Render a layout in a Twig template:

   {{ render_layout('base') }}
   

2. Pass Context to Layouts

   $layout = $layoutManager->getLayout('base', [
       'user' => $user,
       'theme' => 'dark'
   ]);
   

Caching Strategy

1. Cache Invalidation Clear cache when layouts/blocks change:

   php bin/console cache:clear
   

   Or programmatically:

   $this->get('cleverage_layout.cache')->invalidateAll();
   

2. Custom Cache Keys Override cache key generation in a custom block:

   public function getCacheKey()
   {
       return parent::getCacheKey() . '-custom-suffix';
   }
   

Gotchas and Tips

Common Pitfalls

1. Circular Dependencies

   • Issue: Layout A extends Layout B, which extends Layout A.
   • Fix: Validate YAML inheritance chains or use a tool like symfony/var-dumper to debug.

2. Block Not Found

   • Issue: code: "@App/Block/NonExistentBlock" throws ServiceNotFoundException.
   • Fix: Ensure the block is registered as a service (annotated or manually in services.yaml).

3. Parameter Overrides

   • Issue: Child layout parameters silently override parent parameters.
   • Fix: Use !merge in YAML to preserve parent values:

     layout:
         params: !merge
             <<: *parent_params  # Inherit
             new_param: "value"  # Override
     

4. Twig Auto-Reloading

   • Issue: Twig templates don’t update after changes.
   • Fix: Disable cache in config/packages/twig.yaml during development:

     twig:
         cache: false
     

Debugging Tips

1. Dump Layout Structure Use the debug command:

   php bin/console debug:cleverage-layout
   

2. Log Block Rendering Enable debug mode in config/packages/dev/cleverage_layout.yaml:

   cleverage_layout:
       debug: true
   

3. Cache Key Inspection Override getCacheKey() in a block to log keys:

   public function getCacheKey()
   {
       $key = parent::getCacheKey();
       error_log("Cache key: " . $key);
       return $key;
   }
   

Extension Points

1. Custom Block Types Extend AbstractBlock to add behavior:

   class ConditionalBlock extends AbstractBlock
   {
       public function render()
       {
           if ($this->getParameter('condition')) {
               return parent::render();
           }
           return '';
       }
   }
   

2. Layout Events Listen for layout rendering events:

   // config/services.yaml
   services:
       App\EventListener\LayoutListener:
           tags:
               - { name: kernel.event_listener, event: cleverage_layout.render, method: onRender }
   

3. Custom Positioning Logic Override getPosition() in a block for dynamic placement:

   public function getPosition()
   {
       return $this->getParameter('is_sticky') ? 'fixed' : 'relative';
   }
   

Configuration Quirks

1. YAML Anchors Reuse common configurations with YAML anchors:

   defaults: &defaults
       position: relative
       top: 0
   
   layout:
       blocks:
           header:
               <<: *defaults
               code: "@App/Block/HeaderBlock"
   

2. Global Parameters Define global parameters in config/packages/cleverage_layout.yaml:

   cleverage_layout:
       global_params:
           site_name: "My Site"
           version: "1.0"
   

   Access in blocks via $this->getGlobalParameter('site_name').

3. Environment-Specific Layouts Use Symfony’s %env% in YAML:

   layout:
       blocks:
           footer:
               code: "@App/Block/FooterBlock_%kernel.environment%"