Download the PHP package diglactic/laravel-breadcrumbs without Composer

Introduction

A simple Laravel-style way to create breadcrumbs.

This project is the official fork of the fantastically original Laravel Breadcrumbs by Dave James Miller and wouldn't have been possible without a bunch of awesome day-one contributors. Thanks, all!

Table of Contents

• Compatibility Chart
• Getting Started
• Defining Breadcrumbs
• Custom Templates
• Outputting Breadcrumbs
• Structured Data
• Route-Bound Breadcrumbs
• Advanced Usage
• FAQ
• Troubleshooting
• Contributing
• License

Compatibility Chart

For older Laravel versions, reference the original GitHub project. All tags have been mirrored if you prefer referencing this package, but will provide no functional difference.

Getting Started

1. Install

2. Define

Create a file called routes/breadcrumbs.php that looks like this:

See the Defining Breadcrumbs section for more details.

3. Style

By default, a Bootstrap 5 breadcrumb list will be rendered. To change this, initialize the config file by running this command:

Then, open config/breadcrumbs.php and edit this line:

The possible values are:

• breadcrumbs::bootstrap5 – Bootstrap 5
• breadcrumbs::bootstrap4 – Bootstrap 4
• breadcrumbs::bulma – Bulma
• breadcrumbs::foundation6 – Foundation 6
• breadcrumbs::json-ld – JSON-LD Structured Data
• breadcrumbs::materialize – Materialize
• breadcrumbs::tailwind – Tailwind CSS
• breadcrumbs::uikit – UIkit
• Or, you can specify the path to a custom view, like partials.breadcrumbs

See the Custom Templates section for more details.

You may also specify a custom view at runtime.

4. Output

Call Breadcrumbs::render() in the view for each page, passing it the name of the breadcrumb to use and any additional parameters:

See the Outputting Breadcrumbs section for other output options, and see Route-Bound Breadcrumbs for a way to link breadcrumb names to route names automatically.

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:

For generating the URL, you can use any of the standard Laravel URL-generation methods, including:

• url('path/to/route') (URL::to())
• secure_url('path/to/route')
• route('routename') or route('routename', 'param') or route('routename', ['param1', 'param2']) (URL::route())
• action('controller@action') (URL::action())
• Or just pass a string URL ('http://www.example.com/')

This example would be rendered like this:

And result in this output:

Home

Parent links

This is another static page, but with a parent link before it:

It works by calling the closure for the home breadcrumb defined above.

It would be rendered like this:

And result in this output:

Home / Blog

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.

Dynamic titles and links

This is a dynamically generated page pulled from the database:

The $post object (probably an Eloquent Model, but could be anything) would be passed in from the view:

It results in this output:

Blog / Post Title

You can also chain method calls to $trail. If you're using PHP 7.4 and above with arrow function support, you might prefer the following, more concise, syntax:

Nested categories

Finally, if you have nested categories or other special requirements, you can call $trail->push() multiple times:

Alternatively, you could make a recursive function such as this:

Both would be rendered like this:

And result in this:

Parent Category / Category Title

Custom Templates

Create a view

To customize the HTML, create your own view file similar to the following:

If you want to work off an existing built-in template, run the following command:

This will copy all built-in templates into the resources/views/vendor/breadcrumbs/ directory in your project, allowing you to make edits directly.

View data

The view will receive a Collection called $breadcrumbs.

Each breadcrumb is an object with the following keys:

• title – The breadcrumb title
• url – The breadcrumb URL, or null if none was given
• Plus additional keys for each item in $data (see Custom data)

Update the config

Then, update your config file with the custom view name:

Skipping the view

Alternatively, you can skip the custom view and call Breadcrumbs::generate() to get the breadcrumbs collection directly:

Outputting Breadcrumbs

Call Breadcrumbs::render() in the view for each page, passing it the name of the breadcrumb to use and any additional parameters.

With Blade

Or with a parameter:

Structured Data

To render breadcrumbs as JSON-LD structured data (usually for SEO reasons), use Breadcrumbs::view() to render the breadcrumbs::json-ld template in addition to the normal one. For example:

(Note: If you use Laravel Page Speed you may need to disable the TrimUrls middleware.)

To specify an image, add it to the $data parameter in push():

(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 more details, see Named Routes in the Laravel documentation.

Name your breadcrumbs to match

For each route, create a breadcrumb with the same name and parameters. For example:

To add breadcrumbs to a custom 404 Not Found page, use the name errors.404:

Output breadcrumbs in your layout

Call Breadcrumbs::render() with no parameters in your layout file:

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

Route binding exceptions

We'll 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 initialize the config file, if you haven't already:

Then open the newly-created file and set this value:

Similarly, to prevent it throwing an UnnamedRouteException if the current route doesn't have a name, set this value:

Route model binding

Laravel Breadcrumbs uses the same model binding as the controller. For example:

This makes your code less verbose and more efficient by only loading the post from the database once.

For more details see Route Model Binding in the Laravel documentation.

Resourceful controllers

Laravel automatically creates route names for resourceful controllers, e.g. photo.index, which you can use when defining your breadcrumbs. For example:

For more details see Resource Controllers in the Laravel documentation.

(Related FAQ: Why is there no Breadcrumbs::resource() method?.)

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:

In this case, $breadcrumb->url 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 associative array of data to be passed to the breadcrumb, which you can use in your custom template.

If you wanted each breadcrumb to have an icon, for instance, you might do:

The $data array's entries will be merged into the breadcrumb as properties.

Note: do not use the keys title or url, as they will be overwritten.

Before and after callbacks

You can register "before" and "after" callbacks to add breadcrumbs at the start/end of the trail. For example, to automatically add the current page number at the end:

Getting the current page breadcrumb

To get the last breadcrumb for the current page, use Breadcrumb::current(). For example, you could use this to output the current page title:

To ignore a breadcrumb, add 'current' => false to the $data parameter in push(). This can be useful to ignore pagination breadcrumbs:

For more advanced filtering, use Breadcrumbs::generate() and Laravel's Collection class methods instead:

Switching views at runtime

You can use Breadcrumbs::view() in place of Breadcrumbs::render() to render a template other than the default one:

Or you can override the config setting to affect all future render() calls:

Or you could call Breadcrumbs::generate() to get the breadcrumbs Collection and load the view manually:

Overriding the "current" route

If you call Breadcrumbs::render() or Breadcrumbs::generate() with no parameters, it will use the current route name and parameters by default (as returned by Laravel's Route::current() method).

You can override this by calling Breadcrumbs::setCurrentRoute($name, $param1, $param2...).

Checking if a breadcrumb exists

To check if a breadcrumb with a given name exists, call Breadcrumbs::exists('name'), which returns a boolean.

Defining breadcrumbs in a different file

If you don't want to use routes/breadcrumbs.php, you can change it in the config file. First initialize the config file, if you haven't already:

Update this line:

It can be an absolute path, as above, or an array:

So you can use glob() to automatically find files using a wildcard:

Or return an empty array [] to disable loading.

Defining/using breadcrumbs in another package

If you are creating your own package, simply load your breadcrumbs file from your service provider's boot() method:

Dependency injection

You can use dependency injection to access the Manager instance if you prefer, instead of using the Breadcrumbs:: facade:

Macros

The breadcrumbs Manager class is macroable, so you can add your own methods. For example:

Advanced customization

For more advanced customizations you can subclass Breadcrumbs\Manager and/or Breadcrumbs\Generator, then update the config file with the new class name:

Note: configuration syntax may change between releases.

FAQ

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.

You can always create your own using Breadcrumbs::macro(). Here's a good starting point:

Note that this doesn't deal with translations or nested resources, and it assumes that all models have a title attribute (which users probably don't). Adapt it however you see fit.

Troubleshooting

General

• Re-read the instructions and make sure you did everything correctly.
• Start with the simple options and only use the advanced options (e.g. Route-Bound Breadcrumbs) once you understand how it works.

Class 'Breadcrumbs' not found

• Try running composer update diglactic/laravel-breadcrumbs to upgrade.
• Try running php artisan package:discover to ensure the service provider is detected by Laravel.

Breadcrumb not found with name ...

• Make sure you register the breadcrumbs in the right place (routes/breadcrumbs.php by default).
  • Try putting dd(__FILE__) in the file to make sure it's loaded.
  • Try putting dd($files) in ServiceProvider::registerBreadcrumbs() to check the path is correct.
  • If not, try running php artisan config:clear (or manually delete bootstrap/cache/config.php) or update the path in config/breadcrumbs.php.
• Make sure the breadcrumb name is correct.
  • If using Route-Bound Breadcrumbs, make sure it matches the route name exactly.
• To suppress these errors when using Route-Bound Breadcrumbs (if you don't want breadcrumbs on some pages), either:
  • Register them with an empty closure (no push/parent calls), or
  • Set missing-route-bound-breadcrumb-exception to false in the config file to disable the check (but you won't be warned if you miss any pages).

ServiceProvider::registerBreadcrumbs(): Failed opening required ...

• Make sure the path is correct.
• If so, check the file ownership & permissions are correct.
• If not, try running php artisan config:clear (or manually delete bootstrap/cache/config.php) or update the path in config/breadcrumbs.php.

Undefined variable: breadcrumbs

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

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 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 Advanced Usage 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:

Then checkout the main branch and create your own local branch to work on:

Now make your changes, including unit tests and documentation (if appropriate). Run the unit tests to make sure everything is still working:

Then commit the changes. Fork the repository on GitHub if you haven't already, and push your changes to it:

Finally, browse to the repository on GitHub and create a pull request.

Using your fork in a project

To use your own fork in a project, update the composer.json in your main project as follows:

Replace YOUR_USERNAME with your GitHub username and YOUR_BRANCH with the branch name (e.g. develop). This tells Composer to use your repository instead of the default one.

Unit tests

To run the unit tests:

To run the unit tests and rebuild snapshots:

To check code coverage:

Then open test-coverage/index.html to view the results. Be aware of the edge cases in PHPUnit that can make it not-quite-accurate.

New version of Laravel

The following files will need to be updated to run tests against a new Laravel version:

• composer.json

  • laravel/framework (Laravel versions)
  • php (minimum PHP version)
  • Other dependencies (prefer bumping to the highest-available versions that work for all Laravel/PHP combinations)
• tests.yml
  • jobs.phpunit.strategy.matrix.laravel (Laravel versions)
  • jobs.phpunit.strategy.matrix.php (PHP versions)
  • jobs.phpunit.strategy.matrix.exclude (Unsupported combinations)

And the following documentation, as needed:

• README.md

  • Compatibility Chart
• UPGRADE.md
  • Add new section detailing any breaking package changes

License

Laravel Breadcrumbs is open-sourced software licensed under the MIT license.