Laravel Breadcrumbs

A simple Laravel-style way to create breadcrumbs in Laravel 4.

Installation

1. Install with Composer

composer require davejamesmiller/laravel-breadcrumbs dev-master

This will update composer.json and install it into the vendor/ directory.

Note: dev-master is the latest development version. See the Packagist website for a list of other versions.

2. Add to app/config/app.php

    'providers' => array(
        // ...
        'DaveJamesMiller\Breadcrumbs\BreadcrumbsServiceProvider',
    ),

And:

    'aliases' => array(
        // ...
        'Breadcrumbs'     => 'DaveJamesMiller\Breadcrumbs\Facades\Breadcrumbs',
    ),

This registers the package with Laravel and creates an alias called Breadcrumbs.

Usage

1. Define breadcrumbs in app/breadcrumbs.php

Create a file called app/breadcrumbs.php to put your breadcrumbs in. This file will be loaded automatically.

It should look something like this - see the Defining breadcrumbs section below for an explanation.

<?php
//Breadcrumbs::setView('_partials/breadcrumbs');

Breadcrumbs::register('home', function($breadcrumbs) {
    $breadcrumbs->push('Home', route('home'));
});

Breadcrumbs::register('blog', function($breadcrumbs) {
    $breadcrumbs->parent('home');
    $breadcrumbs->push('Blog', route('blog'));
});

Breadcrumbs::register('category', function($breadcrumbs, $category) {
    $breadcrumbs->parent('blog');

    foreach ($category->ancestors as $ancestor) {
        $breadcrumbs->push($ancestor->title, route('category', $ancestor->id));
    }

    $breadcrumbs->push($category->title, route('category', $category->id));
});

Breadcrumbs::register('page', function($breadcrumbs, $page) {
    $breadcrumbs->parent('category', $page->category);
    $breadcrumbs->push($page->title, route('page', $page->id));
});

2. Create a template that renders the breadcrumbs (optional)

This step is optional - by default, a Twitter Bootstrap-compatible unordered list will be rendered.

If you want to customise the HTML that is output, uncomment the Breadcrumbs::setView() line in app/breadcrumbs.php above and create your own view file (e.g. app/views/_partials/breadcrumbs.blade.php) like this:

@if ($breadcrumbs)
    <ul class="breadcrumb">
        @foreach ($breadcrumbs as $breadcrumb)
            @if (!$breadcrumb->last)
                <li>
                    <a href="{{{ $breadcrumb->url }}}">{{{ $breadcrumb->title }}}</a>
                    <span class="divider">/</span>
                </li>
            @else
                <li class="active">
                    {{{ $breadcrumb->title }}}
                </li>
            @endif
        @endforeach
    </ul>
@endif

As you can see above it will receive an array called $breadcrumbs. Each breadcrumb is an object with the following keys:

• title - The title you set above
• url - The URL you set above
• first - true for the first breadcrumb, false otherwise
• last - true for the last breadcrumb, false otherwise

3. Output the breadcrumbs in your view

Finally, call Breadcrumbs::render() in the view template for each page, passing in the name of the page and any parameters you defined above.

For example, with Blade:

{{ Breadcrumbs::render('home') }}
or
{{ Breadcrumbs::render('category', $category) }}

Or you can assign them to a section to be used in the layout:

@section('breadcrumbs', Breadcrumbs::render('category', $category))

(Then in the layout you would call @yield('breadcrumbs').)

Or if you aren't using Blade you can use regular PHP instead:

<?= Breadcrumbs::render('category', $category) ?>

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:

Breadcrumbs::register('home', function($breadcrumbs) {
    $breadcrumbs->push('Home', route('home'));
});

As you can see, you simply call $breadcrumbs->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') (URL::route())
• action('controller@action') (URL::action())
• Or just pass a string URL ('http://www.example.com/')

This example would be rendered like this:

Home

Parent links

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

Breadcrumbs::register('blog', function($breadcrumbs) {
    $breadcrumbs->parent('home');
    $breadcrumbs->push('Blog', route('blog'));
});

It would be rendered like this:

Home / Blog

Dynamic titles and links

This is a dynamically generated page pulled from the database:

Breadcrumbs::register('page', function($breadcrumbs, $page) {
    $breadcrumbs->parent('blog');
    $breadcrumbs->push($page->title, route('page', $page->id));
});

The $page variable would simply be passed in from the view:

{{ Breadcrumbs::render('page', $page) }}

It would be rendered like this:

Home / Blog / Page Title

Tip: You can pass multiple parameters if necessary.

Nested categories

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

Breadcrumbs::register('category', function($breadcrumbs, $category) {
    $breadcrumbs->parent('blog');

    foreach ($category->ancestors as $ancestor) {
        $breadcrumbs->push($ancestor->title, route('category', $ancestor->id));
    }

    $breadcrumbs->push($category->title, route('category', $category->id));
});

Alternatively you could make a recursive function such as this:

Breadcrumbs::register('category', function($breadcrumbs, $category) {
    if ($category->parent)
        $breadcrumbs->parent('category', $category->parent);
    else
        $breadcrumbs->parent('blog');

    $breadcrumbs->push($category->title, route('category', $category->slug));
});

Both would be rendered like this:

Home / Blog / Grandparent Category / Parent Category / Category Title

Advanced usage

Defining breadcrumbs in a different file

If you don't want to use app/breadcrumbs.php, you can define them in routes.php, start/global.php, or any other file as long as it's loaded by Laravel.

Switching views dynamically

If you need different views in different templates, you can call Breadcrumbs::generate() to get the $breadcrumbs array and then load the view manually:

@include('_partials/breadcrumbs2', array('breadcrumbs' => Breadcrumbs::generate('category', $category)))

or

{{ View::make('_partials/breadcrumbs2', array('breadcrumbs' => Breadcrumbs::generate('category', $category))) }}

Changelog

1.0.0

• Initial release

Thanks to

This is largely based on the Gretel plugin for Ruby on Rails, which I used for a while before Laravel lured me back to PHP.

License

MIT License. See LICENSE.txt.

Alternatives

So far I've only found one other breadcrumb package for Laravel:

• noherczeg/breadcrumb