Breadcrumbs Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require mhujer/breadcrumbs-bundle
   

   Enable in config/bundles.php:

   WhiteOctober\BreadcrumbsBundle\WhiteOctoberBreadcrumbsBundle::class => ['all' => true],
   

2. Basic Configuration: Create config/packages/white_october_breadcrumbs.yaml with:

   white_october_breadcrumbs: ~
   

3. First Use Case: In a controller (e.g., src/Controller/PostController.php), inject the service and add a breadcrumb:

   use WhiteOctober\BreadcrumbsBundle\BreadcrumbsGenerator;
   
   public function show(Post $post, BreadcrumbsGenerator $breadcrumbs)
   {
       $breadcrumbs->addRouteItem('Home', 'homepage');
       $breadcrumbs->addItem('Posts', $this->generateUrl('post_index'));
       $breadcrumbs->addItem('Post: ' . $post->getTitle(), $this->generateUrl('post_show', ['id' => $post->getId()]));
   }
   

4. Display in Twig: Add to your template (e.g., templates/base.html.twig):

   {% block breadcrumbs %}
       {% if breadcrumbs %}
           <nav class="breadcrumbs" aria-label="Breadcrumbs">
               <ol>
                   {% for breadcrumb in breadcrumbs %}
                       <li{{ breadcrumb.isActive ? ' class="active"' : '' }}>
                           {% if breadcrumb.link %}
                               <a href="{{ breadcrumb.link }}">{{ breadcrumb.title }}</a>
                           {% else %}
                               {{ breadcrumb.title }}
                           {% endif %}
                       </li>
                   {% endfor %}
               </ol>
           </nav>
       {% endif %}
   {% endblock %}
   

Implementation Patterns

Common Workflows

1. Dynamic Breadcrumbs: Use addItem() with dynamic data (e.g., user-specific routes):

   $breadcrumbs->addItem(
       'User: ' . $user->getName(),
       $this->generateUrl('user_profile', ['id' => $user->getId()])
   );
   

2. Route-Based Breadcrumbs: Leverage addRouteItem() for Symfony routes:

   $breadcrumbs->addRouteItem('Dashboard', 'dashboard');
   $breadcrumbs->addRouteItem('Projects', 'project_index');
   

3. Entity Hierarchies: Build breadcrumbs from nested entities (e.g., categories/subcategories):

   $category = $post->getCategory();
   $breadcrumbs->addItem('Home', $this->generateUrl('homepage'));
   $breadcrumbs->addItem($category->getParent()->getName(), $this->generateUrl('category_show', ['id' => $category->getParent()->getId()]));
   $breadcrumbs->addItem($category->getName(), $this->generateUrl('category_show', ['id' => $category->getId()]));
   

4. Twig Extensions: Use the white_october_breadcrumbs Twig function for templates:

   {{ white_october_breadcrumbs()|raw }}
   

5. Service Integration: Inject BreadcrumbsGenerator into services (e.g., event listeners):

   public function onKernelRequest(GetResponseEvent $event, BreadcrumbsGenerator $breadcrumbs)
   {
       if ($event->isMasterRequest()) {
           $breadcrumbs->addRouteItem('Home', 'homepage');
       }
   }
   

Integration Tips

• Symfony Router: Always use $this->generateUrl() for links to ensure consistency with Symfony’s routing system.
• Translation: Wrap breadcrumb titles in translation functions (e.g., trans('messages.home')) for i18n support.
• Caching: Clear the cache (php bin/console cache:clear) after adding new routes or templates.
• Testing: Mock BreadcrumbsGenerator in PHPUnit tests to verify breadcrumb logic:

  $breadcrumbs = $this->createMock(BreadcrumbsGenerator::class);
  $breadcrumbs->expects($this->once())->method('addItem');
  

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • The bundle is archived and no longer maintained. Use Huluti/BreadcrumbsBundle for Symfony 8+.
   • Check for breaking changes if migrating from whiteoctober/BreadcrumbsBundle.

2. Route Resolution:

   • If links fail, ensure the route exists and is properly configured in config/routes.yaml or annotations.
   • Debug with:

     php bin/console debug:router
     

3. Twig Context:

   • The white_october_breadcrumbs Twig function requires the BreadcrumbsGenerator service to be available. If missing, check:
     • The bundle is enabled in bundles.php.
     • No typos in the Twig function name.

4. Active State Logic:

   • The isActive property is determined by the current request’s route. If breadcrumbs appear incorrect, verify:
     • The controller/action matches the route in addRouteItem().
     • No conflicting route priorities in Symfony’s router.

5. Performance:

   • Avoid heavy logic in breadcrumb generation (e.g., database queries). Cache results if needed:

     $breadcrumbs->addItem('Cached Item', $this->generateUrl('cached_route'), ['cache' => true]);
     

Debugging Tips

• Dump Breadcrumbs: Add this to a controller to inspect the breadcrumb object:

  dump($breadcrumbs->get());
  

• Check Service Availability: Verify the service is registered:

  php bin/console debug:container white_october_breadcrumbs
  

• Clear Cache: After configuration changes:

  php bin/console cache:clear --env=prod
  

Extension Points

1. Custom Renderers: Override the Twig template or create a custom renderer by extending the bundle’s logic:

   {% macro render_breadcrumbs(breadcrumbs) %}
       <nav aria-label="Custom Breadcrumbs">
           <ul>
               {% for item in breadcrumbs %}
                   <li class="{{ item.isActive ? 'active' }}">
                       {% if item.link %}<a href="{{ item.link }}">{{ item.title }}</a>{% else %}{{ item.title }}{% endif %}
                   </li>
               {% endfor %}
           </ul>
       </nav>
   {% endmacro %}
   

2. Event Listeners: Dynamically modify breadcrumbs via events (e.g., kernel.request):

   public function onKernelRequest(GetResponseEvent $event, BreadcrumbsGenerator $breadcrumbs)
   {
       $request = $event->getRequest();
       if ($request->attributes->get('_route') === 'post_show') {
           $breadcrumbs->removeLast();
           $breadcrumbs->addItem('Custom Title', $request->getUri());
       }
   }
   

3. Configuration Overrides: Extend the default config in config/packages/white_october_breadcrumbs.yaml:

   white_october_breadcrumbs:
       default_template: 'custom_breadcrumbs' # Override Twig template
       home_link: '/custom-home-route'       # Custom home link
   

4. Service Decorators: Decorate BreadcrumbsGenerator to add pre/post-processing:

   services:
       app.breadcrumbs.decorator:
           decorates: white_october_breadcrumbs
           arguments: ['@app.breadcrumbs.decorator.inner']