README

A simple breadcrumbs implementation for Laravel with flexible class based segment customisation.

Installation
Usage
Configuration
Package removal
Todo
Changelog
Contributing
Security
Credits
Coffee Time
License

Installation

Depending on which version of Laravel you're on, you may need to specify which version to install.

Laravel Version	Package Version
9.0	^1.2
8.0	^1.0

Run composer require robotsinside/laravel-breadcrumbs.
Optionally register the service provider in config/app.php

/*
* Package Service Providers...
*/
\RobotsInside\Breadcrumbs\BreadcrumbsServiceProvider::class,

Auto-discovery is enabled, so this step can be skipped.

    'aliases' => [
        ...
        'Breadcrumbs' => \RobotsInside\Breadcrumbs\Facades\Breadcrumbs::class,
    ],

Publish the config file php artisan vendor:publish --provider="RobotsInside\Breadcrumbs\BreadcrumbsServiceProvider" --tag="config"
Publish the view files php artisan vendor:publish --provider="RobotsInside\Breadcrumbs\BreadcrumbsServiceProvider" --tag="views"

Usage

Once installed you can start rendering breadcrumbs immediately.

<div class="container">
    {{ Breadcrumbs::render() }}
</div>

For example (using the Bootstrap 4 template) if the URL is http://example.test/about-us/team the output will be:

+-----------+-------------------------------+-----------------------+---------------------------------------------------------------+
| Method    | URI                           | Name                  | Action                                                        |
+-----------+-------------------------------+-----------------------+---------------------------------------------------------------+
| GET|HEAD  | about-us/team                 | about.team            | Closure                                                       |

<div class="container">
    <nav aria-label="You are here:" role="navigation">
        <ul class="breadcrumb">
            <li class="breadcrumb-item">
                <a href="http://example.test">Home</a>
            </li>
            <li class="breadcrumb-item">
                <a href="http://example.test/about-us">About us</a>
            </li>
            <li class="breadcrumb-item">
                Team
            </li>
        </ul>
    </nav>
</div>

The following example includes an injected model.

+-----------+-------------------------------+-----------------------+---------------------------------------------------------------+
| Method    | URI                           | Name                  | Action                                                        |
+-----------+-------------------------------+-----------------------+---------------------------------------------------------------+
| GET|HEAD  | posts/{post}                  | posts.show            | App\App\Posts\Controllers\PostController@show                 |

The Post model will be automatically injected into the breadcrumbs class and the label that is used will depend on whether you have a breadcrumb label class defined for that model and which modelAttributes you have listed in your config file.

The modelAttributes key in the config file can be used to define a selection of model attributes for automatic resolution in your breadcrumbs (see Breadcrumb labels). For more complex situations, you can define a BreadcrumbLabel class as shown below. This class contains a model property which is resolved via the route model binding.

<?php

namespace App\Breadcrumbs\Labels;

use RobotsInside\Breadcrumbs\Label;

class PostBreadcrumbLabel extends Label
{
    public function label()
    {
        return $this->model->whatever;
    }    
}

Don't forget to register your label classes as explained in Breadcrumb labels.

Configuration

The config file should be pretty self explanatory.

Templates

You have the option of choosing a pre-defined template, or creating your own. The provided options are:

Bootstrap 3 (bootstrap-3)
Bootstrap 4 (bootstrap-4)
Bulma (bulma)
Foundation (foundation)

If you want to provide your own breadcrumbs template, provide the name of your Blade template in the template option:

'template' => [
    'style' => 'custom',
    'path' => 'breadcrumbs.custom' // Will look in: 'views.breadcrumbs.custom'
],

Breadcrumb mutators

If you want to define any breadcrumb mutator classes, you need to provide the namespace where the Mutator classes are located. By default this is set to App\\Breadcrumbs\\Mutators\\, but you can change it to suit your project requirements.

Breadcrumb labels

In my own projects I often use name and title model attributes as my breadcrumb labels. Having to define custom breadcrumb labels in these trivial situations is cumbersome. Instead you can define a modelAttributes array in the config file to take care of that.

'modelAttributes' => [
    'name', 
    'title',
    'whatever'
]

If your model matches multiple attributes in this array, the left-most database attribute will be used.

To define some more complex logic for your breadcrumb labels you will need to provide a mapping for your Model => BreadcrumbLabel classes in config/breadcrumbs.php.

'labels' => [
    App\Post::class => App\Breadcrumbs\Labels\PostBreadcrumbLabel::class,
],

Removing nodes

Let's say you have an admin area in your app, in that case you probably want to remove the admin segment from your breadcrumbs.

You can achieve this by defining a mutator and calling the remove method in the mutate method. The remove method expects an array, so you can remove multiple nodes if needed.

<?php

namespace App\Breadcrumbs\Mutators;

use RobotsInside\Breadcrumbs\Mutator;

class AdminMutator extends Mutator
{
	public function mutate()
	{
		$this->remove(['admin']);
	}
}

{{ Breadcrumbs::mutate('AdminMutator')->render() }}

If the URL is http://example.test/admin/posts/my-post, breadcrumbs will render:

<nav aria-label="You are here:" role="navigation">
    <ul class="breadcrumb">
        <li class="breadcrumb-item">
            <a href="http://example.test">
                Home
            </a>
        </li>
        <li class="breadcrumb-item">
            <a href="http://example.test/posts">
                Posts
            </a>
        </li>
        <li class="breadcrumb-item">
            My Post
        </li>
    </ul>
</nav>

Adding nodes

If for some reason you need to add one or more nodes, you can do that too.

You can achieve this by defining a mutator and calling the add method in the mutate method, for example:

<?php

namespace App\Breadcrumbs\Mutators;

use RobotsInside\Breadcrumbs\Mutator;

class AddPostIndexMutator extends Mutator
{
	public function mutate()
	{
		$this->add('All Posts', 'my-post', route('posts.index'));
	}
}

{{ Breadcrumbs::mutate('AddPostIndexMutator')->render() }}

If the URL is http://example.test/my-post, breadcrumbs will render:

<nav aria-label="You are here:" role="navigation">
    <ul class="breadcrumb">
        <li class="breadcrumb-item">
            <a href="http://example.test">Home</a>
        </li>
        <li class="breadcrumb-item">
            <a href="http://example.test/posts">All Posts</a>
        </li>
        <li class="breadcrumb-item">
            My Post
        </li>
    </ul>
</nav>

Package removal

To remove the package:

Remove the facade in config/app.php
Delete the path/to/Breadcrumbs directory from your application
Delete all {{ Breadcrumbs::render }} statements in your views
Delete config/breadcrumbs.php
Run composer remove robotsinside/laravel-breadcrumbs

When I developed this package I was faced with a decision on how to let users customise their breadcrumbs. Initally I though I would provide a BreadcrumbsInteface that would need to be implemented on Model classes, but later decided against it since that would mean implementing methods on all of your models that have breadcrumb labels.

Instead, I opted for a config array mapping since that would be easier to remove at a later date if you decide to remove this package from your project at a later date.

Todo

Write tests
Finish README

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email robertfrancken@gmail.com instead of using the issue tracker.

robotsinside / laravel-breadcrumbs

Maintainers

Details