Breadcrumbs Laravel Package

## Getting Started

### **Minimal Setup**
1. **Installation**
   ```bash
   composer require tabuna/breadcrumbs:^5.0

Publish the config (optional):

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

2. Basic Usage (Updated for 5.0) Define a breadcrumb trail using named parameter resolution in a controller or service:

   use Tabuna\Breadcrumbs\Trail;
   use Tabuna\Breadcrumbs\BreadcrumbsGenerator;
   
   public function show(Post $post, BreadcrumbsGenerator $breadcrumbs)
   {
       $breadcrumbs->push('Home', route('home'));
       $breadcrumbs->push('Blog', route('posts.index'));
       $breadcrumbs->push($post->title, route('posts.show', $post));
   }
   

   Alternative (Closure Syntax):

   $breadcrumbs->breadcrumbs(fn (Trail $trail, Post $post) =>
       $trail->push($post->title, route('posts.show', $post->id))
   );
   

3. Display in Blade

   @include('breadcrumbs::breadcrumbs')
   

   Or manually:

   <div class="breadcrumbs">
       {!! $breadcrumbs->render() !!}
   </div>
   

First Use Case: Dynamic Trail for a Resource (Updated)

// app/Http/Controllers/ProductController.php
public function show(Product $product, BreadcrumbsGenerator $breadcrumbs)
{
    $breadcrumbs->parent('products.index'); // Reuse existing trail
    $breadcrumbs->push($product->name, route('products.show', $product));
}

Blade:

@breadcrumbs(['Home', 'Products', 'Product Name'])

Implementation Patterns

1. Trail Organization (Updated for 5.0)

• Group Trails by Route/Controller (Closure-Based) Use named parameter resolution in closures:

  // app/Breadcrumbs/ProductTrail.php
  namespace App\Breadcrumbs;
  
  use Tabuna\Breadcrumbs\Trail;
  
  class ProductTrail
  {
      public function __invoke(Trail $trail, Product $product)
      {
          $trail->parent('products.index');
          $trail->push($product->name, route('products.show', $product));
      }
  }
  

  Usage:

  $breadcrumbs->breadcrumbs(ProductTrail::class);
  

• Reuse Trails with parent()

  $breadcrumbs->parent('products.index');
  $breadcrumbs->push('Edit', route('products.edit', $product));
  

2. Dynamic Data Binding (Updated)

• Pass Models/Variables (Named Resolution)

  $breadcrumbs->breadcrumbs(fn (Trail $trail, User $user) =>
      $trail->push('User Posts', route('users.posts', $user))
  );
  

  Blade (with @breadcrumbs directive):

  @breadcrumbs(['Home', 'Users', 'John Doe\'s Posts'])
  

• Localization

  $breadcrumbs->push(__('Products'), route('products.index'));
  

3. Integration with Laravel Features (Updated)

• Middleware for Global Trails (5.0 Compatible)

  // app/Http/Middleware/SetBreadcrumbs.php
  public function handle($request, Closure $next)
  {
      $breadcrumbs = app(BreadcrumbsGenerator::class);
      $breadcrumbs->breadcrumbs(fn (Trail $trail) =>
          $trail->push('Home', route('home'))
      );
      return $next($request);
  }
  

• API Responses (Updated)

  return response()->json([
      'data' => $product,
      'breadcrumbs' => $breadcrumbs->getTrail()->toArray(),
  ]);
  

4. Custom Rendering (Unchanged)

• Override Default View

  php artisan vendor:publish --tag=breadcrumbs-views
  

  Modify resources/views/vendor/breadcrumbs/breadcrumbs.blade.php.

• Custom Separator/Styling

  $breadcrumbs->setSeparator('<span class="divider">/</span>');
  $breadcrumbs->setWrapperTag('nav', ['aria-label' => 'Breadcrumb']);
  

Gotchas and Tips

Common Pitfalls (Updated for 5.0)

1. Trail Not Rendering

   • Cause: Forgetting to include @include('breadcrumbs::breadcrumbs') or manually rendering $breadcrumbs->render().
   • Fix: Verify the trail is built before rendering (e.g., in a controller, not a service called too early).
   • 5.0 Note: Ensure closures use Trail parameter explicitly (e.g., fn (Trail $trail) => ...).

2. Duplicate Trails

   • Cause: Calling $breadcrumbs->push() without clearing or using parent().
   • Fix: Use $breadcrumbs->clear() or $breadcrumbs->parent('trail.name') to reset.

3. Route Not Found

   • Cause: Using route() with undefined named routes.
   • Fix: Double-check route names or use URL helpers (url()->route()).

4. Closure Parameter Mismatch (5.0)

   • Cause: Named parameters in closures must match the Trail class signature.
   • Fix: Use fn (Trail $trail, Model $model) => ... for consistency.

Debugging Tips (Updated)

• Inspect the Trail

  dd($breadcrumbs->getTrail()->toArray());
  

• Check for Middleware Conflicts Ensure breadcrumb middleware runs after route resolution (e.g., web middleware group).
• Validate Closure Parameters

  $breadcrumbs->breadcrumbs(fn (Trail $trail, Post $post) => ...);
  

  Error: If $post is missing, Laravel will throw a BindingResolutionException.

Configuration Quirks (Updated)

1. Default Separator Override in config/breadcrumbs.php:

   'separator' => '»',
   

2. Trail Naming Use kebab-case for trail names (e.g., products.index) to avoid conflicts.

3. Caching Disable caching if trails are dynamic:

   $breadcrumbs->disableCache();
   

4. Closure-Based Trails (5.0)

   • Encapsulation: Trail::call() is now private; use closures for custom logic.
   • Fluent Chaining: $breadcrumbs->breadcrumbs(...) returns the generator for chaining.

Extension Points (Updated for 5.0)

1. Custom Trail Providers (Closure-Based)

   // app/Providers/BreadcrumbsServiceProvider.php
   public function boot()
   {
       Breadcrumbs::provider(function (BreadcrumbsGenerator $breadcrumbs) {
           $breadcrumbs->breadcrumbs(fn (Trail $trail) =>
               $trail->push('Global Trail', route('home'))
           );
       });
   }
   

2. Event-Based Trails (Updated) Trigger trails via events (e.g., ModelRetrieved):

   event(new ModelRetrieved($product));
   // In listener:
   $breadcrumbs->breadcrumbs(fn (Trail $trail, Product $product) =>
       $trail->push($product->name, route('products.show', $product))
   );
   

3. Third-Party Integration (Unchanged)

   • Laravel Nova: Use breadcrumbs::breadcrumbs in toolbars.
   • Livewire: Pass the trail to components:

     public $breadcrumbs;
     protected $listeners = ['updateBreadcrumbs'];
     

Performance Considerations (Updated)

• Avoid Heavy Logic in Closures Keep trail-building logic lightweight (e.g., avoid EAV queries).
• Cache Static Trails Use cache()->remember() for trails that rarely change:

  $trail = cache()->remember("breadcrumbs.home", now()->addHours(1), function () {
      return Trail::create('Home')->push('Home', route('home'));
  });
  

• 5.0 Optimization: Named parameter resolution reduces overhead in closures.

Breaking Changes (5.0)

1. Trail::call() is Private Direct calls to Trail::call() will fail. Use closures instead:

   // Old (deprecated):
   $trail->call(ProductTrail::class, $product);
   
   // New (5.0):
   $breadcrumbs->breadcrumbs(ProductTrail::class);
   

2. Generator Class Renamed `