Download the PHP package atstudio-tech/breadcrumbs without Composer

Laravel Breadcrumbs

A complete rework of an older Laravel's package that lets build breadcrumbs with quickly and easy.

Installation

You can install the package by running this command in your console:

The Service Provider will be automatically discovered so there is no need to add it manually to your /config/app.php file.

Vendor Files

You can publish both the configuration and views files with these commands:

Usage

There are two different places to populate a breadcrumbs list:

1. In your routes file, e.g. web.php.
2. Directly in your route's action, e.g. closure or controller.

Routes File

With this method you can get breadcrumbs declaration out of the way, however we don't have access to route parameters. That's a case where we can put breadcrumbs declaration in our controller.

This route macro has the same signature as the crumbs helper function.

Controller

This way you can use route parameters to build your breadcrumbs, such as showing a resource's ID.

Notations

There are are also three different ways of building a breadcrumbs list:

Breadcrumbs Class

or

Crumbs Façade

Helper Function

This is the one we have used so far

If no parameters are passed, the function will return an instance of the main Breadcrumbs class.

Rendering

You can render the breadcrumbs list by calling crumbs()->render() inside a Blade view or using a custom directive:

Both notations accept an optional parameter $view:

• crumbs()->render('breadcrumbs::custom-view')
• @crumbs(breadcrumbs::custom-view)

You can either customize already existing views that come with the package by running:

Or specify a custom view inside config('breadcrumbs.view').

View Customization

Let's say we want to create a completely new view for our breadcrumbs. We start by creating a new Blade file inside resources/views/vendor/breadcrumbs/custom-theme.blade.php (I prefer to put even custom views inside the vendor folder, but feel free to put them anywhere you like as long as it's inside resources/views folder).

Let's take a look the default view file (resources/views/vendor/breadcrumbs/plain.blade.php):

A few things to note here:

• $breadcrumbs is automatically passed to the view. This is the instance of Breadcrumbs class. You can also call $breadcrumbs->all() which is the same thing.
• $breadcrumb->active is a computed property that simply returns true in case the breadcrumb's path is the same as current URL.

API

Breadcrumbs::add(string|array $title, ?string $path = null, mixed $params = null)

A breadcrumb requires a title.

If $path is not provided, current URL will be used instead. $path can either be relative URL that will be converted to an absolute link or a route name. In case of a route name, you can also use the third parameter $params.

$title accepts both a string and an array. If it's an array, it must contain these keys:

crumbs(string|array|callable|null $title = null, ?string $path = null, mixed $params = null)

If you call this helper function without any parameter, it will simply return an instance of Breadcrumbs as mentioned above. Otherwise it accepts the same parameters as Breadcrumbs::add().

Exclusively to this function, the $title parameter also accepts a closure (the same goes for the Route::crumbs() macro as shown in the example above):

Breadcrumb Item

A single breadcrumb item has title, path and active properties.

Changelog

The CHANGELOG file will tell you about all changes to this package.

Contributing

Please see CONTRIBUTING for details.

Credits

• Alex Torscho
• All Contributors

License

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