Breadcrumb Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require digitalrespawn/breadcrumb-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       DigitalRespawn\BreadcrumbBundle\DigitalRespawnBreadcrumbBundle::class => ['all' => true],
   ];
   

3. Publish Configuration (optional):

   php artisan vendor:publish --provider="DigitalRespawn\BreadcrumbBundle\DigitalRespawnBreadcrumbBundle" --tag="config"
   

   This creates config/breadcrumb.php with default settings.

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

   // Controller
   $this->get('breadcrumbs')->add('Home', $this->generateUrl('homepage'));
   $this->get('breadcrumbs')->add('Products', $this->generateUrl('product_index'));
   

   Or in Twig:

   {{ breadcrumbs() }}
   

Implementation Patterns

Controller Integration

1. Dynamic Breadcrumbs: Use the Breadcrumbs service in controllers to dynamically set breadcrumbs based on route parameters:

   $productId = $request->get('id');
   $this->get('breadcrumbs')
       ->add('Home', $this->generateUrl('homepage'))
       ->add('Products', $this->generateUrl('product_index'))
       ->add('Product #'.$productId, $this->generateUrl('product_show', ['id' => $productId]));
   

2. Route-Based Generation: Leverage Symfony’s ParamConverter to auto-generate breadcrumbs from route annotations (if using Symfony 2.x-style annotations):

   # services.yml
   services:
       app.breadcrumb.listener:
           class: AppBundle\EventListener\BreadcrumbListener
           tags:
               - { name: kernel.event_listener, event: kernel.controller, method: onKernelController }
   

Twig Integration

1. Display Breadcrumbs: Use the breadcrumbs() Twig function to render the trail:

   {% if breadcrumbs %}
       <nav class="breadcrumb">
           <ul>
               {% for breadcrumb in breadcrumbs %}
                   <li>
                       {% if loop.first %}
                           <a href="{{ breadcrumb.url }}">{{ breadcrumb.title }}</a>
                       {% else %}
                           <span>{{ breadcrumb.title }}</span>
                       {% endif %}
                   </li>
               {% endfor %}
           </ul>
       </nav>
   {% endif %}
   

2. Customize Output: Override the default Twig function by extending the bundle’s template:

   {% extends 'DigitalRespawnBreadcrumbBundle::breadcrumbs.html.twig' %}
   {% block breadcrumb_item %}
       <li class="breadcrumb-item">{{ breadcrumb.title }}</li>
   {% endblock %}
   

Event-Driven Workflows

1. Kernel Events: Listen to kernel.controller to set breadcrumbs globally:

   public function onKernelController(GetResponseForControllerEvent $event)
   {
       $controller = $event->getController();
       if (is_array($controller)) {
           $object = $controller[0];
           if (method_exists($object, 'setBreadcrumbs')) {
               $object->setBreadcrumbs($this->get('breadcrumbs'));
           }
       }
   }
   

2. Route Matching: Use the Breadcrumbs service in route matchers or middleware to pre-populate breadcrumbs:

   $breadcrumbs = $this->get('breadcrumbs');
   $breadcrumbs->add('Category', $this->generateUrl('category_show', ['slug' => $slug]));
   

Gotchas and Tips

Common Pitfalls

1. Route Generation Failures:

   • If generateUrl() throws exceptions (e.g., route not found), wrap calls in a try-catch:

     try {
         $url = $this->generateUrl('route_name', $params);
     } catch (\Exception $e) {
         $url = '#'; // Fallback or handle gracefully
     }
     

   • Ensure routes are properly defined in routing.yml or routes.php.

2. Duplicate Entries:

   • Clear breadcrumbs at the start of a controller action to avoid duplicates:

     $this->get('breadcrumbs')->clear();
     

3. Twig Function Not Found:

   • If breadcrumbs() fails in Twig, verify the bundle is enabled and the Twig extension is loaded. Check config/bundles.php and app/AppKernel.php.

Debugging Tips

1. Inspect Breadcrumbs: Dump the breadcrumb trail in a controller to verify content:

   dump($this->get('breadcrumbs')->get());
   

2. Check Configuration: Validate config/breadcrumb.php settings, especially:

   • enable_errors: Set to true during development to catch issues early.
   • default_separator: Ensure it matches your UI (e.g., > or /).

3. ParamConverter Issues:

   • If using annotations, ensure your controller extends Symfony\Component\HttpKernel\Controller\Controller and annotations are parsed correctly. For Laravel (Symfony-based), this may require additional setup.

Extension Points

1. Custom Providers: Extend the bundle by creating a custom breadcrumb provider:

   class CustomBreadcrumbProvider implements BreadcrumbProviderInterface
   {
       public function getBreadcrumbs()
       {
           return [
               new Breadcrumb('Custom', $this->generateUrl('custom_route')),
           ];
       }
   }
   

   Register it in services.yml:

   services:
       app.custom_breadcrumb_provider:
           class: AppBundle\Service\CustomBreadcrumbProvider
           tags:
               - { name: breadcrumb.provider }
   

2. Override Templates: Copy vendor/digitalrespawn/breadcrumb-bundle/Resources/views/breadcrumbs.html.twig to Resources/views/DigitalRespawnBreadcrumbBundle/breadcrumbs.html.twig to customize rendering.

3. Laravel-Specific Workarounds:

   • Since this bundle is Symfony 2.x-focused, in Laravel, manually bind the service in AppServiceProvider:

     public function register()
     {
         $this->app->singleton('breadcrumbs', function ($app) {
             return new \DigitalRespawn\BreadcrumbBundle\Service\BreadcrumbsService(
                 $app['router'],
                 $app['twig'],
                 $app['config']['breadcrumb']
             );
         });
     }
     

   • Use Laravel’s route helpers (e.g., route('name')) instead of Symfony’s generateUrl().

4. Avoid Deprecation Warnings:

   • The bundle is outdated (last release 2016). For modern Laravel, consider alternatives like:
     • way/generators (for route-based breadcrumbs).
     • Custom logic in middleware or controllers.