Sonata Theme Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require carlead/sonata-theme-bundle
   

   Add to config/app.php under ExtraBundles:

   Carlead\SonataThemeBundle\CarleadSonataThemeBundle::class,
   

2. Enable the Bundle Ensure CarleadSonataThemeBundle is registered in config/bundles.php (Symfony 4+).

3. First Use Case Override the default Sonata Admin theme by creating a custom template:

   php bin/console sonata:theme:dump
   

   Place your custom theme files in templates/CarleadSonataThemeBundle/ (or your preferred namespace).

Key Files to Inspect

• config/packages/sonata_theme.yaml (if provided)
• templates/CarleadSonataThemeBundle/layouts/base_admin_layout.html.twig
• templates/CarleadSonataThemeBundle/blocks/sonata_block_service.html.twig

Implementation Patterns

1. Theme Inheritance

Extend the default Sonata Admin theme by overriding specific blocks or layouts:

{# templates/CarleadSonataThemeBundle/layouts/base_admin_layout.html.twig #}
{% extends 'SonataAdminBundle::standard_layout.html.twig' %}

{% block sonata_body %}
    {{ parent() }}
    {# Custom content here #}
{% endblock %}

2. Dynamic Block Management

Use Sonata’s block system to inject custom content:

# config/packages/sonata_block.yaml
sonata_block:
    default_contexts: [sonata_admin]
    blocks:
        sonata.admin.block.admin_list:
            contexts: [sonata_admin]
        carlead_sonata.custom_block: ~

Register a custom block service:

// src/Service/CustomBlockService.php
namespace App\Service;

use Sonata\BlockBundle\Block\BlockContextInterface;
use Sonata\BlockBundle\Model\BlockInterface;
use Sonata\BlockBundle\Block\BaseBlockService;

class CustomBlockService extends BaseBlockService
{
    public function execute(BlockInterface $block, BlockContextInterface $blockContext)
    {
        return ['content' => 'Custom content!'];
    }
}

3. Asset Integration

Override or extend CSS/JS assets:

{# templates/CarleadSonataThemeBundle/blocks/sonata_block_service.html.twig #}
{% block sonata_assets %}
    {{ parent() }}
    <link rel="stylesheet" href="{{ asset('bundles/carleadsonata/css/custom.css') }}">
{% endblock %}

4. Configuration Overrides

Customize Sonata Admin settings via config:

# config/packages/sonata_admin.yaml
sonata_admin:
    templates:
        layout: CarleadSonataThemeBundle::base_admin_layout.html.twig
    options:
        html5_entities_naming: true

Gotchas and Tips

Pitfalls

1. Namespace Conflicts Ensure your template paths (templates/CarleadSonataThemeBundle/) match the bundle’s namespace. Misalignment causes TemplateNotFoundException.

2. Caching Issues Clear cache after theme changes:

   php bin/console cache:clear
   php bin/console sonata:theme:dump
   

3. Block Context Mismatch Blocks may fail if contexts in sonata_block.yaml don’t align with Sonata Admin routes. Verify with:

   php bin/console debug:sonata:contexts
   

4. Symfony 5+ Deprecations The bundle may not support Symfony’s latest features (e.g., Flex recipes). Check composer.json for symfony/* constraints.

Debugging Tips

• Template Debugging Enable Twig debug mode in .env:

  APP_DEBUG=1
  

  Use {{ dump(_context) }} in templates to inspect variables.

• Block Debugging Log block execution:

  // In CustomBlockService
  error_log('Block executed with: ' . print_r($block->getSettings(), true));
  

• Asset Loading Verify assets are compiled:

  php bin/console assets:install public
  

Extension Points

1. Custom Theme Switcher Dynamically switch themes via a route/controller:

   // src/Controller/ThemeController.php
   public function switchTheme(Request $request, ThemeManagerInterface $themeManager)
   {
       $theme = $request->query->get('theme', 'default');
       $themeManager->setTheme($theme);
       return new RedirectResponse($request->headers->get('referer'));
   }
   

2. Dynamic Block Settings Extend block settings via a form:

   # config/packages/sonata_block.yaml
   blocks:
       carlead_sonata.custom_block:
           form:
               type: App\Form\CustomBlockType
   

3. Event Listeners Hook into Sonata events (e.g., sonata.admin.event.configure):

   // src/EventListener/AdminListener.php
   public function onConfigure(ConfigureEvent $event)
   {
       $event->getSubject()->setTemplate('list', 'CarleadSonataThemeBundle:admin:custom_list.html.twig');
   }