Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require bkstg/core-bundle
   

   Register it in config/bundles.php:

   return [
       // ...
       Backstage\CoreBundle\BackstageCoreBundle::class => ['all' => true],
   ];
   

2. Dependencies Ensure these required bundles are installed and configured:

   • doctrine/doctrine-bundle
   • exercise/htmlpurifier-bundle
   • friendsofsymfony/ckeditor-bundle
   • knplabs/knp-menu-bundle
   • knplabs/knp-paginator-bundle (implied by the README’s context)

   Follow the standard distribution for default configurations.

3. First Use Case Leverage the menu builder (knp-menu-bundle) for navigation:

   {{ knp_menu('backstage_menu', {
       'rootName': 'backstage',
       'currentUri': app.request.getUri()
   }) }}
   

   Configure the menu in config/packages/knp_menu.yaml:

   knp_menu:
       backstage_menu:
           items:
               dashboard:
                   label: Dashboard
                   uri: /dashboard
   

Implementation Patterns

Core Workflows

1. Twig Integration The bundle provides Twig extensions for common Backstage patterns (e.g., menus, HTML sanitization). Extend templates in templates/backstage/:

   {% extends 'backstage/base.html.twig' %}
   {% block body %}
       {{ parent() }}
       {# Custom content #}
   {% endblock %}
   

2. CKEditor Configuration Use the ckeditor_bundle for rich text editing. Configure in config/packages/fos_ckeditor.yaml:

   fos_ckeditor:
       base_path: /bundles/backstage/ckeditor
       config:
           toolbar: ['Bold', 'Italic', 'NumberedList']
   

3. Doctrine Entities The bundle likely includes base entities (e.g., User, Page). Extend them in src/Entity/:

   namespace App\Entity;
   
   use Backstage\CoreBundle\Entity\BaseEntity;
   
   class CustomPage extends BaseEntity { ... }
   

4. Event Listeners Hook into Backstage events (e.g., backstage.page.publish). Register in src/EventListener/:

   namespace App\EventListener;
   
   use Backstage\CoreBundle\Event\PageEvents;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class PagePublishListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [PageEvents::PAGE_PUBLISH => 'onPagePublish'];
       }
       public function onPagePublish(PagePublishEvent $event) { ... }
   }
   

Integration Tips

• Asset Management: Use Symfony’s asset pipeline for JS/CSS in assets/backstage/.
• Security: Apply htmlpurifier to user-generated content:

  {{ content|purify_html }}
  

• Pagination: Use knp_paginator for lists:

  $pages = $paginator->paginate(
      $pagesQuery,
      $request->query->getInt('page', 1),
      10
  );
  

Gotchas and Tips

Pitfalls

1. Dependency Conflicts

   • The bundle requires specific versions of its dependencies. Use composer why-not to debug conflicts.
   • Example: If friendsofsymfony/ckeditor-bundle fails, check for version mismatches in composer.lock.

2. Menu Configuration

   • The backstage_menu must match the Twig template’s expected name. Misconfiguration causes blank menus.
   • Debug with:

     php bin/console debug:container knp_menu.menu_manager
     

3. Doctrine Migrations

   • The bundle may include migrations. Run:

     php bin/console doctrine:migrations:migrate
     

   • If migrations fail, check for reserved keywords in entity fields (e.g., order).

4. Twig Autoloading

   • Ensure templates/backstage/ is in your Twig loader paths. Add to config/packages/twig.yaml:

     twig:
         paths: ['%kernel.project_dir%/templates/backstage']
     

Debugging

• Event Dispatcher: Verify events are fired with:

  php bin/console debug:event-dispatcher
  

• CKEditor Assets: Clear cache if editor assets fail:

  php bin/console cache:clear
  rm -rf var/cache/*
  

Extension Points

1. Custom Templates Override bundle templates by placing them in templates/backstage/BackstageCoreBundle/.

2. Service Overrides Extend services via compiler passes or configuration:

   # config/packages/backstage.yaml
   backstage_core:
       services:
           app.custom_service: '@app.service.id'
   

3. HTML Purifier Rules Customize allowed tags in config/packages/htmlpurifier.yaml:

   htmlpurifier:
       config:
           HTML.Allowed: 'p[style],a[href],strong'
   

4. Menu Builders Create dynamic menus with a custom builder:

   namespace App\Menu;
   
   use Knp\Menu\FactoryInterface;
   use Symfony\Component\HttpFoundation\Request;
   
   class CustomMenuBuilder {
       public function mainMenu(FactoryInterface $factory, array $options) {
           $menu = $factory->createItem('root');
           // ...
           return $menu;
       }
   }
   

   Register in config/packages/knp_menu.yaml:

   knp_menu:
       backstage_menu:
           builder: app.custom_menu_builder