Control Panel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require braunstetter/control-panel-bundle
   yarn install --force
   

   Ensure BraunstetterControlPanelBundle is enabled in config/bundles.php.

2. First Use Case:

   • Extend the base template (base.html.twig) by copying it to templates/ControlPanelBundle/base.html.twig.
   • Override hooks using TemplateHooksBundle (install via composer require braunstetter/template-hooks-bundle if needed).
   • Example: Add a custom sidebar menu by extending the sidebar hook in your template.

3. Routing: Define a route in config/routes.yaml:

   control_panel:
       resource: "@ControlPanelBundle/Resources/config/routing.yaml"
       prefix: /admin
   

4. Basic Page: Create a controller extending AbstractControlPanelController (if available) or use Twig templates directly:

   {% extends 'ControlPanelBundle::base.html.twig' %}
   {% block content %}
       <h1>Welcome to Your Control Panel</h1>
   {% endblock %}
   

Implementation Patterns

Template Extensibility

• Hook-Based Structure: Leverage TemplateHooksBundle hooks (e.g., sidebar, header, footer) to inject content without modifying core templates. Example:

  {% do hook('sidebar') %}
  <li><a href="{{ path('app_dashboard') }}">Dashboard</a></li>
  

• Layout Inheritance: Override base.html.twig to customize the mobile/desktop structure. Key hooks:

  • content: Main body content.
  • sidebar: Navigation menu.
  • header: Top bar (e.g., user profile, notifications).

Form Integration

• Custom Form Types: Use pre-built form types (e.g., ControlPanelType) for admin forms. Example:

  // src/Form/OrangePuppyType.php
  use Braunstetter\ControlPanelBundle\Form\ControlPanelType;
  
  class OrangePuppyType extends AbstractType {
      public function buildForm(FormBuilderInterface $builder, array $options) {
          $builder->add('name', ControlPanelType::class, [
              'label' => 'Puppy Name',
          ]);
      }
  }
  

• CRUD Workflow: Pair with EasyAdminBundle or SonataAdminBundle for rapid CRUD, but use this bundle for lightweight admin panels.

Routing and Controllers

• Controller Structure: Extend AbstractControlPanelController (if provided) or create custom controllers:

  namespace App\Controller;
  
  use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
  use Symfony\Component\HttpFoundation\Response;
  use Symfony\Component\Routing\Annotation\Route;
  
  class AdminController extends AbstractController {
      #[Route('/admin/dashboard', name: 'app_dashboard')]
      public function dashboard(): Response {
          return $this->render('admin/dashboard.html.twig');
      }
  }
  

• Asset Management: Use assets/ directory for CSS/JS. Override base.html.twig to include:

  {{ parent() }} {# Call parent template first #}
  {{ encore_entry_link_tags('admin-app') }} {# Webpack Encore assets #}
  

Workflow Tips

1. Start Small: Begin with a single page (e.g., dashboard) and extend hooks incrementally.
2. Mobile-First: The base template is mobile-responsive by default. Test on small screens early.
3. Modularize: Split admin sections into sub-bundles (e.g., UserAdminBundle) for scalability.

Gotchas and Tips

Pitfalls

1. Hook Naming Collisions:

   • Ensure hook names (e.g., sidebar) don’t conflict with other bundles. Prefix if needed (e.g., cp_sidebar).
   • Debug missing hooks with Twig’s {% if hook('sidebar') is defined %} checks.

2. Asset Loading:

   • Forgetting to call {{ parent() }} in extended templates breaks asset inclusion (e.g., Bootstrap CSS).
   • Verify Webpack Encore is configured for the admin-app entry point.

3. Form Type Dependencies:

   • Custom form types may require additional JS/CSS. Check the bundle’s Resources/public/ for dependencies.
   • Example: ControlPanelType might need select2 for enhanced selects.

4. Routing Conflicts:

   • The default /admin prefix may clash with other bundles. Adjust in routing.yaml:

     prefix: /app_admin
     

Debugging

• Template Debugging: Use Twig’s {% debug %} or Symfony’s profiler to inspect rendered hooks:

  {% block content %}
      {% debug %}
  {% endblock %}
  

• Form Validation: Custom form types may need validation overrides. Extend the base type:

  class OrangePuppyType extends ControlPanelType {
      public function configureOptions(OptionsResolver $resolver) {
          $resolver->setDefaults([
              'validation_groups' => ['Default', 'admin'],
          ]);
      }
  }
  

Configuration Quirks

1. TemplateHooksBundle:

   • If hooks aren’t firing, ensure TemplateHooksBundle is installed and configured in bundles.php.
   • Clear cache after adding new hooks:

     php bin/console cache:clear
     

2. Yarn Dependencies:

   • Running yarn install --force may resolve missing assets, but check package.json for required dev dependencies (e.g., bootstrap, select2).

3. Environment-Specific Assets:

   • Use Webpack Encore’s environment variables to load different assets in dev vs. prod:

     // webpack.config.js
     Encore.enableSingleRuntimeChunk()
                .setPublicPath('/admin/assets')
                .addEntry('admin-app', './assets/admin/app.js');
     

Extension Points

1. Custom Templates:

   • Override the entire layout by copying Resources/views/layouts/base.html.twig to templates/ControlPanelBundle/layouts/.
   • Extend specific sections (e.g., sidebar.html.twig) for granular control.

2. Dynamic Hooks:

   • Register hooks dynamically in controllers:

     use Braunstetter\TemplateHooksBundle\Hook\HookManager;
     
     public function __construct(private HookManager $hookManager) {}
     
     public function addDashboardHook() {
         $this->hookManager->add('sidebar', '<li>Dynamic Link</li>');
     }
     

3. Event Listeners:

   • Subscribe to bundle events (if documented) to modify behavior. Example:

     // src/EventListener/ControlPanelListener.php
     use Braunstetter\ControlPanelBundle\Event\ControlPanelEvent;
     
     class ControlPanelListener {
         public function onBuildPanel(ControlPanelEvent $event) {
             $event->addMenuItem('Settings', 'app_settings');
         }
     }
     

     Register in services.yaml:

     services:
         App\EventListener\ControlPanelListener:
             tags:
                 - { name: kernel.event_listener, event: control_panel.build, method: onBuildPanel }
     

4. API Integration:

   • Use the panel for API status pages by extending templates to include API response data:

     {% block content %}
         <div class="api-status">
             {% for endpoint, status in api_status %}
                 <p>{{ endpoint }}: {{ status }}</p>
             {% endfor %}
         </div>
     {% endblock %}