Download the PHP package daikazu/breadcrumbs without Composer

Route-aware breadcrumb management for Laravel

Installation

You can install the package via composer:

You can publish the config file with:

Optionally, you can publish the views using

Usage

• Quick Start
• Defining Breadcrumbs
• Parent Chaining
• Route Model Binding
• HasBreadcrumb Interface
• Rendering
• Trail::home()
• Trail::fromArray() / Trail::fromJson()
• Truncation
• Caching
• Middleware
• Livewire Integration
• Configuration

Quick Start

Register a breadcrumb definition in a service provider, then render with the Blade component.

1. Register definitions — create a routes/breadcrumbs.php file and the package will auto-load it. Alternatively, register definitions directly in AppServiceProvider::boot(). The file path is configurable via the definition_file config key.

2. Render in a Blade layout:

The component resolves the current route automatically and renders nothing if no matching definition exists.

Defining Breadcrumbs

Use Breadcrumbs::for() to register a definition keyed to a route name. The closure receives a Trail instance as its first argument.

Trail methods:

The $data array on push and prepend accepts arbitrary metadata that your view can use — icon names, CSS classes, flags, and so on.

Parent Chaining

$trail->parent() resolves another registered definition and prepends its crumbs to the current trail. This composes full paths from independent definitions without duplication.

Resolving products.show produces: Home > Products > [product name]

Each level only defines its own crumb; the chain is assembled at resolve time.

Route Model Binding

When Breadcrumbs::current() is called, the package inspects the current route's bound parameters via Route::current()->parameters() and injects them into the closure automatically, matching by type-hint first, then by parameter name.

If the route has {product} bound to a Product model instance, it is injected without any extra configuration. The resolution mirrors Laravel's own dependency injection behavior.

Routes with multiple bound models are also supported:

Passing resolved objects to current()

When a route only binds a scalar — for example /blog/{slug} where the model is fetched manually (a remote API, a cache, a custom query) rather than via route model binding — Breadcrumbs::current() would otherwise hand the raw slug string to your closure. Pass the already-resolved object explicitly to override the route parameters and avoid a second lookup:

Explicit parameters are matched positionally, so the closure's parameter name does not matter — current($post) fills the first non-Trail argument whether it is called $post, $model, or anything else. Pass multiple values in order for multi-segment routes:

Calling Breadcrumbs::current() with no arguments is unchanged — it still resolves from the current route's bound parameters.

HasBreadcrumb Interface

As an alternative to registering a closure, an Eloquent model can own its own breadcrumb definition by implementing Daikazu\Breadcrumbs\Contracts\HasBreadcrumb.

No Breadcrumbs::for() call is needed. When the route binds a Product, the manager calls toBreadcrumb() automatically.

Resolution priority when no registered closure exists for the current route:

1. Registered closure via Breadcrumbs::for()
2. Bound model implementing HasBreadcrumb
3. MissingBreadcrumbException or silent empty trail

A registered closure always wins over HasBreadcrumb. This lets you override a model's default definition on a per-route basis.

Rendering

Blade component

The component resolves the current route. It calls shouldRender() internally and produces no output when the trail is empty, so it is safe to include unconditionally in layouts.

To render breadcrumbs for a specific route instead of the current one:

Pass route parameters when the target route requires them:

:params may also be used without route-name to forward resolved objects to the current route — handy when the route binds only a scalar (e.g. a slug) but the closure expects the full model (see Passing resolved objects to current()):

JSON-LD schema directive

Place @breadcrumbsSchema anywhere in your layout to output a <script type="application/ld+json"> tag with a valid BreadcrumbList schema. The head is the recommended location.

The directive renders nothing if no breadcrumb trail can be resolved, so no empty script tags are output. The schema uses BreadcrumbTrail::toSchema() internally and follows the schema.org BreadcrumbList specification.

Available views

Two built-in views ship with the package:

Switch the active view in config/breadcrumbs.php:

Publishing and customizing views

This copies the views to resources/views/vendor/breadcrumbs/. Edit them freely. The schema.blade.php partial that renders the JSON-LD script tag is structural and is not published.

After publishing, set view in config to point to your custom view:

Each view receives a $breadcrumbs variable — an instance of BreadcrumbTrail, which extends Illuminate\Support\Collection of Crumb objects.

Trail::home()

Trail::home() is a shorthand that prepends the home crumb using home_label and home_route from the config. It is equivalent to calling $trail->prepend(config('breadcrumbs.home_label'), route(config('breadcrumbs.home_route'))).

Override either value inline:

Both parameters are optional. Passing null (or omitting them) falls back to config values.

Trail::fromArray() / Trail::fromJson()

These static factory methods build a Trail directly from a data source, bypassing the resolver. They are intended for headless setups, CMS-driven pages, and API responses where breadcrumb data arrives pre-assembled.

Each entry requires a label key. The url key is optional.

Trail::fromJson() throws Daikazu\Breadcrumbs\Exceptions\InvalidTrailDataException if the input is not valid JSON or does not match the expected [{label, url}] shape.

Truncation

BreadcrumbTrail::truncate() collapses a long trail into a fixed maximum number of items by replacing the middle crumbs with an ellipsis placeholder. It always preserves the first crumb and the last crumb.

The ellipsis crumb has an empty URL and ['truncated' => true] in its data array so views can style it differently (for example, rendering it as a non-link).

truncate() returns a new BreadcrumbTrail instance and does not mutate the original. When the trail length is already within $maxItems, the original items are returned unchanged. The $maxItems argument must be at least 3 (first + ellipsis + last); values below 3 are treated as a no-op.

The default ellipsis label is …. Pass a custom string as the second argument:

Caching

For routes whose breadcrumb resolution involves database queries — such as loading a category ancestor chain — enable per-definition caching by chaining ->cache() on the return value of Breadcrumbs::for().

Cache keys are scoped per route and per model instance using model class names and primary keys — not serialize() — so loaded relations do not affect cache hits:

The cache store used is whatever is configured in breadcrumbs.cache_store (defaults to the application's default store). Cache tags require a driver that supports them (Redis, Memcached). Do not set tags on a file or database cache driver.

Cache invalidation with BreadcrumbCacheObserver

The package ships a BreadcrumbCacheObserver that flushes breadcrumb cache entries by tag when a model fires saved or deleted events. Register it yourself in a service provider — the package does not auto-register it.

The observer only flushes by tag, so the cache driver must support tagging. The tags passed to the observer should match those used in the ->cache() call.

Middleware

Daikazu\Breadcrumbs\Middleware\SetBreadcrumbs resolves Breadcrumbs::current() after the controller has executed and shares the result as $breadcrumbs with all views via View::share(). This is a convenience; the package functions without it.

Register it in your application's middleware stack:

Or apply it to specific route groups:

With the middleware active, $breadcrumbs is available in every view without calling Breadcrumbs::current() manually.

Livewire Integration

When livewire/livewire is installed and breadcrumbs.livewire is true, the package registers a Livewire component in place of the standard Blade component. The Livewire component re-resolves the breadcrumb trail on wire:navigate page transitions without a full reload.

Enable it in config/breadcrumbs.php:

Or via environment variable:

The <x-breadcrumbs /> tag in your layout works without modification. When Livewire is not installed or breadcrumbs.livewire is false, the standard Blade component is used. No Livewire dependency is introduced for non-Livewire applications.

Internally, the component listens for the breadcrumbs:refresh browser event triggered by Livewire's navigate hook:

This script is only emitted when breadcrumbs.livewire is true.

Laravel Octane

If you run Laravel Octane (or any long-lived process), call Breadcrumbs::flush() between requests to clear registered definitions and prevent state leaking across requests:

Configuration

Publish the config file to customize defaults:

Full reference:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mike Wall
• All Contributors

License

The MIT License (MIT). Please see License File for more information.