Breadcrumb Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require asprega/breadcrumb-bundle
   

   Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       AndreaSprega\Bundle\BreadcrumbBundle\AndreaSpregaBreadcrumbBundle::class => ['all' => true],
   ];
   

2. First Use Case: In a controller, dynamically add breadcrumbs via code:

   public function showAction($id)
   {
       $builder = $this->get('asprega.breadcrumb.builder');
       $builder->addItem('Home', 'home');
       $builder->addItem('Posts', 'posts_list');
       $builder->addItem('Post #$id', 'post_show', ['id' => $id]);
   }
   

   Render in Twig:

   {{ render(controller('AndreaSpregaBreadcrumbBundle:Breadcrumb:breadcrumb')) }}
   

Where to Look First

• Documentation: Focus on the README for core usage.
• Annotations: Check @Breadcrumb for declarative configuration.
• Twig Integration: Use asprega_breadcrumb() in templates.

Implementation Patterns

Usage Patterns

1. Controller-Based Breadcrumb Building:

   $builder->addItem(
       'Dynamic Label', // Supports `$var.path` syntax
       'route_name',    // Optional route for clickability
       ['param' => 'value'], // Dynamic params via `$var.path`
       'translation_domain' // Optional translation domain
   );
   

2. Annotation-Based (Recommended for CRUD):

   /**
    * @Breadcrumb({
    *   {"label" = "home", "route" = "home"},
    *   {"label" = "$entity.title", "route" = "entity_show", "params" = {"id" = "$entity.id"}}
    * })
    */
   public function showAction(Entity $entity) { ... }
   

3. Dynamic Route Parameters: Leverage the current request’s URL parameters to avoid hardcoding:

   // For URL `/posts/123/comments/456`, omit params if they exist in the request.
   $builder->addItem('Post', 'post_show'); // Uses `id=123` from URL.
   

Workflows

• Global Breadcrumb (Base Template): Define breadcrumbs at the controller class level (applies to all actions).
• Action-Specific Overrides: Use method-level @Breadcrumb to override class-level items.
• Template Customization: Extend breadcrumb.html.twig (located in vendor/asprega/breadcrumb-bundle/Resources/views/) for UI changes.

Integration Tips

• Symfony Forms: Pass entity data to templates for dynamic labels:

  {% set breadcrumbItems = breadcrumbItems|merge([{'label': entity.title}]) %}
  

• Event Listeners: Modify breadcrumbs post-request via kernel.response events.
• Translation: Use translationDomain to isolate translation keys (e.g., admin domain).

Gotchas and Tips

Pitfalls

1. Annotation Parsing:

   • Issue: Annotations may not load if doctrine/annotations is missing or misconfigured.
   • Fix: Ensure doctrine/annotations is installed and cached:

     php bin/console cache:clear
     

2. Dynamic Variables:

   • Issue: $var.path syntax fails if $var is not passed to the template.
   • Fix: Explicitly pass variables to Twig:

     return $this->render('template.html.twig', ['entity' => $entity]);
     

3. Route Parameter Conflicts:

   • Issue: Hardcoding route params may override URL params.
   • Fix: Omit params if they exist in the current request (see README example).

4. Symfony 5+ Twig Namespacing:

   • Issue: Twig template paths may break if not namespaced.
   • Fix: Use fully qualified paths in config/packages/asprega_breadcrumb.yaml:

     asprega_breadcrumb:
         template: AppBundle::breadcrumb.html.twig
     

Debugging

• Check Builder State:

  dump($this->get('asprega.breadcrumb.builder')->getItems());
  

• Validate Annotations: Run php bin/console debug:container --tag="asprega.breadcrumb" to verify annotation parsing.

Extension Points

1. Custom Item Types: Extend the BreadcrumbItem class to add metadata (e.g., icons, classes):

   class CustomBreadcrumbItem extends BreadcrumbItem {
       public $icon;
   }
   

   Override the builder to handle the new type.

2. Translation Overrides: Use translationDomain: false for non-translatable labels:

   $builder->addItem('Static Text', null, [], false);
   

3. Template Inheritance: Override breadcrumb.html.twig to support:

   • ARIA labels (aria-label).
   • Custom separators (e.g., icons instead of >).

Config Quirks

• Symfony 5.2+: Ensure symfony/translation-contracts is v2.x for compatibility.
• Caching: Clear cache after adding/removing annotations:

  php bin/console cache:pool:clear cache_annotations
  

Pro Tips

• Reusable Breadcrumb Logic: Create a base controller with shared breadcrumb setup:

  abstract class BaseController extends Controller {
      protected function initBreadcrumb() {
          $this->get('asprega.breadcrumb.builder')->addItem('Home', 'home');
      }
  }
  

• Testing: Mock the breadcrumb builder in PHPUnit:

  $builder = $this->createMock(BreadcrumbBuilder::class);
  $builder->method('getItems')->willReturn([...]);
  $this->container->set('asprega.breadcrumb.builder', $builder);