README

A powerful, strategy-based block building system for Symfony applications. This bundle provides a flexible architecture for managing, editing, and rendering dynamic content blocks.

Features

• Strategy Pattern Architecture: Extensible system where each block type is handled by a dedicated strategy.
• Dual-View Rendering:
  • Editor: Complex, interactive templates (Twig + Stimulus + LiveComponents) for the admin interface.
  • Frontend: Lightweight, clean HTML structures defined in the database for performance and separation of concerns.
• Markdown Import: Intelligent service to convert Markdown content into structured blocks, delegating logic to strategies.
• Live Components Integration: Built-in support for Symfony UX Live Components for a rich editing experience.
• 13 Built-in Block Types: paragraph, image, quote, table, list, code, infobox, cta, howto, separator, video, faq_block, and snippet.
• 183 Tailwind CSS Snippets: Pre-built UI components across 32 categories, optionally loadable via sync command.

Documentation

• Installation & Usage
• Technical Architecture
• How to Add a New Block Type

Installation

1. Require the bundle:

   composer require symkit/builder-bundle

2. Enable the bundle (if not auto-enabled):

   // config/bundles.php
   return [
       // ...
       Symkit\BuilderBundle\SymkitBuilderBundle::class => ['all' => true],
   ];

Configuration

All features are enabled by default. You can override entity classes and toggle features in config/packages/symkit_builder.yaml:

symkit_builder:
    admin:
        enabled: true
        route_prefix: admin   # URL prefix for admin routes (default: admin)
    doctrine:
        enabled: true
        entity:
            block_class: Symkit\BuilderBundle\Entity\Block
            block_repository_class: Symkit\BuilderBundle\Repository\BlockRepository
            block_category_class: Symkit\BuilderBundle\Entity\BlockCategory
            block_category_repository_class: Symkit\BuilderBundle\Repository\BlockCategoryRepository
    twig:
        enabled: true
    assets:
        enabled: true
    command:
        enabled: true
    live_component:
        enabled: true

Routes

Include the bundle admin routes in your app (e.g. config/routes.yaml):

symkit_builder:
    resource: '@SymkitBuilderBundle/Resources/config/routing.yaml'
    prefix: '%symkit_builder.admin.route_prefix%'

This registers routes such as admin_block_list, admin_block_create, admin_block_edit, admin_block_category_*. Change route_prefix in config to alter the URL prefix (e.g. /back-office/blocks).

Dependencies

Ensure you have the following bundles enabled and configured:

• Symfony\UX\LiveComponent\LiveComponentBundle
• Symfony\UX\TwigComponent\TwigComponentBundle
• Symfony\UX\StimulusBundle\StimulusBundle

Usage

1. Rendering Blocks

Two Twig functions are available for rendering blocks in your frontend templates.

Render a single block (accepts an array):

{# templates/page/show.html.twig #}

{% for block in page.content %}
    {{ symkit_render_block(block) }}
{% endfor %}

Render all blocks at once (accepts a JSON string or an array):

{{ symkit_render_content_blocks(page.content) }}

Or manually via the service:

use Symkit\BuilderBundle\Contract\BlockRendererInterface;

public function show(BlockRendererInterface $renderer, array $blocks)
{
    // Render a single block
    $html = $renderer->renderBlock($block);

    // Or render all blocks at once
    $html = $renderer->renderBlocks($blocks);
}

2. Synchronizing Blocks

Blocks are defined within the BlockSynchronizer service. To ensure your database is updated with the latest block definitions, run the synchronization command:

php bin/console builder:sync-blocks

To also include the 183 Tailwind CSS snippets:

php bin/console builder:sync-blocks --snippets

This command uses an idempotent "upsert" logic, updating existing blocks by their code and creating new ones as needed.

3. Built-in Block Types

The bundle ships with 13 core block types across 6 categories:

4. Adding a New Block Type

To add a block type without custom logic, register it in BlockSynchronizer and use AbstractBlockStrategy as the default fallback. See How to Add a New Block Type for the full guide.

For complex blocks (e.g., fetching data, processing URLs), create a Strategy:

1. Create a class implementing BlockStrategyInterface (or extending AbstractBlockStrategy).
2. Implement supports(), prepareData(), render().
3. Implement supportsNode() and createFromNode() for Markdown import support.

namespace App\Block\Strategy;

use Symkit\BuilderBundle\Render\Strategy\AbstractBlockStrategy;

class MyCustomBlockStrategy extends AbstractBlockStrategy
{
    public function supports(array $block): bool
    {
        return $block['type'] === 'my_custom_block';
    }

    // ... implement other methods
}

The service will be automatically tagged and used by the BlockRenderer.