Builder Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require akyos/builder-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Akyos\BuilderBundle\AkyosBuilderBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Override default settings in config/packages/akyos_builder.yaml:

   akyos_builder:
       blocks: ['header', 'content', 'footer']  # Define available blocks
       templates: ['default', 'custom']        # Define templates
   

3. First Use Case: Creating a Page Define a page entity (e.g., Page):

   // src/Entity/Page.php
   use Akyos\BuilderBundle\Entity\PageInterface;
   
   class Page implements PageInterface {
       // ...
   }
   

   Use the builder in a controller:

   use Akyos\BuilderBundle\Builder\PageBuilder;
   
   class PageController {
       public function edit(PageBuilder $builder, Page $page) {
           return $builder->edit($page);
       }
   }
   

4. Key Directories

   • templates/akyos_builder/ – Default Twig templates for blocks.
   • src/Resources/config/akyos_builder.yaml – Default config.

Implementation Patterns

Workflows

1. Block-Based Development

   • Define reusable blocks in config/packages/akyos_builder.yaml:

     akyos_builder:
         blocks:
             header:
                 type: 'header'       # Block type (e.g., 'text', 'image', 'custom')
                 template: 'blocks/header.html.twig'
                 fields:
                     - { name: 'title', type: 'text' }
                     - { name: 'logo', type: 'media' }
             content:
                 type: 'rich_text'
                 template: 'blocks/content.html.twig'
     

   • Extend block types via services (see Extension Points).

2. Template Inheritance Override default templates by copying files from templates/akyos_builder/ to your project’s templates/ directory.

3. Dynamic Page Assembly Use the PageBuilder to construct pages programmatically:

   $page = $builder->createPage('home');
   $page->addBlock('header', ['title' => 'Welcome']);
   $page->addBlock('content', ['content' => '<p>Hello!</p>']);
   $builder->save($page);
   

4. Integration with CMS

   • Use PageRepository to fetch/save pages:

     $repository = $this->get(PageRepository::class);
     $page = $repository->findOneBy(['slug' => 'about']);
     

   • Hook into lifecycle events (e.g., prePersist, preUpdate) via Doctrine listeners.

5. Frontend Rendering Render pages in Twig:

   {{ render(akyos_builder_page(page)) }}
   

   Or use the PageRenderer service:

   $renderer = $this->get(PageRenderer::class);
   echo $renderer->render($page);
   

Integration Tips

1. Symfony Forms Integrate with Symfony Forms for block configuration:

   use Akyos\BuilderBundle\Form\Type\BlockType;
   
   $builder->add('header', BlockType::class, [
       'block_type' => 'header',
       'data' => $page->getBlock('header'),
   ]);
   

2. Media Handling Use VichUploaderBundle or similar for media fields in blocks:

   fields:
       - { name: 'image', type: 'media', options: { vich_uploader: 'images' } }
   

3. Localization Support multilingual blocks by extending BlockInterface and using Symfony’s translation tools.

4. API Endpoints Expose pages/blocks via API (e.g., with API Platform):

   # config/api_platform/resources.yaml
   resources:
       Akyos\BuilderBundle\Entity\Page:
           collectionOperations:
               - GET
           itemOperations:
               - GET
               - PUT
   

5. Asset Management Use Webpack Encore or similar to compile block-specific CSS/JS:

   {# templates/blocks/custom.html.twig #}
   {{ encore_entry_link_tags('blocks-custom') }}
   

Gotchas and Tips

Pitfalls

1. Block Type Mismatches

   • Ensure block_type in config matches the registered type (e.g., 'header' must have a corresponding HeaderBlockType service).
   • Fix: Verify services.yaml for custom block types:

     services:
         Akyos\BuilderBundle\Form\Type\HeaderBlockType:
             tags: [akyos_builder.block_type]
     

2. Template Overrides

   • Overriding templates requires exact directory structure (e.g., templates/akyos_builder/blocks/header.html.twig).
   • Fix: Use {{ parent() }} in Twig to extend parent templates.

3. Circular Dependencies

   • Avoid circular references in block fields (e.g., Block A references Block B, which references Block A).
   • Fix: Use lazy-loading or proxy services for complex relationships.

4. Doctrine Lifecycle Conflicts

   • Custom Doctrine events (e.g., prePersist) may conflict with BuilderBundle’s listeners.
   • Fix: Use priority in event subscribers:

     ->addEventListener(PrePersist::class, [$listener, 'onPrePersist'], 20) // Lower priority
     

5. Performance with Large Pages

   • Pages with many blocks may slow down rendering.
   • Fix: Implement caching for rendered pages:

     $renderer->render($page, ['cache' => true]);
     

Debugging

1. Enable Debug Mode Set AKYOS_BUILDER_DEBUG: true in .env to log block rendering issues.

2. Common Errors

   • "Block type not found": Check config/packages/akyos_builder.yaml for typos.
   • "Template not found": Ensure template files exist in the correct directory.
   • "Field validation failed": Validate block field types in BlockType classes.

3. Logging Use Symfony’s logger to debug block processing:

   $this->logger->debug('Block data:', ['data' => $block->getData()]);
   

Tips

1. Custom Block Types Create reusable block types by extending AbstractBlockType:

   class CustomBlockType extends AbstractBlockType {
       public function getBlockType() { return 'custom'; }
       public function getFields() {
           return [
               ['name' => 'title', 'type' => 'text'],
               ['name' => 'content', 'type' => 'rich_text'],
           ];
       }
   }
   

   Register the service with the akyos_builder.block_type tag.

2. Dynamic Block Configuration Use Symfony’s ParameterBag to pass dynamic options:

   akyos_builder:
       blocks:
           dynamic:
               type: 'custom'
               options:
                   max_items: '%env(int:MAX_DYNAMIC_BLOCKS)%'
   

3. Versioning Implement soft-deletes for pages/blocks using Doctrine Extensions:

   use Gedmo\SoftDeleteable\SoftDeleteableEntity;
   
   class Page extends SoftDeleteableEntity implements PageInterface { ... }
   

4. Testing Use functional tests to verify page rendering:

   public function testPageRendering(Client $client) {
       $page = $this->createTestPage();
       $client->request('GET', '/page/' . $page->getSlug());
       $this->assertSelectorTextContains('h1', 'Welcome');
   }
   

5. Extension Points

   • Block Types: Extend via AbstractBlockType and tag services.
   • Templates: Override Twig templates in your project.
   • Repositories: Extend PageRepository for custom queries.
   • Events: Dispatch custom events (e.g., PageBuiltEvent) via Symfony’s event dispatcher.

6. Security

   • Protect block configuration forms with Symfony’s security system:

     # config/packages/security.yaml
     access_control:
         - { path: ^/admin/builder, roles: ROLE_ADMIN }