Breadcrumbs Bundle Laravel Package

Getting Started

Minimal Setup

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

   composer require art/breadcrumbs-bundle
   

   Enable it in app/AppKernel.php:

   new Art\BreadcrumbsBundle\ArtBreadcrumbsBundle(),
   

2. Configuration Define breadcrumbs in Resources/config/breadcrumbs.yml:

   breadcrumbs:
       home:
           uri: /
           name: Home
       products:
           uri: /products
           name: Products
           parent: home
   

3. First Use Case Render breadcrumbs in a Twig template:

   {{ render(controller('ArtBreadcrumbsBundle:Breadcrumbs:default')) }}
   

   Or fetch them programmatically:

   $breadcrumbs = $this->get('art_breadcrumbs')->getBreadcrumbs();
   

Implementation Patterns

YAML-Based Configuration

• Hierarchical Structure: Define breadcrumbs as a tree in breadcrumbs.yml with parent keys.

  admin:
      uri: /admin
      name: Admin
      parent: home
  

• Dynamic Routes: Use placeholders for dynamic segments:

  product:
      uri: /products/{id}
      name: Product {name}
      parent: products
  

  Pass values via Twig:

  {% set breadcrumbs = render(controller('ArtBreadcrumbsBundle:Breadcrumbs:default', {'id': product.id, 'name': product.name})) %}
  

Twig Integration

• Default Template: Override the default Twig template (Resources/views/Breadcrumbs/default.html.twig) to customize rendering.
• Partial Rendering: Use art_breadcrumbs service to fetch specific paths:

  {% for crumb in art_breadcrumbs.getBreadcrumbs() %}
      {{ crumb.name }} {% if not loop.last %} > {% endif %}
  {% endfor %}
  

Programmatic Control

• Service Injection: Inject Art\BreadcrumbsBundle\Service\BreadcrumbsService to manipulate breadcrumbs dynamically:

  $breadcrumbs = $this->get('art_breadcrumbs');
  $breadcrumbs->add('custom', ['uri' => '/custom', 'name' => 'Custom']);
  

• Contextual Breadcrumbs: Use events (e.g., kernel.request) to modify breadcrumbs based on route parameters:

  $event->getRequest()->attributes->set('breadcrumbs', ['custom' => ['uri' => '/custom', 'name' => 'Custom']]);
  

Routing Integration

• Route-Based Triggers: Extend the bundle to auto-generate breadcrumbs from routes (e.g., using symfony/routing):

  $router = $this->get('router');
  $route = $router->getRouteCollection()->get('product_show');
  $params = $route->getRequirements();
  

Gotchas and Tips

Configuration Quirks

• YAML Syntax: Ensure proper indentation and quotes in breadcrumbs.yml (YAML is strict about spacing).
• Circular References: Avoid defining breadcrumbs where A is a parent of B, and B is a parent of A—this causes infinite loops.
• Dynamic Placeholders: Use {param} syntax in uri and name fields, but validate that all placeholders are passed during rendering.

Debugging

• Missing Crumbs: If breadcrumbs don’t render, check:
  • The breadcrumbs.yml file exists and is valid.
  • The bundle is enabled in AppKernel.php.
  • No typos in the Twig template or service calls.
• Route Mismatches: Verify uri paths in YAML match actual routes (e.g., /products/{id} vs. /products/show/{id}).

Extension Points

• Custom Providers: Override the default BreadcrumbsService to fetch breadcrumbs from a database or API:

  class CustomBreadcrumbsService extends \Art\BreadcrumbsBundle\Service\BreadcrumbsService {
      public function getBreadcrumbs() {
          // Custom logic here
      }
  }
  

  Register it as a service in services.yml:

  services:
      art_breadcrumbs:
          class: AppBundle\Service\CustomBreadcrumbsService
          arguments: [...]
  

• Event Listeners: Listen for art_breadcrumbs.build events to modify the breadcrumb tree dynamically:

  $dispatcher->addListener('art_breadcrumbs.build', function($event) {
      $event->setBreadcrumbs(array_merge($event->getBreadcrumbs(), ['dynamic' => [...]]));
  });
  

Performance

• Caching: Cache the breadcrumb tree if it’s static (e.g., using Symfony’s cache system):

  $cache = $this->get('cache');
  $breadcrumbs = $cache->get('breadcrumbs', function() {
      return $this->get('art_breadcrumbs')->getBreadcrumbs();
  });
  

Legacy Notes

• Symfony 2.3 Only: This bundle is tied to Symfony 2.3. For newer versions, consider alternatives like WhiteOctober/BreadcrumbsBundle or custom solutions.
• No Active Maintenance: Last release was in 2013. Test thoroughly in your environment, and be prepared to fork if issues arise.