robertboes/inertia-breadcrumbs

Laravel package to automatically share breadcrumbs to Inertia

0.7.0-beta 2024-11-05 14:19 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^10.0|^11.0
• inertiajs/inertia-laravel: ^1.0|^2.0
• spatie/laravel-package-tools: ^1.11.0

Requires (Dev)

• composer/composer: ^2.1
• diglactic/laravel-breadcrumbs: ^8.0|^9.0
• glhd/gretel: ^1.7
• larastan/larastan: ^2.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^7.0|^8.0
• orchestra/testbench: ^8.0|^9
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^10.0|^11
• spatie/laravel-ray: ^1.28
• spatie/ray: ^1.33
• tabuna/breadcrumbs: ^4.0

Suggests

• diglactic/laravel-breadcrumbs: Manage and configure breadcrumbs with diglactic/laravel-breadcrumbs
• glhd/gretel: Manage and configure breadcrumbs with glhd/gretel
• tabuna/breadcrumbs: Manage and configure breadcrumbs with tabuna/breadcrumbs

Conflicts

• orchestra/testbench-core: >=9,<9.0.14

MIT

• Robert Boes

• breadcrumbs
• laravel
• inertiajs
• robertboes
• inertia-breadcrumbs

README

This package automatically shares breadcrumbs as Inertia props in a standardized way, with support for multiple breadcrumb packages.

Installation

You can install the package via composer:

composer require robertboes/inertia-breadcrumbs

You can publish the config file with:

php artisan vendor:publish --tag="inertia-breadcrumbs-config"

Next step is to install one of the following packages to manage your breadcrumbs:

• diglactic/laravel-breadcrumbs
• tabuna/breadcrumbs
• glhd/gretel

Configure your breadcrumbs as explained by the package

Update your config/inertia-breadcrumbs.php configuration to use the correct collector:

// diglactic/laravel-breadcrumbs
use RobertBoes\InertiaBreadcrumbs\Collectors\DiglacticBreadcrumbsCollector;

return [
    'collector' => DiglacticBreadcrumbsCollector::class,
];

// tabuna/breadcrumbs
use RobertBoes\InertiaBreadcrumbs\Collectors\TabunaBreadcrumbsCollector;

return [
    'collector' => TabunaBreadcrumbsCollector::class,
];

// glhd/gretel
use RobertBoes\InertiaBreadcrumbs\Collectors\GretelBreadcrumbsCollector;

return [
    'collector' => GretelBreadcrumbsCollector::class,
];

Usage

No matter which third party package you're using, this package will always share breadcrumbs to Inertia in the following format:

[
    {
        "title": "Dashboard",
        "url": "http://localhost/dashboard"
    },
    {
        "title": "Profile",
        "url": "http://localhost/dashboard/profile",
        "current": true
    },
    {
        "title": "Breadcrumb without URL"
    }
]

Note

Note that due to package differences, URLs are always present when using glhd/gretel, but are otherwise optional.

An example to render your breadcrumbs in Vue 3 could look like the following:

<template>
    <nav v-if="breadcrumbs">
        <ol>
            <li v-for="page in breadcrumbs">
                <div>
                    <span v-if="page === '/'">/</span>
                    <a
                        v-else-if="page.url"
                        :href="page.url"
                        :class="{ 'border-b border-blue-400': page.current }"
                    >{{ page.title }}</a>
                    <span v-else>{{ page.title }}</span>
                </div>
            </li>
        </ol>
    </nav>
</template>

<script>
import { usePage } from '@inertiajs/inertia-vue3'
import { computed } from 'vue'

export default {
    setup() {
        // Insert an element between all elements, insertBetween([1, 2, 3], '/') results in [1, '/', 2, '/', 3]
        const insertBetween = (items, insertion) => {
            return items.flatMap(
                (value, index, array) =>
                    array.length - 1 !== index
                        ? [value, insertion]
                        : value,
            )
        }

        const breadcrumbs = computed(() => insertBetween(usePage().props.value.breadcrumbs || [], '/'))

        return {
            breadcrumbs,
        }
    },
}
</script>

Using a classifier

A classifier is used to determine when breadcrumbs should be shared as Inertia props. By default all breadcrumbs are shared, but this package is shipped with the IgnoreSingleBreadcrumbs classifier, which simply discards a breadcrumb collection containing only one route.

To write your own classifier you'll have to implement RobertBoes\InertiaBreadcrumbs\BreadcrumbCollection\ClassifierContract and update the inertia-breadcrumbs.classifier config, for example:

<?php

namespace App\Support;

use Illuminate\Support\Str;
use RobertBoes\InertiaBreadcrumbs\Classifier\ClassifierContract;
use RobertBoes\InertiaBreadcrumbs\BreadcrumbCollection;

class IgnoreAdminBreadcrumbs implements ClassifierContract
{
    public function shouldShareBreadcrumbs(BreadcrumbCollection $collection): bool
    {
        return ! Str::startsWith($collection->first()->url(), '/admin')''
    }
}

Serializing breadcrumbs

In some cases you might not like the default way breadcrumbs are serialized. To modify the way the breadcrumbs are being sent to the frontend you can register a serialize callback in the boot method of a service provider:

<?php

namespace App\Providers;

use RobertBoes\InertiaBreadcrumbs\InertiaBreadcrumbs;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        InertiaBreadcrumbs::serializeUsing(fn (Breadcrumb $breadcrumb) => [
            'name' => $breadcrumb->title(),
            'href' => $breadcrumb->url(),
            'active' => $breadcrumb->current(),
            'data' => $breadcrumb->data(),
        ]);
    }
}

Including the query string when determining the current URL

By default, the query string will be ignored when determining the current url, meaning a breadcrumb defined for /users/{id} will match both /users/1 and /users/1?foo=bar. To change this behaviour and include the query string (meaning /users/1?foo=bar will not be seen as the current page), change ignore_query to false in the config/inertia-breadcrumbs.php file.

Notes on using glhd/gretel

glhd/gretel shares the breadcrumbs automatically if it detects Inertia is installed and shares the props with the same key (breadcrumbs). If you want to use this package with gretel you should disable their automatic sharing by updating the config:

// config/gretel.php

return [
    'packages' => [
        'inertiajs/inertia-laravel' => false,
    ],
];

Testing

composer test

Upgrading

For notable changes see UPGRADING.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Robert Boes
• All Contributors

License

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