Defining Breadcrumbs

Breadcrumbs will usually correspond to actions or types of page. For each breadcrumb you specify a name, the breadcrumb title and the URL to link it to. Since these are likely to change dynamically, you do this in a closure, and you pass any variables you need into the closure.

The following examples should make it clear:

Static pages

The most simple breadcrumb is probably going to be your homepage, which will look something like this:

Note that the default templates do not create a link for the last breadcrumb (the one for the current page), even when a URL is specified. You can override this by creating your own template – see Custom Templates for more details.

(If you prefer to use Microdata or RDFa you will need to create a custom template.)

Route-Bound Breadcrumbs

In normal usage you must call Breadcrumbs::render($name, $params...) to render the breadcrumbs on every page. If you prefer, you can name your breadcrumbs the same as your routes and avoid this duplication...

Name your routes

Make sure each of your routes has a name. For example (routes/web.php):

Output breadcrumbs in your layout

This will automatically output breadcrumbs corresponding to the current route. The same applies to Breadcrumbs::generate():

$breadcrumbs=Breadcrumbs::generate();

And to Breadcrumbs::view():

{{ Breadcrumbs::view('breadcrumbs::json-ld') }}

Route binding exceptions

It will throw an InvalidBreadcrumbException if the breadcrumb doesn't exist, to remind you to create one. To disable this (e.g. if you have some pages with no breadcrumbs), first initialise the config file, if you haven't already:

Advanced Usage

Breadcrumbs with no URL

The second parameter to push() is optional, so if you want a breadcrumb with no URL you can do so:

$trail->push('Sample');

The $breadcrumb->url value will be null.

The default Bootstrap templates provided render this with a CSS class of "active", the same as the last breadcrumb, because otherwise they default to black text not grey which doesn't look right.

Custom data

The push() method accepts an optional third parameter, $data – an array of arbitrary data to be passed to the breadcrumb, which you can use in your custom template. For example, if you wanted each breadcrumb to have an icon, you could do:

$trail->push('Home', '/', ['icon'=>'home.png']);

The $data array's entries will be merged into the breadcrumb as properties, so you would access the icon as $breadcrumb->icon in your template, like this:

FAQ

There's a new version of Laravel - can you add support for it?

Yes - if/when (1) someone submits a pull request to add it, or (2) I decide to upgrade my own applications - whichever comes first. (In practice it's usually the former because I don't generally upgrade on day 1.)

Why is there no Breadcrumbs::resource() method?

A few people have suggested adding Breadcrumbs::resource() to match Route::resource(), but no-one has come up with a good implementation that (a) is flexible enough to deal with translations, nested resources, etc., and (b) isn't overly complex as a result.

Personally I don't think there is a good all-round solution, so instead I recommend adding your own using Breadcrumbs::macro(). Here's a starting point:

Undefined variable: breadcrumbs

Make sure you use {{ Breadcrumbs::render() }} or {{ Breadcrumbs::view() }}, not @include().

Method for does not exist

You're probably using a version older than 5.1 - use Breadcrumbs::register() instead of Breadcrumbs::for() (or upgrade).

Something else

Sorry I wasn't able to help this time, but once you have solved your problem, please edit this file with the solution to help the next person!

Contributing

Documentation: If you think the documentation can be improved in any way, please do edit this file and make a pull request.

Bug fixes: Please fix it and open a pull request. (See below for more detailed instructions.) Bonus points if you add a unit test to make sure it doesn't happen again!

New version of Laravel:See below for details of everything that needs to be changed to support a new version of Laravel. (Don't just change composer.json and ignore the rest!)

New features: Only features with a clear use case and well-considered API will be accepted. They must be documented and include unit tests. If in doubt, make a proof-of-concept (either code or documentation) and open a pull request to discuss the details. (Tip: If you want a feature that's too specific to be included by default, see Macros or Advanced customisations for ways to add them.)

Creating a pull request

The easiest way to work on Laravel Breadcrumbs is to tell Composer to install it from source (Git) using the --prefer-source flag:

Run composer update to install the new version of Laravel, and scripts/test.sh to make sure everything still works.

If everything does work, it can be released as a patch version. If changes are needed, it may need to be a minor version (consult semver.org). If there are major changes in Laravel, I will release a new major version that drops support for old versions of Laravel, rather than attempting to support both in one codebase. Please update the README accordingly.

No Technical Support!

Sorry, I don't offer any technical support, and GitHub Issues are disabled. I won't figure out why it's not working for you. I won't fix bugs for you. I won't write new features on request.

Maybe that seems unfair to you? If so, please remember this is free open source software. The license even says The software is provided "as is", without warranty of any kind. I wrote it for my own benefit, not yours.

But the beauty of open source is you can do whatever you want with it! You can fork it, fix it, improve it and extend it. If you think other people would benefit from your changes, you can submit a pull request to have your changes included in the next release. Yes it requires some effort on your part, but why should I do all the work?

So if you get stuck, please don't expect me to help! Here are some alternate suggestions:

Older versions

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.