Breadcrumb Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awaresoft/breadcrumb-bundle
   

   Ensure your project uses Symfony 4.4+ and includes knplabs/knp-menu-bundle and sonata-project/block-bundle.

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Awaresoft\BreadcrumbBundle\AwaresoftBreadcrumbBundle::class => ['all' => true],
   ];
   

3. Configure Routes: Add the bundle’s routes in config/routes.yaml:

   awaresoft_breadcrumb:
       resource: "@AwaresoftBreadcrumbBundle/Resources/config/routing.yml"
   

4. First Use Case: Generate breadcrumbs in a controller:

   use Awaresoft\BreadcrumbBundle\Breadcrumb\Breadcrumb;
   
   public function indexAction()
   {
       $breadcrumb = new Breadcrumb();
       $breadcrumb->add('Home', '/');
       $breadcrumb->add('Products', '/products');
       $breadcrumb->add('Current Page', null);
   
       return $this->render('template.html.twig', [
           'breadcrumb' => $breadcrumb,
       ]);
   }
   

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

   {{ breadcrumb(breadcrumb) }}
   

Implementation Patterns

Core Workflows

1. Dynamic Breadcrumb Generation: Extend the Breadcrumb class to create reusable logic:

   class ProductBreadcrumb extends Breadcrumb
   {
       public function generate(int $id)
       {
           $this->add('Home', '/');
           $this->add('Products', '/products');
           $this->add('Product #'.$id, '/products/'.$id);
       }
   }
   

2. Integration with KnpMenu: Combine with knp-menu-bundle for hierarchical navigation:

   {{ knp_menu_render(menu, { 'breadcrumbs': true }) }}
   

3. Sonata Block Integration: Add breadcrumbs as a Sonata block in config/packages/sonata_block.yaml:

   sonata_block:
       blocks:
           sonata.admin.block.breadcrumb: ~
   

4. Event-Driven Updates: Use Symfony events to update breadcrumbs dynamically (e.g., after login):

   // In a listener
   $breadcrumb->clear();
   $breadcrumb->add('Dashboard', '/dashboard');
   

Best Practices

• Reuse Logic: Create services for complex breadcrumb generation.
• Cache Breadcrumbs: Use Symfony’s cache system for static breadcrumbs.
• Localization: Pass translated labels to add() for multilingual support.

Gotchas and Tips

Common Pitfalls

1. Symlink Issues:

   • If modifying the vendor, ensure /src/Awaresoft is symlinked correctly.
   • Clear cache after manual changes:

     php bin/console cache:clear
     

2. Route Conflicts:

   • The bundle’s routes may clash with existing ones. Prefix routes in routing.yml if needed:

     awaresoft_breadcrumb:
         resource: "@AwaresoftBreadcrumbBundle/Resources/config/routing.yml"
         prefix: /awaresoft
     

3. Twig Extension Missing:

   • Ensure the Twig extension is registered. If not, manually add it in config/packages/twig.yaml:

     twig:
         globals:
             breadcrumb: '@awaresoft_breadcrumb.twig.breadcrumb'
     

4. Backward Compatibility:

   • Avoid breaking changes. Test with composer update before pushing updates.

Debugging Tips

• Check Breadcrumb Content: Dump the breadcrumb object in Twig to verify structure:

  {{ dump(breadcrumb) }}
  

• Enable Debug Mode: Set APP_DEBUG=true in .env to log breadcrumb-related errors.

Extension Points

1. Custom Renderers: Override the Twig renderer by creating a new service tagged as awaresoft_breadcrumb.renderer:

   services:
       app.custom_breadcrumb_renderer:
           class: App\Renderer\CustomBreadcrumbRenderer
           tags: ['awaresoft_breadcrumb.renderer']
   

2. Database Backing: Store breadcrumbs in a database by extending BreadcrumbProviderInterface and binding it in services.yaml:

   services:
       app.db_breadcrumb_provider:
           class: App\Provider\DbBreadcrumbProvider
           arguments: ['@doctrine.orm.entity_manager']
           tags: ['awaresoft_breadcrumb.provider']
   

3. AJAX Updates: Use Symfony’s Response to update breadcrumbs via AJAX:

   return new Response($this->renderView('breadcrumb/_partial.html.twig', ['breadcrumb' => $breadcrumb]));