Breadcrumb Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require thormeier/breadcrumb-bundle
   

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

   Thormeier\BreadcrumbBundle\ThormeierBreadcrumbBundle::class => ['all' => true],
   

2. Basic Configuration Add to config/packages/thormeier_breadcrumb.yaml (Symfony 4+):

   thormeier_breadcrumb: ~
   

3. First Use Case Define breadcrumbs in route annotations (Symfony 3) or YAML (Symfony 4+):

   # config/routes.yaml
   home:
       path: /
       defaults:
           breadcrumb:
               label: Home
   contact:
       path: /contact
       defaults:
           breadcrumb:
               label: Contact
               parent_route: home
   

   Render in Twig:

   {{ render(thormeier_breadcrumb) }}
   

Implementation Patterns

Route-Based Breadcrumb Management

• Hierarchical Structure: Use parent_route to nest breadcrumbs (e.g., parent_route: home for /contact).
• Dynamic Labels: Override labels in controllers via breadcrumb service:

  $this->get('thormeier_breadcrumb')->setLabel('contact', 'Support');
  

• Route Parameters: Inject dynamic values (e.g., {id}) into labels:

  defaults:
      breadcrumb:
          label: 'Post {id}'
  

Twig Integration

• Custom Templates: Override the default template by setting template in config:

  thormeier_breadcrumb:
      template: 'bundles/acme/templates/breadcrumb.html.twig'
  

• Conditional Rendering: Check if breadcrumbs exist:

  {% if thormeier_breadcrumb|length > 0 %}
      {{ render(thormeier_breadcrumb) }}
  {% endif %}
  

Advanced Workflows

• Event-Based Updates: Listen to kernel.request to modify breadcrumbs dynamically:

  $event->getResponse()->headers->set('X-Breadcrumb', 'Custom');
  

• Multi-Language Support: Use route parameters for locale-aware labels:

  defaults:
      breadcrumb:
          label: '{{ _locale|default('en') }} Home'
  

Gotchas and Tips

Common Pitfalls

• Circular References: Avoid parent_route loops (e.g., A → B → A).
• Missing Parent Routes: Ensure parent_route exists in the router.
• Twig Cache: Clear cache after template changes:

  php bin/console cache:clear
  

Debugging

• Check Route Existence: Verify routes with:

  php bin/console debug:router
  

• Inspect Breadcrumb Tree: Dump the service:

  dump($this->get('thormeier_breadcrumb')->getBreadcrumbs());
  

Extension Points

• Custom Providers: Implement BreadcrumbProviderInterface for non-route-based breadcrumbs.
• Override Services: Extend the bundle’s BreadcrumbManager to add logic (e.g., SEO tags):

  services:
      app.breadcrumb.manager:
          class: App\Service\CustomBreadcrumbManager
          decorates: thormeier_breadcrumb.manager
  

Configuration Quirks

• Default Template Path: Located at ThormeierBreadcrumbBundle:Breadcrumb:breadcrumb.html.twig.
• Label Escaping: Labels are auto-escaped; use |raw in Twig if needed.