Breadcrumbtrail Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require apy/breadcrumbtrail-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       APY\BreadcrumbTrailBundle\APYBreadcrumbTrailBundle::class => ['all' => true],
   ];
   

2. First Use Case: Define breadcrumbs for a controller using PHP Attributes (preferred in Symfony 5.7+):

   use APY\BreadcrumbTrailBundle\Model\BreadcrumbInterface;
   use APY\BreadcrumbTrailBundle\Model\BreadcrumbTrait;
   
   #[APY\BreadcrumbTrailBundle\Model\Breadcrumb]
   class ProductController extends AbstractController
   {
       #[APY\BreadcrumbTrailBundle\Model\Breadcrumb(['Home', 'Products'])]
       public function index(): Response
       {
           return $this->render('product/index.html.twig');
       }
   }
   

3. Render in Twig: Include the breadcrumb trail in your base template (e.g., base.html.twig):

   {{ render(controller('APYBreadcrumbTrailBundle:Breadcrumb:trail')) }}
   

Implementation Patterns

1. Configuration Approaches

PHP Attributes (Recommended for Symfony 5.7+)

• Use #[Breadcrumb] on controllers or methods.
• Supports dynamic titles via closures or method calls:

  #[Breadcrumb(['Home', function() { return 'Dynamic Title'; }])]
  

Annotations (Legacy, Deprecated)

• Use @Breadcrumb (e.g., @Breadcrumb({"Home", "Products"})).
• Deprecation warnings appear in Symfony 5.7+; migrate to attributes.

PHP Methods

• Implement BreadcrumbInterface in controllers:

  use APY\BreadcrumbTrailBundle\Model\BreadcrumbInterface;
  
  class ProductController implements BreadcrumbInterface
  {
      public function getBreadcrumbs(): array
      {
          return ['Home', 'Products'];
      }
  }
  

Twig-Based (Dynamic)

• Use APYBreadcrumbTrailBundle:Breadcrumb:add in Twig:

  {% do breadcrumb.add('Custom', path('some_route')) %}
  

2. Workflow Integration

Reset Trail

• Clear breadcrumbs for a route using #[ResetBreadcrumbTrail]:

  #[ResetBreadcrumbTrail]
  #[Breadcrumb(['Home'])]
  public function resetTrail(): Response { ... }
  

Dynamic Routes

• Pass route parameters dynamically:

  #[Breadcrumb(['Home', function() use ($product) {
      return 'Product: ' . $product->getName();
  }])]
  

Nested Controllers

• Extend parent breadcrumbs:

  #[Breadcrumb(['Home', 'Products', 'Details'])]
  public function show(Product $product): Response { ... }
  

3. Twig Customization

Override Default Template

• Copy templates/breadcrumbs.html.twig from the bundle to your project (e.g., templates/bundles/breadcrumbtrail/).
• Extend with custom logic:

  {# Example: Add icons or active state #}
  <nav class="breadcrumb">
      {% for item in breadcrumbs %}
          <a href="{{ item.link }}">{{ item.title }}</a>
          {% if not loop.last %}<span class="sep">/</span>{% endif %}
      {% endfor %}
  </nav>
  

Access Raw Data

• Pass breadcrumbs to Twig globally in config/services.yaml:

  services:
      App\EventListener\BreadcrumbListener:
          tags:
              - { name: kernel.event_listener, event: kernel.controller, method: onKernelController }
  

  // src/EventListener/BreadcrumbListener.php
  public function onKernelController(ControllerEvent $event): void
  {
      $breadcrumbs = $this->breadcrumbTrailService->getBreadcrumbs();
      $event->getRequest()->attributes->set('breadcrumbs', $breadcrumbs);
  }
  

  {% for item in app.request.attributes.breadcrumbs %}
      {{ item.title }}
  {% endfor %}
  

Gotchas and Tips

1. Common Pitfalls

Deprecation Warnings

• Issue: Using @Breadcrumb in Symfony 5.7+ triggers deprecation notices.
• Fix: Migrate to #[Breadcrumb] attributes. Run:

  composer require symfony/deprecation-contracts
  

Twig Security Errors

• Issue: Older versions (<1.9.2) may fail with Twig security errors.
• Fix: Update the bundle:

  composer update apy/breadcrumbtrail-bundle
  

Dynamic Titles Not Rendering

• Issue: Closures/method calls in breadcrumb titles return empty strings.
• Fix: Ensure the closure is callable (e.g., function() { return 'Title'; }).
  • Debug: Check logs for Uncaught Error: Call to undefined function.

Invokable Controllers

• Issue: Breadcrumb attributes ignored in invokable controllers.
• Fix: Use #[Breadcrumb] on the __invoke() method or implement BreadcrumbInterface.

2. Debugging Tips

Inspect Active Breadcrumbs

• Dump breadcrumbs in a controller:

  use APY\BreadcrumbTrailBundle\Service\BreadcrumbTrailService;
  
  public function debugBreadcrumbs(BreadcrumbTrailService $trail): Response
  {
      dump($trail->getBreadcrumbs());
      return new Response();
  }
  

Clear Cached Trails

• Reset the trail manually in tests or debugging:

  $this->breadcrumbTrailService->reset();
  

Check Route Parameters

• Ensure route parameters are passed correctly:

  #[Breadcrumb(['Home', function() use ($id) {
      return 'Item #' . $id;
  }])]
  

3. Advanced Patterns

Conditional Breadcrumbs

• Use closures to conditionally add items:

  #[Breadcrumb([
      'Home',
      function() {
          return auth()->check() ? 'Dashboard' : 'Login';
      }
  ])]
  

Multi-Language Support

• Translate titles via Symfony’s translator:

  #[Breadcrumb(['Home', $this->translator->trans('breadcrumb.products')])]
  

Custom Link Generators

• Extend the bundle to add custom link logic:

  // src/Service/CustomBreadcrumbLinkGenerator.php
  use APY\BreadcrumbTrailBundle\Generator\LinkGeneratorInterface;
  
  class CustomBreadcrumbLinkGenerator implements LinkGeneratorInterface
  {
      public function generate(array $options): string
      {
          return route('custom_route', $options);
      }
  }
  

  Register in services.yaml:

  services:
      App\Service\CustomBreadcrumbLinkGenerator:
          tags:
              - { name: apy_breadcrumbtrail.link_generator }
  

4. Configuration Quirks

Template Overrides

• Gotcha: Forgetting to clear cache after overriding breadcrumbs.html.twig.
• Fix: Run:

  php bin/console cache:clear
  

PHP 8.1+ Attributes

• Gotcha: Attributes must be imported fully (e.g., #[APY\BreadcrumbTrailBundle\Model\Breadcrumb]).
• Fix: Use absolute imports or add use statements.

Symfony 6+ Compatibility

• Gotcha: Symfony 6 requires explicit #[Route] imports.
• Fix: Ensure routes are defined with full namespace:

  use Symfony\Component\Routing\Annotation\Route;
  

5. Performance Considerations

Avoid Overhead in Loops

• Issue: Adding breadcrumbs in tight loops (e.g., API responses).
• Fix: Use #[ResetBreadcrumbTrail] to clear trails between requests or lazy-load breadcrumbs.

Caching Breadcrumbs

• Tip: Cache breadcrumb data for static routes:

  #[Cache(withContext: false)]
  #[Breadcrumb(['Home', 'Cached Page'])]
  public function cachedPage(): Response { ... }