Breadcrumbtrail Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require airria/breadcrumbtrail-bundle
   

   Add to config/bundles.php:

   Airria\APYBreadcrumbTrailBundle\APYBreadcrumbTrailBundle::class => ['all' => true],
   

2. Enable in config/packages/apy_breadcrumb_trail.yaml

   apy_breadcrumb_trail:
       enabled: true
       # Optional: Default options
       default_options:
           separator: '›'
           first_item: true
   

3. First Use Case: Annotated Controller

   use Airria\APYBreadcrumbTrailBundle\Annotation\Breadcrumb;
   
   class ProductController extends AbstractController
   {
       #[Breadcrumb('Home', route: 'homepage')]
       #[Breadcrumb('Products', route: 'product_index')]
       public function show(Product $product): Response
       {
           return $this->render('product/show.html.twig', ['product' => $product]);
       }
   }
   

4. Render in Twig

   {{ render(apy_breadcrumb_trail()) }}
   

Implementation Patterns

1. Attribute-Based Breadcrumb Generation (PHP 8+)

use Airria\APYBreadcrumbTrailBundle\Attribute\Breadcrumb;

#[Breadcrumb('Dashboard', route: 'dashboard')]
#[Breadcrumb('Projects', route: 'project_index')]
public function index(): Response
{
    return $this->render('project/index.html.twig');
}

2. Dynamic Breadcrumbs via Methods

public function show(Product $product): Response
{
    $this->breadcrumbTrail()
        ->add('Home', 'homepage')
        ->add('Products', 'product_index')
        ->add($product->name, 'product_show', ['id' => $product->id]);

    return $this->render('product/show.html.twig');
}

3. Overriding Defaults in Twig

{{ render(apy_breadcrumb_trail({
    'separator': ' » ',
    'first_item': false,
    'exclude_current': true
})) }}

4. Integration with Symfony Events

// src/EventListener/BreadcrumbListener.php
public function onKernelRequest(RequestEvent $event): void
{
    if (!$event->isMainRequest()) {
        return;
    }

    $trail = $event->getRequest()->attributes->get('breadcrumb_trail');
    if ($trail) {
        $this->breadcrumbTrail()->merge($trail);
    }
}

5. Customizing Trail Rendering

Extend the default Twig extension:

// src/Twig/BreadcrumbExtension.php
class CustomBreadcrumbExtension extends \Airria\APYBreadcrumbTrailBundle\Twig\BreadcrumbExtension
{
    public function getBreadcrumbTrailHtml(array $options = []): string
    {
        // Custom logic (e.g., add icons, modify classes)
        return parent::getBreadcrumbTrailHtml($options);
    }
}

Register as a service and tag it to replace the default.

Gotchas and Tips

Pitfalls

1. Annotation vs. Attribute Conflicts

   • If using both annotations (@Breadcrumb) and attributes (#[Breadcrumb]), the last defined takes precedence.
   • Fix: Stick to one method per project.

2. Route Generation Failures

   • If a route fails to generate (e.g., missing parameters), the breadcrumb will break silently.
   • Fix: Use routeParameters in the attribute:

     #[Breadcrumb('Edit', route: 'product_edit', routeParameters: ['id' => $product->id])]
     

3. Caching Issues

   • Breadcrumbs are resolved per-request. If using HTTP caching, ensure the trail isn’t cached statically.
   • Fix: Exclude breadcrumb-related routes from cache headers.

4. Twig Auto-escaping

   • Breadcrumbs are escaped by default. If you need raw HTML (e.g., for icons), use |raw:

     {{ render(apy_breadcrumb_trail())|raw }}
     

Debugging Tips

• Dump the Trail:

  {{ dump(apy_breadcrumb_trail().getItems()) }}
  

• Check Route Existence: Use Symfony’s router service to verify routes:

  $this->container->get('router')->generate('product_index');
  

• Enable Dev Mode: Set APY_BREADCRUMB_TRAIL_DEBUG=true in .env to log unresolved routes.

Extension Points

1. Custom Trail Providers Implement BreadcrumbTrailProviderInterface to fetch breadcrumbs from a database or API.

2. Modify Trail Items Use the BreadcrumbTrailEvent (dispatches after generation):

   $eventDispatcher->addListener(BreadcrumbTrailEvents::POST_BUILD, function (BreadcrumbTrailEvent $event) {
       $event->getTrail()->add('Custom Item', '#');
   });
   

3. Override Twig Rendering Replace the default Twig extension by binding your own service with the apy_breadcrumb_trail.twig.extension tag.

4. Localization Support Use Symfony’s translation system with the translation_domain option:

   #[Breadcrumb('Products', route: 'product_index', translationDomain: 'messages')]