fragkp/laravel-route-breadcrumb

4.0.0 2020-11-27 20:19 UTC

Requires

• php: ^7.4|^8.0
• laravel/framework: ^8.0

Requires (Dev)

• mockery/mockery: ^1.4
• orchestra/database: ^6.0
• orchestra/testbench: ^6.0
• phpunit/phpunit: ^9.4

MIT

• Kevin Pohl

• route
• laravel
• breadcrumb

README

This package tries to give a simple solution for breadcrumbs. Add breadcrumbs direct to your routes and display them in your views.

Installation

You can install the package via composer:

composer require fragkp/laravel-route-breadcrumb

If you want also use the facade to access the main breadcrumb class, add this line to your facades array in config/app.php:

'Breadcrumb' => Fragkp\LaravelRouteBreadcrumb\Facades\Breadcrumb::class,

This package contains some pre-built views for the most active css-frameworks:

• Bootstrap 3
• Bootstrap 4
• Bulma
• Foundation 6

If you want to use one of these views, include it in this way:

@include('laravel-breadcrumb::bootstrap3')

To customize the pre-built views, run this command:

php artisan vendor:publish Fragkp\LaravelRouteBreadcrumb\BreadcrumbServiceProvider --tag=views

Note: You could also create your own custom view to display breadcrumb links.

Usage

Defining breadcrumbs

Basic

To add a breadcrumb title to your route, call the breadcrumb method and pass your title.

Route::get('/')->breadcrumb('Your custom title');

Index

On some websites, you wish to have always an index inside your breadcrumbs. Use the breadcrumbIndex method. This method should only be used once.

Note: breadcrumbIndex sets also the breadcrumb title for this route.

Route::get('/')->breadcrumbIndex('Start');

Route::get('/foo')->breadcrumb('Your custom title');

Inside groups

The breadcrumb method will also work inside route groups.

Route::get('/')->breadcrumbIndex('Start');

Route::prefix('/foo')->group(function () {
    Route::get('/bar')->breadcrumb('Your custom title');
});

Group index

Also, it is possible to specify a group index title by calling breadcrumbGroup. This method should only be used once inside a group.

Note: breadcrumbGroup sets also the breadcrumb title for this route.

Route::get('/')->breadcrumbIndex('Start');

Route::prefix('/foo')->group(function () {
    Route::get('/')->breadcrumbGroup('Foo group index');

    Route::get('/bar')->breadcrumb('Your custom title');
});

Custom title resolver

If you want to customize your breadcrumb title, you could pass a closure to all breadcrumb methods.

Route::get('/')->breadcrumb(function () {
    return 'Your custom title';
});

You could also pass a fully qualified class name. This will invoke your class.

Route::get('/')->breadcrumb(YourCustomTitleResolver::class);

class YourCustomTitleResolver
{
    public function __invoke()
    {
        return 'Your custom title';
    }
}

You may also pass a callable.

Route::get('/foo/{id}')->breadcrumb([app('my_breadcrumb_resolver'), 'resolve']);

// my_breadcrumb_resolver
class MyBreadcrumbResolver
{
    public function resolve($id)
    {
        $title = $this->repo->findById($id);
        
        return $title->getName();
    }
}

Route parameters

All route parameters will be passed to your resolver. Route model binding is also supported.

Route::get('/{foo}')->breadcrumb(YourCustomTitleResolver::class);

class YourCustomTitleResolver
{
    public function __invoke(Foo $foo)
    {
        return "Title: {$foo->title}";
    }
}

Accessing breadcrumb

Links

The links method will return a Collection of BreadcrumbLink.

Note: The array is indexed by the uri.

app(Breadcrumb::class)->links(); // or use here the facade

Example result:

Illuminate\Support\Collection {#266
    #items: array:2 [
        "/" => Fragkp\LaravelRouteBreadcrumb\BreadcrumbLink {#41
            +uri: "/"
            +title: "Start"
        }
        "foo" => Fragkp\LaravelRouteBreadcrumb\BreadcrumbLink {#262
            +uri: "foo"
            +title: "Your custom title"
        }
    ]
}

Index

The index method will return a single instance of BreadcrumbLink. If you haven't defined any index, null is returned.

app(Breadcrumb::class)->index(); // or use here the facade

Example result:

Fragkp\LaravelRouteBreadcrumb\BreadcrumbLink {#36
    +uri: "/"
    +title: "Start"
}

Current

The current method will return a single instance of BreadcrumbLink. If no route is provided (e.g. on errors), null is returned.

app(Breadcrumb::class)->current(); // or use here the facade

Example result:

Fragkp\LaravelRouteBreadcrumb\BreadcrumbLink {#36
    +uri: "/"
    +title: "Your custom title"
}

View example

A good way to access the breadcrumb inside your views is to bound it via a View Composer.

For more information about View Composers, have a look at the Laravel docs.

// app/Providers/AppServiceProvider.php

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        View::composer('your-view', function ($view) {
            $view->with('breadcrumb', app(Breadcrumb::class)->links());
        });
    }
}

// resources/views/breadcrumb.blade.php

<ul>
    @foreach ($breadcrumb as $link)
        <li>
            <a href="{{ url($link->uri) }}">{{ $link->title }}</a>
        </li>
    @endforeach
</ul>

Testing

./vendor/bin/phpunit

License

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