Breadcrumb Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cnerta/breadcrumb-bundle:2.1.*
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   Cnerta\BreadcrumbBundle\CnertaBreadcrumbBundle::class => ['all' => true],
   

2. Prerequisite: Ensure KnpMenuBundle is installed (required dependency). Install via:

   composer require knplabs/knp-menu-bundle
   

3. First Use Case: Generate a breadcrumb in a controller or Twig template:

   {{ knp_menu('cnerta_breadcrumb', {
       'template': '@CnertaBreadcrumb/breadcrumb.html.twig',
       'rootLinks': false,
       'linkAttributes': {'class': 'breadcrumb-item'}
   }) }}
   

   Override the default template (breadcrumb.html.twig) in templates/CnertaBreadcrumb/breadcrumb.html.twig if needed.

Implementation Patterns

Workflows

1. Dynamic Breadcrumb Generation: Use the cnerta_breadcrumb menu builder in controllers or Twig:

   // Controller
   $breadcrumb = $this->get('knp_menu.factory')->createItem('root');
   $breadcrumb->setChildren([
       $this->get('knp_menu.factory')->createItem('Home', ['route' => 'home']),
       $this->get('knp_menu.factory')->createItem('Current Page', ['route' => 'current_route']),
   ]);
   return $this->render('page.html.twig', ['breadcrumb' => $breadcrumb]);
   

2. Route-Based Breading: Leverage Symfony’s routing system to auto-generate breadcrumbs:

   {{ knp_menu('cnerta_breadcrumb', {
       'matcher': 'knp_menu.matcher.route',
       'defaultRoute': 'home',
       'routeParameters': {'_locale': app.request.locale}
   }) }}
   

3. Template Customization: Extend the default template to add icons, separators, or ARIA labels:

   {% block breadcrumb_item %}
       <li class="breadcrumb-item">
           <a href="{{ item.uri }}">{{ item.label }}</a>
           {% if not item.children|length %}
               <span class="sr-only">, {{ 'Current'|trans }}</span>
           {% endif %}
       </li>
   {% endblock %}
   

4. Integration with KnpMenu: Use KnpMenu’s features (e.g., matcher, provider) to dynamically populate breadcrumbs:

   # config/packages/knp_menu.yaml
   knp_menu:
       twig:
           template: '@CnertaBreadcrumb/breadcrumb.html.twig'
       matcher: knp_menu.matcher.route
   

Gotchas and Tips

Pitfalls

1. Deprecated Bundle: The package is unmaintained (Symfony 2/3 focus). Avoid in new projects; consider alternatives like:

   • whiteoctober/pagerfanta-bundle (for pagination + breadcrumbs).
   • Custom Twig extensions with Symfony’s UrlGenerator.

2. KnpMenuBundle Dependency:

   • Ensure KnpMenuBundle is properly configured (e.g., matcher, provider).
   • Debug KnpMenu issues first if breadcrumbs fail to render.

3. Template Overrides:

   • Override templates in templates/CnertaBreadcrumb/ before clearing cache:

     php bin/console cache:clear
     

   • Verify the override path matches the bundle’s namespace (CnertaBreadcrumb).

4. Route Matching Quirks:

   • Use defaultRoute in Twig to handle edge cases (e.g., 404 pages):

     {{ knp_menu('cnerta_breadcrumb', {'defaultRoute': 'home'}) }}
     

   • Debug route parameters with {{ dump(app.request.attributes) }} in Twig.

5. Symfony 4+ Compatibility:

   • The bundle may not work out-of-the-box with Symfony Flex. Manually register the bundle in config/bundles.php and handle autoloading.

Debugging Tips

1. Check Menu Rendering: Dump the menu item structure in Twig:

   {{ dump(cnerta_breadcrumb) }}
   

2. Log Configuration: Enable debug mode (APP_DEBUG=true) and check Symfony’s profiler for KnpMenu errors.

3. Cache Issues: Clear cache after template/config changes:

   php bin/console cache:pool:clear knp_menu.cache_pool
   

Extension Points

1. Custom Providers: Extend KnpMenu’s ProviderInterface to fetch breadcrumbs from a database or API:

   // src/Service/CustomBreadcrumbProvider.php
   class CustomBreadcrumbProvider implements ProviderInterface {
       public function getItem($name) { ... }
   }
   

   Register in services.yaml:

   services:
       App\Service\CustomBreadcrumbProvider:
           tags: ['knp_menu.provider']
   

2. Event Listeners: Dynamically modify breadcrumbs via KnpMenu events (e.g., MenuEvent):

   // src/EventListener/BreadcrumbListener.php
   class BreadcrumbListener {
       public function onMenuPreBuild(MenuEvent $event) {
           $menu = $event->getMenu();
           $menu->addChild('Dynamic Item', ['route' => 'dynamic_route']);
       }
   }
   

   Bind in services.yaml:

   services:
       App\EventListener\BreadcrumbListener:
           tags: ['kernel.event_listener', { event: 'knp_menu.menu', method: 'onMenuPreBuild' }]
   

3. Twig Extensions: Create a custom Twig function to generate breadcrumbs with less boilerplate:

   // src/Twig/BreadcrumbExtension.php
   class BreadcrumbExtension extends \Twig\Extension\AbstractExtension {
       public function getFunctions() {
           return [
               new \Twig\TwigFunction('app_breadcrumb', [$this, 'renderBreadcrumb']),
           ];
       }
       public function renderBreadcrumb(array $options = []) {
           return $this->getMenuFactory()->createItem('root', $options);
       }
   }