Package Data | |
---|---|
Maintainer Username: | sheng |
Maintainer Contact: | sheng@diglactic.com (Sheng Slogar) |
Package Create Date: | 2020-04-20 |
Package Last Update: | 2024-03-20 |
Home Page: | https://packagist.org/packages/diglactic/laravel-breadcrumbs |
Language: | PHP |
License: | MIT |
Last Refreshed: | 2024-11-17 03:05:52 |
Package Statistics | |
---|---|
Total Downloads: | 4,987,363 |
Monthly Downloads: | 150,059 |
Daily Downloads: | 3,434 |
Total Stars: | 868 |
Total Watchers: | 11 |
Total Forks: | 63 |
Total Open Issues: | 0 |
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!
| Laravel | Laravel Breadcrumbs | |---------|---------------------| | 8.x | 6.x | | 7.x | 6.x | | 6.x | 6.x |
For older Laravel versions, you'll need to use the original GitHub project.
composer require diglactic/laravel-breadcrumbs
Create a file called routes/breadcrumbs.php
that looks like this:
<?php
// Home
Breadcrumbs::for('home', function ($trail) {
$trail->push('Home', route('home'));
});
// Home > About
Breadcrumbs::for('about', function ($trail) {
$trail->parent('home');
$trail->push('About', route('about'));
});
// Home > Blog
Breadcrumbs::for('blog', function ($trail) {
$trail->parent('home');
$trail->push('Blog', route('blog'));
});
// Home > Blog > [Category]
Breadcrumbs::for('category', function ($trail, $category) {
$trail->parent('blog');
$trail->push($category->title, route('category', $category->id));
});
// Home > Blog > [Category] > [Post]
Breadcrumbs::for('post', function ($trail, $post) {
$trail->parent('category', $post->category);
$trail->push($post->title, route('post', $post->id));
});
See the Defining Breadcrumbs section for more details.
By default, a Bootstrap-compatible ordered list will be rendered, so if you're using Bootstrap 4 you can skip this step.
First, initialize the config file by running this command:
php artisan vendor:publish --tag=breadcrumbs-config
Then, open config/breadcrumbs.php
and edit this line:
'view' => 'breadcrumbs::bootstrap4',
The possible values are:
breadcrumbs::bootstrap4
– Bootstrap 4
breadcrumbs::bootstrap3
– Bootstrap 3
breadcrumbs::bootstrap2
– Bootstrap 2
breadcrumbs::bulma
– Bulma
breadcrumbs::foundation6
– Foundation 6
breadcrumbs::json-ld
– JSON-LD Structured Data
breadcrumbs::materialize
– Materialize
breadcrumbs::tailwind
– Tailwind CSS
breadcrumbs::uikit
– UIkit
(<script> tag, no visible output)partials.breadcrumbs
See the Custom Templates section for more details.
Finally, call Breadcrumbs::render()
in the view for each page, passing it the name of the breadcrumb to use and any
additional parameters – for example:
{{ Breadcrumbs::render('home') }}
{{ Breadcrumbs::render('category', $category) }}
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.
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:
The most simple breadcrumb is probably going to be your homepage, which will look something like this:
Breadcrumbs::for('home', function ($trail) {
$trail->push('Home', route('home'));
});
As you can see, you simply call $trail->push($title, $url)
inside the closure.
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()
)'http://www.example.com/'
)This example would be rendered like this:
{{ Breadcrumbs::render('home') }}
And results in this output:
Home
This is another static page, but this has a parent link before it:
Breadcrumbs::for('blog', function ($trail) {
$trail->parent('home');
$trail->push('Blog', route('blog'));
});
It works by calling the closure for the home
breadcrumb defined above.
It would be rendered like this:
{{ Breadcrumbs::render('blog') }}
And results 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.
This is a dynamically generated page pulled from the database:
Breadcrumbs::for('post', function ($trail, $post) {
$trail->parent('blog');
$trail->push($post->title, route('post', $post));
});
The $post
object (probably an Eloquent Model,
but could be anything) would simply be passed in from the view:
{{ Breadcrumbs::render('post', $post) }}
It results in this output:
Tip: You can pass multiple parameters if necessary.
Finally, if you have nested categories or other special requirements, you can call $trail->push()
multiple times:
Breadcrumbs::for('category', function ($trail, $category) {
$trail->parent('blog');
foreach ($category->ancestors as $ancestor) {
$trail->push($ancestor->title, route('category', $ancestor->id));
}
$trail->push($category->title, route('category', $category->id));
});
Alternatively, you could make a recursive function such as this:
Breadcrumbs::for('category', function ($trail, $category) {
if ($category->parent) {
$trail->parent('category', $category->parent);
} else {
$trail->parent('blog');
}
$trail->push($category->title, route('category', $category->slug));
});
Both would be rendered like this:
{{ Breadcrumbs::render('category', $category) }}
And result in this:
Home / Blog / Grandparent Category / Parent Category / Category Title
To customize the HTML, create your own view file (e.g. resources/views/partials/breadcrumbs.blade.php
) like this:
@unless ($breadcrumbs->isEmpty())
<ol class="breadcrumb">
@foreach ($breadcrumbs as $breadcrumb)
@if (!is_null($breadcrumb->url) && !$loop->last)
<li class="breadcrumb-item"><a href="{{ $breadcrumb->url }}">{{ $breadcrumb->title }}</a></li>
@else
<li class="breadcrumb-item active">{{ $breadcrumb->title }}</li>
@endif
@endforeach
</ol>
@endunless
(See the resources/views/ directory for the built-in templates.)
The view will receive an array called $breadcrumbs
.
Each breadcrumb is an object with the following keys:
title
– The breadcrumb titleurl
– The breadcrumb URL, or null
if none was given$data
(see Custom data)Then update your config file (config/breadcrumbs.php
) with the custom view name, e.g.:
'view' => 'partials.breadcrumbs', #--> resources/views/partials/breadcrumbs.blade.php
Alternatively you can skip the custom view and call Breadcrumbs::generate()
to get the breadcrumbs
Collection directly:
@foreach (Breadcrumbs::generate('post', $post) as $breadcrumb)
{{-- ... --}}
@endforeach
Call Breadcrumbs::render()
in the view for each page, passing it the name of the breadcrumb to use and any additional parameters.
In the page (e.g. resources/views/home.blade.php
):
{{ Breadcrumbs::render('home') }}
Or with a parameter:
{{ Breadcrumbs::render('category', $category) }}
In the page (e.g. resources/views/home.blade.php
):
@extends('layout.name')
@section('breadcrumbs')
{{ Breadcrumbs::render('home') }}
@endsection
Or using the shorthand syntax:
@extends('layout.name')
@section('breadcrumbs', Breadcrumbs::render('home'))
And in the layout (e.g. resources/views/layout/name.blade.php
):
@yield('breadcrumbs')
In the page (e.g. resources/views/home.php
):
<?= Breadcrumbs::render('home') ?>
Or use the longhand syntax if you prefer:
<?php echo Breadcrumbs::render('home') ?>
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:
<html>
<head>
...
{{ Breadcrumbs::view('breadcrumbs::json-ld', 'category', $category) }}
...
</head>
<body>
...
{{ Breadcrumbs::render('category', $category) }}
...
</body>
</html>
(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()
:
Breadcrumbs::for('post', function ($trail, $post) {
$trail->parent('home');
$trail->push($post->title, route('post', $post), ['image' => asset($post->image)]);
});
(If you prefer to use Microdata or RDFa you will need to create a custom template.)
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.
Make sure each of your routes has a name. For example (routes/web.php
):
// Home
Route::name('home')->get('/', 'HomeController@index');
// Home > [Post]
Route::name('post')->get('/post/{id}', 'PostController@show');
For more details see Named Routes in the Laravel documentation.
For each route, create a breadcrumb with the same name and parameters. For example (routes/breadcrumbs.php
):
// Home
Breadcrumbs::for('home', function ($trail) {
$trail->push('Home', route('home'));
});
// Home > [Post]
Breadcrumbs::for('post', function ($trail, $id) {
$post = Post::findOrFail($id);
$trail->parent('home');
$trail->push($post->title, route('post', $post));
});
To add breadcrumbs to a custom 404 Not Found page, use
the name errors.404
:
// Error 404
Breadcrumbs::for('errors.404', function ($trail) {
$trail->parent('home');
$trail->push('Page Not Found');
});
Call Breadcrumbs::render()
with no parameters in your layout file (e.g. resources/views/app.blade.php
):
{{ Breadcrumbs::render() }}
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') }}
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:
php artisan vendor:publish --tag=breadcrumbs-config
Then open config/breadcrumbs.php
and set this value:
'missing-route-bound-breadcrumb-exception' => false,
Similarly, to prevent it throwing an UnnamedRouteException
if the current route doesn't have a name, set this value:
'unnamed-route-exception' => false,
Laravel Breadcrumbs uses the same model binding as the controller. For example:
// routes/web.php
Route::name('post')->get('/post/{post}', 'PostController@show');
// app/Http/Controllers/PostController.php
use App\Post;
class PostController extends Controller
{
public function show(Post $post) // <-- Implicit model binding happens here
{
return view('post/show', ['post' => $post]);
}
}
// routes/breadcrumbs.php
Breadcrumbs::for('post', function ($trail, $post) { // <-- The same Post model is injected here
$trail->parent('home');
$trail->push($post->title, route('post', $post));
});
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.
Laravel automatically creates route names for resourceful controllers, e.g. photo.index
, which you can use when
defining your breadcrumbs. For example:
// routes/web.php
Route::resource('photo', PhotoController::class);
$ php artisan route:list
+--------+----------+--------------------+---------------+-------------------------+------------+
| Domain | Method | URI | Name | Action | Middleware |
+--------+----------+--------------------+---------------+-------------------------+------------+
| | GET|HEAD | photo | photo.index | PhotoController@index | |
| | GET|HEAD | photo/create | photo.create | PhotoController@create | |
| | POST | photo | photo.store | PhotoController@store | |
| | GET|HEAD | photo/{photo} | photo.show | PhotoController@show | |
| | GET|HEAD | photo/{photo}/edit | photo.edit | PhotoController@edit | |
| | PUT | photo/{photo} | photo.update | PhotoController@update | |
| | PATCH | photo/{photo} | | PhotoController@update | |
| | DELETE | photo/{photo} | photo.destroy | PhotoController@destroy | |
+--------+----------+--------------------+---------------+-------------------------+------------+
// routes/breadcrumbs.php
// Photos
Breadcrumbs::for('photo.index', function ($trail) {
$trail->parent('home');
$trail->push('Photos', route('photo.index'));
});
// Photos > Upload Photo
Breadcrumbs::for('photo.create', function ($trail) {
$trail->parent('photo.index');
$trail->push('Upload Photo', route('photo.create'));
});
// Photos > [Photo Name]
Breadcrumbs::for('photo.show', function ($trail, $photo) {
$trail->parent('photo.index');
$trail->push($photo->title, route('photo.show', $photo->id));
});
// Photos > [Photo Name] > Edit Photo
Breadcrumbs::for('photo.edit', function ($trail, $photo) {
$trail->parent('photo.show', $photo);
$trail->push('Edit Photo', route('photo.edit', $photo->id));
});
For more details see Resource Controllers in the Laravel documentation.
(Related FAQ: Why is there no Breadcrumbs::resource() method?.)
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.
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:
<li><a href="{{ $breadcrumb->url }}">
<img src="/images/icons/{{ $breadcrumb->icon }}">
{{ $breadcrumb->title }}
</a></li>
Do not use the keys title
or url
as they will be overwritten.
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:
Breadcrumbs::after(function ($trail) {
$page = (int) request('page', 1);
if ($page > 1) {
$trail->push("Page $page");
}
});
To get the last breadcrumb for the current page, use Breadcrumb::current()
. For example, you could use this to output
the current page title:
<title>{{ ($breadcrumb = Breadcrumbs::current()) ? $breadcrumb->title : 'Fallback Title' }}</title>
To ignore a breadcrumb, add 'current' => false
to the $data
parameter in push()
. This can be useful to ignore
pagination breadcrumbs:
Breadcrumbs::after(function ($trail) {
$page = (int) request('page', 1);
if ($page > 1) {
$trail->push("Page $page", null, ['current' => false]);
}
});
<title>
{{ ($breadcrumb = Breadcrumbs::current()) ? "$breadcrumb->title –" : '' }}
{{ ($page = (int) request('page')) > 1 ? "Page $page –" : '' }}
Demo App
</title>
For more advanced filtering, use Breadcrumbs::generate()
and Laravel's
Collection class methods instead:
$current = Breadcrumbs::generate()->where('current', '!==', 'false)->last();
You can use Breadcrumbs::view()
in place of Breadcrumbs::render()
to render a template other than the
default one:
{{ Breadcrumbs::view('partials.breadcrumbs2', 'category', $category) }}
Or you can override the config setting to affect all future render()
calls:
Config::set('breadcrumbs.view', 'partials.breadcrumbs2');
{{ Breadcrumbs::render('category', $category) }}
Or you could call Breadcrumbs::generate()
to get the breadcrumbs Collection and load the view manually:
@include('partials.breadcrumbs2', ['breadcrumbs' => Breadcrumbs::generate('category', $category)])
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...)
.
To check if a breadcrumb with a given name exists, call Breadcrumbs::exists('name')
, which returns a boolean.
If you don't want to use routes/breadcrumbs.php
, you can change it in the config file. First initialise the config
file, if you haven't already:
php artisan vendor:publish --tag=breadcrumbs-config
Then open config/breadcrumbs.php
and edit this line:
'files' => base_path('routes/breadcrumbs.php'),
It can be an absolute path, as above, or an array:
'files' => [
base_path('breadcrumbs/admin.php'),
base_path('breadcrumbs/frontend.php'),
],
So you can use glob()
to automatically find files using a wildcard:
'files' => glob(base_path('breadcrumbs/*.php')),
Or return an empty array []
to disable loading.
If you are creating your own package, simply load your breadcrumbs file from your service provider's boot()
method:
use Illuminate\Support\ServiceProvider;
class MyServiceProvider extends ServiceProvider
{
public function register() {}
public function boot()
{
if (class_exists('Breadcrumbs')) {
require __DIR__ . '/breadcrumbs.php';
}
}
}
You can use dependency injection to access the Manager
instance if you prefer, instead of using the Breadcrumbs::
facade:
use Diglactic\Breadcrumbs\Manager;
use Illuminate\Support\ServiceProvider;
class MyServiceProvider extends ServiceProvider
{
public function register() {}
public function boot(Manager $breadcrumbs)
{
$breadcrumbs->register(...);
}
}
The breadcrumbs Manager
class is macroable,
so you can add your own methods. For example:
Breadcrumbs::macro('pageTitle', function () {
$title = ($breadcrumb = Breadcrumbs::current()) ? "{$breadcrumb->title} – " : '';
if (($page = (int) request('page')) > 1) {
$title .= "Page $page – ";
}
return $title . 'Demo App';
});
<title>{{ Breadcrumbs::pageTitle() }}</title>
For more advanced customizations you can subclass Breadcrumbs\Manager
and/or Breadcrumbs\Generator
, then update the
config file with the new class name:
// Manager
'manager-class' => Diglactic\Breadcrumbs\Manager::class,
// Generator
'generator-class' => Diglactic\Breadcrumbs\Generator::class,
(Note: Anything may change between releases. It's always a good idea to write unit tests to ensure nothing breaks when upgrading.)
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:
Breadcrumbs::macro('resource', function ($name, $title) {
// Home > Blog
Breadcrumbs::for("$name.index", function ($trail) use ($name, $title) {
$trail->parent('home');
$trail->push($title, route("$name.index"));
});
// Home > Blog > New
Breadcrumbs::for("$name.create", function ($trail) use ($name) {
$trail->parent("$name.index");
$trail->push('New', route("$name.create"));
});
// Home > Blog > Post 123
Breadcrumbs::for("$name.show", function ($trail, $model) use ($name) {
$trail->parent("$name.index");
$trail->push($model->title, route("$name.show", $model));
});
// Home > Blog > Post 123 > Edit
Breadcrumbs::for("$name.edit", function ($trail, $model) use ($name) {
$trail->parent("$name.show", $model);
$trail->push('Edit', route("$name.edit", $model));
});
});
Breadcrumbs::resource('blog', 'Blog');
Breadcrumbs::resource('photos', 'Photos');
Breadcrumbs::resource('users', 'Users');
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.
composer update diglactic/laravel-breadcrumbs
to upgrade.php artisan package:discover
to ensure the service provider is detected by Laravel.routes/breadcrumbs.php
by default).
dd(__FILE__)
in the file to make sure it's loaded.dd($files)
in ServiceProvider::registerBreadcrumbs()
to check the path is correct.php artisan config:clear
(or manually delete bootstrap/cache/config.php
) or update the
path in config/breadcrumbs.php
.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).php artisan config:clear
(or manually delete bootstrap/cache/config.php
) or update the path
in config/breadcrumbs.php
.{{ Breadcrumbs::render() }}
or {{ Breadcrumbs::view() }}
, not @include()
.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 Macros or Advanced customizations for ways to add them.)
The easiest way to work on Laravel Breadcrumbs is to tell Composer to install it from source (Git) using the
--prefer-source
flag:
rm -rf vendor/diglactic/laravel-breadcrumbs
composer install --prefer-source
Then checkout the master branch and create your own local branch to work on:
cd vendor/diglactic/laravel-breadcrumbs
git checkout -t origin/master
git checkout -b YOUR_BRANCH
Now make your changes, including unit tests and documentation (if appropriate). Run the unit tests to make sure everything is still working:
vendor/bin/phpunit -d --update-snapshots
Then commit the changes. Fork the repository on GitHub if you haven't already, and push your changes to it:
git remote add YOUR_USERNAME git@github.com:YOUR_USERNAME/laravel-breadcrumbs.git
git push -u YOUR_USERNAME YOUR_BRANCH
Finally, browse to the repository on GitHub and create a pull request.
To use your own fork in a project, update the composer.json
in your main project as follows:
{
// ADD THIS:
"repositories": [
{
"type": "vcs",
"url": "https://github.com/YOUR_USERNAME/laravel-breadcrumbs.git"
}
],
"require": {
// UPDATE THIS:
"diglactic/laravel-breadcrumbs": "dev-YOUR_BRANCH"
}
}
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.
To run the unit tests:
vendor/bin/phpunit -d --update-snapshots
To check code coverage:
vendor/bin/phpunit --coverage-html test-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.
The following files will need to be updated to run tests against a new Laravel version:
laravel/framework
(Laravel versions)php
(minimum PHP version)jobs.phpunit.strategy.matrix.laravel
(Laravel versions)jobs.phpunit.strategy.matrix.php
(PHP versions)jobs.phpunit.strategy.matrix.exclude
(Unsupported combinations)If changes are required, also update:
Laravel Breadcrumbs is open-sourced software licensed under the MIT license.