README

Breadcrumbs management and rendering for Symfony applications, maintained by InSquare under the MIT License.

The source lineage and base revision are documented in FORK_ORIGIN.md.

Requirements

PHP 8.2 or newer
Symfony 7.4 or 8.x
Twig 3.x

Installation

Install the stable 1.x release:

composer require in-square/breacrumbs-bundle:^1.0

<?php

return [
    InSquare\BreadcrumbsBundle\InSquareBreadcrumbsBundle::class => ['all' => true],
];

Create config/packages/in_square_breadcrumbs.yaml:

in_square_breadcrumbs: ~

The package currently has no Symfony Flex recipe, so bundle registration and configuration are manual.

Basic usage

Inject Breadcrumbs into the controller action or constructor. Generate URLs through Symfony's router instead of retrieving services from the container:

<?php

use InSquare\BreadcrumbsBundle\Model\Breadcrumbs;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

public function show(
    User $user,
    Breadcrumbs $breadcrumbs,
    UrlGeneratorInterface $urlGenerator,
): Response {
    $breadcrumbs->addItem('Home', $urlGenerator->generate('homepage'));
    $breadcrumbs->addItem('User profile', $urlGenerator->generate('user_show', [
        'id' => $user->getId(),
    ]));

    return $this->render('user/show.html.twig', ['user' => $user]);
}

The last breadcrumb is rendered as plain text. Earlier items are rendered as links when they have a URL.

Route-based items

The bundle can generate URLs directly from route names:

$breadcrumbs->addRouteItem('Home', 'homepage');
$breadcrumbs->addRouteItem('User profile', 'user_show', [
    'id' => $user->getId(),
]);
$breadcrumbs->prependRouteItem('Start', 'homepage');

Attributes

Breadcrumbs may also be declared on controllers and actions:

<?php

use InSquare\BreadcrumbsBundle\Attribute\Breadcrumb;

#[Breadcrumb(text: 'Home', route: 'homepage')]
final class UserController extends AbstractController
{
    #[Breadcrumb(
        text: 'Profile of {user.name}',
        route: 'user_show',
        parameters: ['id' => '{user.id}'],
    )]
    public function show(User $user): Response
    {
        // ...
    }
}

Twig

Render the default breadcrumb list:

{{ in_square_render_breadcrumbs() }}

Available Twig functions and filters:

in_square_breadcrumbs(namespace = 'default')
in_square_breadcrumbs_exists(namespace = 'default')
in_square_render_breadcrumbs(options = {})
in_square_is_final_breadcrumb filter

Options can be overridden for an individual render:

{{ in_square_render_breadcrumbs({
    separator: '>',
    listId: 'page-breadcrumbs',
}) }}

Configuration

All supported options and their defaults:

in_square_breadcrumbs:
    separator: '/'
    separatorClass: 'separator'
    listId: 'in-square-breadcrumbs'
    listClass: 'breadcrumb'
    itemClass: ''
    linkRel: ''
    locale: ~
    translation_domain: ~
    viewTemplate: '@InSquareBreadcrumbs/microdata.html.twig'

Use the bundled JSON-LD template when structured data should be emitted as a script instead of HTML microdata:

in_square_breadcrumbs:
    viewTemplate: '@InSquareBreadcrumbs/json-ld.html.twig'

Namespaces

Multiple independent breadcrumb collections can be maintained in one request:

$breadcrumbs->addNamespaceRouteItem('sidebar', 'Home', 'homepage');
$breadcrumbs->addNamespaceItem('sidebar', 'Current page');

Render the selected collection:

{{ in_square_render_breadcrumbs({namespace: 'sidebar'}) }}

Object collections and trees

Add a bounded array of objects:

$breadcrumbs->addObjectArray(
    $categories,
    'name',
    static fn (Category $category): string => $urlGenerator->generate(
        'category_show',
        ['slug' => $category->getSlug()],
    ),
);

Add an object's parent path:

$breadcrumbs->addObjectTree(
    $category,
    'name',
    static fn (Category $item): string => $urlGenerator->generate(
        'category_show',
        ['slug' => $item->getSlug()],
    ),
    'parent',
);

The caller is responsible for supplying a collection that is explicitly bounded and safe to process in memory.

Overriding templates

Copy Resources/views/microdata.html.twig to:

templates/bundles/InSquareBreadcrumbsBundle/microdata.html.twig

Alternatively, select a custom template per render:

{{ in_square_render_breadcrumbs({
    viewTemplate: 'breadcrumbs/custom.html.twig',
}) }}

Contributing

Issues and pull requests are welcome in in-square/breacrumbs-bundle. Contributors must follow the project Code of Conduct.

in-square / breacrumbs-bundle

Maintainers

Package info

Statistics

Security