Breadcrumbs Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mayeulak/breadcrumbs
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Mayeulak\Breadcrumbs\BreadcrumbsServiceProvider"
   

2. Basic Usage: Add the breadcrumb view to your layout (e.g., resources/views/layouts/app.blade.php):

   @include('breadcrumbs::breadcrumbs')
   

   Generate breadcrumbs in a controller:

   use Mayeulak\Breadcrumbs\BreadcrumbsGenerator;
   
   public function show()
   {
       Breadcrumbs::generate('Home', url('/'));
       Breadcrumbs::generate('Category', route('categories.index'));
       Breadcrumbs::generate('Product', route('products.show', $product));
   }
   

3. First Use Case: Use the BreadcrumbsGenerator facade in a controller to dynamically build breadcrumbs for a product page:

   Breadcrumbs::generate('Home', url('/'));
   Breadcrumbs::generate('Electronics', route('categories.show', ['category' => 'electronics']));
   Breadcrumbs::generate('Laptops', route('subcategories.show', ['subcategory' => 'laptops']));
   Breadcrumbs::generate('Product Name', route('products.show', $product));
   

Implementation Patterns

Common Workflows

1. Dynamic Breadcrumb Generation: Use closures to dynamically generate breadcrumbs based on route parameters:

   Breadcrumbs::generate('Category', route('categories.index'))
       ->parent('Home', url('/'));
   

2. Reusable Breadcrumb Logic: Create a trait or helper class to encapsulate breadcrumb logic for specific routes:

   // app/Traits/Breadcrumbable.php
   trait Breadcrumbable
   {
       public function setBreadcrumbs()
       {
           Breadcrumbs::generate('Home', url('/'));
           Breadcrumbs::generate('Blog', route('blog.index'));
           Breadcrumbs::generate($this->title, route('blog.post', $this));
       }
   }
   

3. Integration with Route Model Binding: Use breadcrumbs in route model binding to ensure consistency:

   public function show(Product $product)
   {
       $this->setBreadcrumbs($product);
       return view('products.show', compact('product'));
   }
   

4. Conditional Breadcrumb Logic: Use conditional checks to customize breadcrumbs:

   if ($product->isFeatured()) {
       Breadcrumbs::generate('Featured', route('products.featured'));
   }
   Breadcrumbs::generate('Product', route('products.show', $product));
   

Integration Tips

• View Composition: Extend the default breadcrumb view (resources/views/breadcrumbs/breadcrumbs.blade.php) to customize styling or behavior.

• Middleware: Use middleware to set default breadcrumbs for specific routes or user roles:

  public function handle($request, Closure $next)
  {
      Breadcrumbs::generate('Dashboard', route('dashboard'));
      return $next($request);
  }
  

• API Integration: Expose breadcrumbs via API for single-page applications (SPAs) by returning breadcrumb data in JSON responses:

  return response()->json([
      'breadcrumbs' => Breadcrumbs::get()
  ]);
  

Gotchas and Tips

Pitfalls

1. Missing Parent Links: Forgetting to set parent links can result in broken breadcrumb hierarchies. Always ensure the parent() method is used where applicable:

   Breadcrumbs::generate('Child', route('child'))
       ->parent('Parent', route('parent'));
   

2. Duplicate Entries: Overwriting breadcrumbs without clearing previous entries can lead to duplicate or incorrect breadcrumbs. Use clear() if needed:

   Breadcrumbs::clear();
   Breadcrumbs::generate('New Root', url('/'));
   

3. Route Caching: If using route caching (php artisan route:cache), ensure breadcrumb routes are not cached incorrectly. Clear cached routes if breadcrumbs break unexpectedly:

   php artisan route:clear
   

4. View Not Found: If the breadcrumb view is not found, verify the view exists at resources/views/breadcrumbs/breadcrumbs.blade.php or check the published views.

Debugging

• Check Generated Breadcrumbs: Use Breadcrumbs::get() to inspect the current breadcrumb trail in a controller or Tinker:

  dd(Breadcrumbs::get());
  

• Clear and Regenerate: If breadcrumbs appear incorrect, clear and regenerate them:

  Breadcrumbs::clear();
  Breadcrumbs::generate('Root', url('/'));
  

Tips

1. Customize the View: Override the default breadcrumb view to match your application’s design:

   <!-- resources/views/breadcrumbs/breadcrumbs.blade.php -->
   <nav aria-label="Breadcrumb">
       <ol class="flex items-center space-x-2">
           @foreach ($breadcrumbs as $breadcrumb)
               <li>
                   <a href="{{ $breadcrumb->url }}" class="text-gray-600 hover:text-gray-900">
                       {{ $breadcrumb->title }}
                   </a>
               </li>
               <li>/</li>
           @endforeach
       </ol>
   </nav>
   

2. Use Route Names: Prefer route names over URLs for better maintainability:

   Breadcrumbs::generate('Home', route('home'));
   

3. Localization: Localize breadcrumb titles by passing translated strings:

   Breadcrumbs::generate(__('Home'), url('/'));
   

4. Testing: Test breadcrumb generation in PHPUnit by mocking the Breadcrumbs facade:

   $this->mock(Breadcrumbs::class)->shouldReceive('get')->andReturn([
       (object) ['title' => 'Home', 'url' => '/'],
       (object) ['title' => 'Products', 'url' => '/products'],
   ]);
   

5. Performance: Avoid generating breadcrumbs in every request if they are static. Cache breadcrumb data where possible:

   $breadcrumbs = Cache::remember('breadcrumbs', now()->addHours(1), function () {
       return Breadcrumbs::get();
   });