# Laravel Breadcrumbs

Laravel Breadcrumbs is a package that provides a simple, Laravel-style way to create breadcrumb navigation trails in your web application. It allows you to define breadcrumbs for each page using closures that can accept parameters, making it easy to build dynamic breadcrumb trails that reflect your application's navigation hierarchy. The package follows Laravel conventions and integrates seamlessly with Laravel's routing system.

The package supports route model binding, parent-child breadcrumb relationships, custom templates for different CSS frameworks (Bootstrap, Tailwind, Bulma, etc.), and JSON-LD structured data for SEO. It provides a fluent API through the `Breadcrumbs` facade with methods to define, generate, and render breadcrumbs, along with advanced features like before/after callbacks, custom data injection, and runtime view switching.

## API Reference

### Breadcrumbs::for() - Define Breadcrumbs for a Page

Registers a breadcrumb-generating callback for a specific page. The callback receives a `BreadcrumbTrail` instance and optional parameters.

```php
<?php
use Diglactic\Breadcrumbs\Breadcrumbs;
use Diglactic\Breadcrumbs\Generator as BreadcrumbTrail;
use App\Models\Post;

// Simple static breadcrumb
Breadcrumbs::for('home', function (BreadcrumbTrail $trail) {
    $trail->push('Home', route('home'));
});

// Breadcrumb with parent
Breadcrumbs::for('blog', function (BreadcrumbTrail $trail) {
    $trail->parent('home');
    $trail->push('Blog', route('blog'));
});

// Dynamic breadcrumb with parameter
Breadcrumbs::for('post', function (BreadcrumbTrail $trail, Post $post) {
    $trail->parent('blog');
    $trail->push($post->title, route('post', $post));
});

// Arrow function syntax (PHP 7.4+)
Breadcrumbs::for(
    'category',
    fn (BreadcrumbTrail $trail, $category) => $trail
        ->parent('blog')
        ->push($category->title, route('category', $category))
);
```

### Breadcrumbs::render() - Display Breadcrumbs in Views

Renders breadcrumbs using the configured template (default: Bootstrap 5). Accepts breadcrumb name and optional parameters.

```blade
{{-- Basic usage in Blade template --}}
{{ Breadcrumbs::render('home') }}

{{-- With parameter --}}
{{ Breadcrumbs::render('post', $post) }}

{{-- With multiple parameters --}}
{{ Breadcrumbs::render('comment', $post, $comment) }}

{{-- Route-bound breadcrumbs (auto-detect current route) --}}
{{ Breadcrumbs::render() }}

{{-- Output example (Bootstrap 5):
<nav aria-label="breadcrumb">
    <ol class="breadcrumb">
        <li class="breadcrumb-item"><a href="/">Home</a></li>
        <li class="breadcrumb-item"><a href="/blog">Blog</a></li>
        <li class="breadcrumb-item active" aria-current="page">Post Title</li>
    </ol>
</nav>
--}}
```

### Breadcrumbs::generate() - Get Breadcrumb Collection

Generates breadcrumbs and returns them as a Collection without rendering, useful for custom processing or manual rendering.

```php
<?php
use Diglactic\Breadcrumbs\Breadcrumbs;

// Generate breadcrumbs collection
$breadcrumbs = Breadcrumbs::generate('post', $post);

// Iterate in Blade template
@foreach (Breadcrumbs::generate('post', $post) as $breadcrumb)
    @if (!is_null($breadcrumb->url) && !$loop->last)
        <a href="{{ $breadcrumb->url }}">{{ $breadcrumb->title }}</a>
    @else
        <span>{{ $breadcrumb->title }}</span>
    @endif
    @if (!$loop->last) / @endif
@endforeach

// Use Collection methods
$breadcrumbs = Breadcrumbs::generate('post', $post);
$count = $breadcrumbs->count(); // 3
$first = $breadcrumbs->first(); // {title: "Home", url: "/"}
$filtered = $breadcrumbs->filter(fn($b) => $b->url !== null);
```

### $trail->push() - Add Breadcrumb to Trail

Adds a single breadcrumb to the trail with title, optional URL, and optional custom data.

```php
<?php
use Diglactic\Breadcrumbs\Breadcrumbs;
use Diglactic\Breadcrumbs\Generator as BreadcrumbTrail;

// Basic usage
Breadcrumbs::for('example', function (BreadcrumbTrail $trail) {
    // With URL
    $trail->push('Home', route('home'));

    // Without URL (no link)
    $trail->push('Current Page');

    // With custom data for templates
    $trail->push('Dashboard', route('dashboard'), ['icon' => 'dashboard.svg']);

    // With custom data for structured data
    $trail->push('Product', route('product', $product), [
        'image' => asset('products/' . $product->image)
    ]);
});

// Access custom data in custom template
@foreach ($breadcrumbs as $breadcrumb)
    <li>
        @if (isset($breadcrumb->icon))
            <img src="/images/{{ $breadcrumb->icon }}" alt="">
        @endif
        <a href="{{ $breadcrumb->url }}">{{ $breadcrumb->title }}</a>
    </li>
@endforeach
```

### $trail->parent() - Add Parent Breadcrumbs

Links to a parent breadcrumb definition, automatically including all ancestors in the trail.

```php
<?php
use Diglactic\Breadcrumbs\Breadcrumbs;
use Diglactic\Breadcrumbs\Generator as BreadcrumbTrail;
use App\Models\Category;

// Define parent
Breadcrumbs::for('products', function (BreadcrumbTrail $trail) {
    $trail->parent('home');
    $trail->push('Products', route('products.index'));
});

// Child with static parent
Breadcrumbs::for('product.show', function (BreadcrumbTrail $trail, $product) {
    $trail->parent('products');
    $trail->push($product->name, route('product.show', $product));
});

// Recursive parent for nested categories
Breadcrumbs::for('category', function (BreadcrumbTrail $trail, Category $category) {
    if ($category->parent) {
        $trail->parent('category', $category->parent);
    } else {
        $trail->parent('products');
    }
    $trail->push($category->name, route('category', $category));
});

// Result: Home / Products / Electronics / Phones / iPhone
```

### Breadcrumbs::view() - Render with Custom View

Renders breadcrumbs using a specified view template instead of the default configured view.

```php
<?php
// In controller
use Diglactic\Breadcrumbs\Breadcrumbs;
use Illuminate\Support\Facades\Config;

// Render with specific view
$html = Breadcrumbs::view('breadcrumbs::tailwind', 'post', $post);
$jsonLd = Breadcrumbs::view('breadcrumbs::json-ld', 'post', $post);

// Change default view at runtime
Config::set('breadcrumbs.view', 'breadcrumbs::tailwind');
```

```blade
{{-- In Blade template --}}
{{ Breadcrumbs::view('partials.breadcrumbs', 'post', $post) }}

{{-- Use different views for different contexts --}}
<head>
    {{ Breadcrumbs::view('breadcrumbs::json-ld', 'product', $product) }}
</head>
<body>
    {{ Breadcrumbs::view('breadcrumbs::bootstrap5', 'product', $product) }}
</body>

{{-- Built-in views: bootstrap4, bootstrap5, bulma, foundation6,
     json-ld, materialize, tailwind, uikit --}}
```

### Breadcrumbs::before() and Breadcrumbs::after() - Register Callbacks

Registers callbacks that run before or after breadcrumb generation, useful for automatically adding common breadcrumbs.

```php
<?php
use Diglactic\Breadcrumbs\Breadcrumbs;
use Diglactic\Breadcrumbs\Generator as BreadcrumbTrail;

// Add home to every breadcrumb trail
Breadcrumbs::before(function (BreadcrumbTrail $trail) {
    $trail->push('Home', route('home'));
});

// Add pagination to end of trail
Breadcrumbs::after(function (BreadcrumbTrail $trail) {
    $page = (int) request('page', 1);
    if ($page > 1) {
        $trail->push("Page {$page}");
    }
});

// Add current user context
Breadcrumbs::before(function (BreadcrumbTrail $trail) {
    if (auth()->check() && request()->is('admin/*')) {
        $trail->push('Admin Panel', route('admin.dashboard'));
    }
});

// Exclude pagination from current page detection
Breadcrumbs::after(function (BreadcrumbTrail $trail) {
    $page = (int) request('page', 1);
    if ($page > 1) {
        $trail->push("Page {$page}", null, ['current' => false]);
    }
});
```

### Breadcrumbs::current() - Get Current Page Breadcrumb

Returns the last breadcrumb in the trail, typically representing the current page.

```php
<?php
use Diglactic\Breadcrumbs\Breadcrumbs;

// Get current breadcrumb
$current = Breadcrumbs::current();
$title = $current ? $current->title : 'Default Title';
$url = $current ? $current->url : null;
```

```blade
{{-- Use in page title --}}
<title>
    {{ ($breadcrumb = Breadcrumbs::current()) ? $breadcrumb->title : 'Default' }}
    - My App
</title>

{{-- Use in heading --}}
<h1>{{ Breadcrumbs::current()?->title ?? 'Welcome' }}</h1>

{{-- Advanced filtering with Collection methods --}}
<?php
$current = Breadcrumbs::generate()
    ->where('current', '!==', false)
    ->last();
?>
```

### Breadcrumbs::exists() - Check if Breadcrumb Exists

Checks whether a breadcrumb with the given name has been registered.

```php
<?php
use Diglactic\Breadcrumbs\Breadcrumbs;

// Check if breadcrumb exists
if (Breadcrumbs::exists('post')) {
    echo Breadcrumbs::render('post', $post);
}

// Check current route breadcrumb
if (Breadcrumbs::exists()) {
    echo Breadcrumbs::render();
} else {
    echo '<p>No breadcrumb trail available</p>';
}

// Conditional rendering in controller
public function show(Post $post)
{
    $hasBreadcrumbs = Breadcrumbs::exists('post');
    return view('post.show', compact('post', 'hasBreadcrumbs'));
}
```

### Route-Bound Breadcrumbs - Automatic Route Detection

Automatically renders breadcrumbs based on the current route name when no parameters are passed to render().

```php
<?php
// routes/web.php
use Illuminate\Support\Facades\Route;

Route::name('home')->get('/', 'HomeController@index');
Route::name('posts.index')->get('/posts', 'PostController@index');
Route::name('posts.show')->get('/posts/{post}', 'PostController@show');

// routes/breadcrumbs.php
use Diglactic\Breadcrumbs\Breadcrumbs;
use Diglactic\Breadcrumbs\Generator as BreadcrumbTrail;
use App\Models\Post;

Breadcrumbs::for('home', function (BreadcrumbTrail $trail) {
    $trail->push('Home', route('home'));
});

Breadcrumbs::for('posts.index', function (BreadcrumbTrail $trail) {
    $trail->parent('home');
    $trail->push('Posts', route('posts.index'));
});

Breadcrumbs::for('posts.show', function (BreadcrumbTrail $trail, Post $post) {
    $trail->parent('posts.index');
    $trail->push($post->title, route('posts.show', $post));
});

// Custom 404 page
Breadcrumbs::for('errors.404', function (BreadcrumbTrail $trail) {
    $trail->parent('home');
    $trail->push('Page Not Found');
});
```

```blade
{{-- resources/views/layouts/app.blade.php --}}
<nav>
    {{ Breadcrumbs::render() }}
    {{-- Automatically detects route and parameters --}}
</nav>
```

### Breadcrumbs::macro() - Extend with Custom Methods

Adds custom methods to the Breadcrumbs facade using Laravel's macroable trait.

```php
<?php
use Diglactic\Breadcrumbs\Breadcrumbs;

// Define custom page title macro
Breadcrumbs::macro('pageTitle', function () {
    $title = ($breadcrumb = Breadcrumbs::current()) ? "{$breadcrumb->title} – " : '';

    if (($page = (int) request('page')) > 1) {
        $title .= "Page $page – ";
    }

    return $title . config('app.name');
});

// Define resource breadcrumbs macro
Breadcrumbs::macro('resource', function (string $name, string $title) {
    Breadcrumbs::for("{$name}.index", function ($trail) use ($name, $title) {
        $trail->parent('home');
        $trail->push($title, route("{$name}.index"));
    });

    Breadcrumbs::for("{$name}.create", function ($trail) use ($name) {
        $trail->parent("{$name}.index");
        $trail->push('New', route("{$name}.create"));
    });

    Breadcrumbs::for("{$name}.show", function ($trail, $model) use ($name) {
        $trail->parent("{$name}.index");
        $trail->push($model->title, route("{$name}.show", $model));
    });
});

// Use the macros
Breadcrumbs::resource('posts', 'Blog Posts');
Breadcrumbs::resource('users', 'Users');
```

```blade
<title>{{ Breadcrumbs::pageTitle() }}</title>
```

### Configuration - Customize Package Behavior

Configure breadcrumb file locations, views, exception handling, and custom classes.

```bash
# Publish configuration file
php artisan vendor:publish --tag=breadcrumbs-config

# Publish view templates for customization
php artisan vendor:publish --tag=breadcrumbs-views
```

```php
<?php
// config/breadcrumbs.php

return [
    // Default view template
    'view' => 'breadcrumbs::bootstrap5',

    // Breadcrumb definition files
    'files' => base_path('routes/breadcrumbs.php'),

    // Multiple files
    'files' => [
        base_path('breadcrumbs/admin.php'),
        base_path('breadcrumbs/frontend.php'),
    ],

    // Wildcard loading
    'files' => glob(base_path('breadcrumbs/*.php')),

    // Exception handling
    'unnamed-route-exception' => true,
    'missing-route-bound-breadcrumb-exception' => true,
    'invalid-named-breadcrumb-exception' => true,

    // Custom classes for advanced customization
    'manager-class' => Diglactic\Breadcrumbs\Manager::class,
    'generator-class' => Diglactic\Breadcrumbs\Generator::class,
];
```

### JSON-LD Structured Data - SEO-Friendly Breadcrumbs

Renders breadcrumbs as JSON-LD structured data for search engine optimization.

```blade
{{-- resources/views/products/show.blade.php --}}
<html>
<head>
    <title>{{ $product->name }}</title>

    {{-- JSON-LD structured data for SEO --}}
    {{ Breadcrumbs::view('breadcrumbs::json-ld', 'product.show', $product) }}
</head>
<body>
    {{-- Visible breadcrumb navigation --}}
    {{ Breadcrumbs::render('product.show', $product) }}

    <h1>{{ $product->name }}</h1>
</body>
</html>

{{-- Output in <head>:
<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
        {
            "@type": "ListItem",
            "position": 1,
            "item": {
                "@id": "https://example.com/",
                "name": "Home",
                "image": null
            }
        },
        {
            "@type": "ListItem",
            "position": 2,
            "item": {
                "@id": "https://example.com/products",
                "name": "Products",
                "image": null
            }
        }
    ]
}
</script>
--}}
```

```php
<?php
// Add image to structured data
Breadcrumbs::for('product.show', function (BreadcrumbTrail $trail, $product) {
    $trail->parent('products.index');
    $trail->push(
        $product->name,
        route('product.show', $product),
        ['image' => asset('products/' . $product->image)]
    );
});
```

### Custom Template - Create Your Own Breadcrumb View

Create custom breadcrumb templates with full control over HTML output and styling.

```blade
{{-- resources/views/partials/breadcrumbs.blade.php --}}

@unless ($breadcrumbs->isEmpty())
    <nav aria-label="breadcrumb">
        <ol class="breadcrumb">
            @foreach ($breadcrumbs as $breadcrumb)
                @if (!is_null($breadcrumb->url) && !$loop->last)
                    <li class="breadcrumb-item">
                        @if (isset($breadcrumb->icon))
                            <i class="icon-{{ $breadcrumb->icon }}"></i>
                        @endif
                        <a href="{{ $breadcrumb->url }}">{{ $breadcrumb->title }}</a>
                    </li>
                @else
                    <li class="breadcrumb-item active" aria-current="page">
                        {{ $breadcrumb->title }}
                    </li>
                @endif
            @endforeach
        </ol>
    </nav>
@endunless

{{-- Available variables:
$breadcrumbs - Collection of breadcrumb objects
$breadcrumb->title - The breadcrumb title
$breadcrumb->url - The breadcrumb URL (or null)
$breadcrumb->{custom} - Any custom data passed via push()
--}}
```

```php
<?php
// config/breadcrumbs.php
return [
    'view' => 'partials.breadcrumbs',
];
```

## Summary

Laravel Breadcrumbs is designed for Laravel applications that need hierarchical navigation trails. Common use cases include e-commerce sites with category hierarchies, blog platforms with post categorization, admin panels with multi-level sections, documentation sites, and any application with nested page structures. The package excels at building dynamic breadcrumbs that respond to route parameters and model relationships, making it ideal for applications with complex navigation patterns.

Integration is straightforward: install via Composer, define breadcrumbs in `routes/breadcrumbs.php` using the fluent API, and render them in Blade templates with a single method call. The package integrates with Laravel's routing system through route-bound breadcrumbs, supports all major CSS frameworks out of the box, and provides JSON-LD structured data for SEO. Advanced features include before/after callbacks for common breadcrumb patterns, custom data injection for template flexibility, macro support for extending functionality, and full customization through subclassing core classes.