Laravel Breadcrumbs Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require diglactic/laravel-breadcrumbs
   

2. Define breadcrumbs in routes/breadcrumbs.php:

   Breadcrumbs::for('home', fn($trail) => $trail->push('Home', route('home')));
   

3. Render in Blade:

   {{ Breadcrumbs::render('home') }}
   

4. Publish config (optional) to customize the view template:

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

First Use Case

Create a simple blog hierarchy:

// routes/breadcrumbs.php
Breadcrumbs::for('blog.index', fn($trail) =>
    $trail->parent('home')->push('Blog', route('blog.index'))
);

Breadcrumbs::for('posts.show', fn($trail, $post) =>
    $trail->parent('blog.index')->push($post->title, route('posts.show', $post))
);

Render in resources/views/posts/show.blade.php:

{{ Breadcrumbs::render('posts.show', $post) }}

Implementation Patterns

1. Hierarchical Navigation

Use parent() to chain breadcrumbs logically:

Breadcrumbs::for('products.category', fn($trail, $category) =>
    $trail
        ->parent('products.index')
        ->push($category->name, route('products.category', $category))
);

2. Dynamic Data Binding

Pass Eloquent models or arrays to closures:

Breadcrumbs::for('users.profile', fn($trail, User $user) =>
    $trail->parent('users.index')->push($user->name, route('users.profile', $user))
);

3. Route-Bound Integration

Align breadcrumb names with route names to auto-resolve:

// routes/web.php
Route::name('dashboard.analytics')->get('/analytics', ...);

// routes/breadcrumbs.php
Breadcrumbs::for('dashboard.analytics', fn($trail) =>
    $trail->parent('dashboard.index')->push('Analytics')
);

4. Custom Data for SEO

Extend breadcrumbs with structured data:

$trail->push('Product', route('products.show', $product), [
    'image' => $product->image_url,
    'description' => $product->meta_description
]);

5. View Composition

Combine with other packages (e.g., Tailwind CSS):

<div class="text-sm text-gray-500">
    {{ Breadcrumbs::render('posts.show', $post) }}
</div>

6. Conditional Logic

Handle edge cases (e.g., root-level pages):

Breadcrumbs::for('home', fn($trail) =>
    $trail->push('Home', route('home'))
);

Breadcrumbs::for('root.page', fn($trail) =>
    $trail->parent('home')->push('Root Page')
);

Gotchas and Tips

Pitfalls

1. Missing Route Names:

   • Ensure all referenced routes have names (e.g., Route::name('route.name')).
   • Fix: Use route() helper with fallback URLs:

     $trail->push('Page', route('page') ?? '#');
     

2. Circular Dependencies:

   • Avoid recursive parent() calls without termination.
   • Fix: Use if checks or base cases:

     if ($category->parent_id) {
         $trail->parent('category', $category->parent);
     }
     

3. View Template Overrides:

   • Custom views must match the config key exactly (e.g., 'view' => 'partials.breadcrumbs').
   • Fix: Verify the view path in config/breadcrumbs.php.

4. Structured Data Conflicts:

   • JSON-LD may conflict with URL trimming (e.g., Laravel Page Speed).
   • Fix: Exclude breadcrumbs from trimming or use Microdata instead.

Debugging Tips

• Inspect the Trail: Use Breadcrumbs::generate() to debug the collection:

  dd(Breadcrumbs::generate('posts.show', $post));
  

• Check for Typos: Ensure breadcrumb names in render() match those in for().
• Clear Cached Views: If changes don’t reflect, clear Blade cache:

  php artisan view:clear
  

Extension Points

1. Custom Views: Publish and modify templates:

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

   Edit resources/views/vendor/breadcrumbs/bootstrap5.blade.php.

2. Dynamic Parents: Use closures for dynamic parent resolution:

   $trail->parent(fn($trail) => $trail->push('Dynamic Parent', '#'));
   

3. Middleware Integration: Set default breadcrumbs via middleware:

   public function handle($request, Closure $next) {
       Breadcrumbs::for('default', fn($trail) => $trail->push('Default', route('home')));
       return $next($request);
   }
   

4. Localization: Use Laravel’s translation system for titles:

   $trail->push(__('Home'), route('home'));
   

Performance

• Avoid Heavy Logic: Keep breadcrumb closures lightweight (e.g., avoid complex queries).
• Cache Static Trails: For static pages, predefine trails outside closures if possible.

Config Quirks

• View Paths: Use dot notation for nested views (e.g., 'view' => 'partials.breadcrumbs').
• Structured Data: JSON-LD requires <script type="application/ld+json"> in the <head>.