Bcm Breadcrumbbundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require benoitmariaux/bcm-breadcrumbbundle:dev-master
   

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

   BCM\BreadcrumbBundle\BCMBreadcrumbBundle::class => ['all' => true],
   

2. Configure Routes: Add label (required) and parent (optional) to route defaults in config/routes.yaml:

   homepage:
       path: /
       defaults:
           _controller: App\Controller\DefaultController::home
           label: "Home"
   articles:
       path: /articles
       defaults:
           _controller: App\Controller\ArticleController::list
           label: "Articles"
           parent: homepage
   

3. First Render: Inject the manager in a controller and render breadcrumbs:

   use BCM\BreadcrumbBundle\Manager\BreadcrumbManager;
   
   public function showArticle(Article $article, BreadcrumbManager $breadcrumbManager)
   {
       $breadcrumb = $breadcrumbManager->render([
           'article_title' => $article->getTitle(),
       ]);
       return $this->render('article/show.html.twig', [
           'breadcrumb' => $breadcrumb,
       ]);
   }
   

4. Display in Twig: Use the provided Twig extension in your template:

   {{ breadcrumb() }}
   

Implementation Patterns

Core Workflow

1. Route Configuration:

   • Define breadcrumb hierarchy via parent route references.
   • Use dynamic labels (e.g., {article_title}) for runtime values.

2. Controller Integration:

   • Pass dynamic parameters to render() (e.g., article_title).
   • Cache the rendered breadcrumb in the view layer to avoid redundant logic.

3. Twig Integration:

   • Use {{ breadcrumb() }} for default rendering.
   • Customize appearance via Twig filters/extensions (e.g., breadcrumb_link):

     {% for item in breadcrumb() %}
         {{ item.link }} {{ item.label }}
     {% endfor %}
     

Advanced Patterns

• Dynamic Parent Routes: Override parent routes in render() for context-specific hierarchies:

  $breadcrumbManager->render([], 'custom_parent_route');
  

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

  label: "{_locale}_homepage"
  

  Pass _locale in render():

  $breadcrumbManager->render(['_locale' => $request->getLocale()]);
  

• API-Driven Breadcrumbs: Fetch breadcrumb data via a dedicated endpoint (e.g., /api/breadcrumb) and cache responses.

Integration Tips

• Symfony Flex: Use config/packages/bcm_breadcrumb.yaml for environment-specific configs.
• Event Listeners: Trigger breadcrumb updates post-route resolution (e.g., KernelEvents::CONTROLLER).
• Testing: Mock BreadcrumbManager in PHPUnit:

  $this->breadcrumbManager->expects($this->once())
      ->method('render')
      ->with(['title' => 'Test'])
      ->willReturn($mockedBreadcrumb);
  

Gotchas and Tips

Pitfalls

1. Route Caching:

   • Clear Symfony’s route cache (php bin/console cache:clear) after adding/editing routes.
   • Dynamic routes (e.g., /articles/{id}) must include label in defaults, not requirements.

2. Label Placeholders:

   • Unresolved placeholders (e.g., {missing_param}) render as literal text. Validate inputs:

     $breadcrumbManager->render(['article_title' => $article->getTitle() ?? 'Untitled']);
     

3. Circular References:

   • Avoid parent: self or cyclic dependencies (e.g., A -> B -> A). The bundle throws a RuntimeException.

4. Twig Autoescape:

   • Breadcrumbs may break if labels contain HTML. Use |raw in Twig:

     {{ breadcrumb()[0].label|raw }}
     

Debugging

• Dumping Routes: Check route configurations with:

  php bin/console debug:router | grep "label\|parent"
  

• Manager Methods: Inspect available methods:

  $methods = get_class_methods($breadcrumbManager);
  // ['render', 'getCurrentRoute', 'getParentRoute', ...]
  

• Log Levels: Enable debug mode to log breadcrumb generation:

  # config/packages/dev/bcm_breadcrumb.yaml
  bcm_breadcrumb:
      debug: true
  

Extension Points

1. Custom Renderers: Extend BCM\BreadcrumbBundle\Renderer\RendererInterface for non-Twig outputs (e.g., JSON):

   class JsonRenderer implements RendererInterface {
       public function render(array $items) {
           return json_encode($items);
       }
   }
   

   Register in services.yaml:

   services:
       App\Renderer\JsonRenderer:
           tags: [bcm_breadcrumb.renderer]
   

2. Event Dispatching: Listen for bcm_breadcrumb.build events to modify items:

   use BCM\BreadcrumbBundle\Event\BreadcrumbEvent;
   
   $eventDispatcher->addListener(BreadcrumbEvent::BUILD, function (BreadcrumbEvent $event) {
       $event->addItem('Custom Item', '/custom');
   });
   

3. Configuration Overrides: Override default Twig paths in config/packages/bcm_breadcrumb.yaml:

   bcm_breadcrumb:
       twig:
           template: 'custom_breadcrumb.html.twig'
           extension_class: 'App\Twig\Extension\CustomBreadcrumbExtension'
   

Performance Tips

• Route Compilation: Use cache:warmup in deployment scripts to pre-compile routes.
• Fragment Caching: Cache breadcrumb HTML in Twig:

  {% cache 'breadcrumb_' app.request.get('_route') %}
      {{ breadcrumb() }}
  {% endcache %}