README

Breadcrumb navigation management for Symfony applications.

This bundle provides a simple, flexible way to define and render breadcrumbs in Symfony 7.3+ using KnpMenu and Twig. It ships with a configuration system, ready‑to‑use templates, and translations to help you get productive quickly.

Compatible with: Symfony 7.3+ and PHP 8.3+
Depends on: symfony/framework-bundle, symfony/translation, twig/twig, knplabs/knp-menu-bundle

Installation

1) With Symfony Flex (recommended)

composer require kayrault/breadcrumb-bundle

Flex will register this bundle and usually enable KnpMenuBundle, and wire services automatically.

Note: In some Symfony Flex setups, you may need to enable KnpMenuBundle manually in config/bundles.php (see the bundles.php snippet below).

2) Without Symfony Flex

Require the packages:

composer require kayrault/breadcrumb-bundle knplabs/knp-menu-bundle

Enable the bundles in config/bundles.php:

return [
    // ...
    Knp\Bundle\MenuBundle\KnpMenuBundle::class => ['all' => true],
    Kayrault\BreadcrumbBundle\KayraultBreadcrumbBundle::class => ['all' => true],
];

No additional service config is needed: the bundle ships its own service definitions and Twig path. The KnpMenuBundle must be enabled because this bundle registers its breadcrumb builder and renderer using KnpMenu services and tags.

Basic usage

The bundle exposes a KnpMenu builder and a renderer under the alias "kayrault_breadcrumb".

Menu builder service: Kayrault\BreadcrumbBundle\Menu\BreadcrumbBuilder
Renderer service: Kayrault\BreadcrumbBundle\Menu\BreadcrumbRenderer (KnpMenu renderer alias: kayrault_breadcrumb)

Declare your breadcrumb items per route (see Configuration below).
Render the breadcrumb in Twig:

{# e.g. templates/base.html.twig #}
{% if app.request %}
    {{ knp_menu_render('kayrault_breadcrumb', {}, 'kayrault_breadcrumb') }}
{% endif %}

Include the stylesheet in your base layout so the breadcrumb renders with the default styles:

{# e.g. templates/base.html.twig, in your <head> block #}
<link rel="stylesheet" href="{{ asset('bundles/kayraultbreadcrumb/assets/styles/breadcrumb.css') }}">

This will use the bundle template @KayraultBreadcrumb/menu/breadcrumb.html.twig by default.

Programmatic building

This bundle focuses on configuration-driven breadcrumbs. If you need to build or manipulate menus programmatically, please use KnpMenuBundle directly (see https://github.com/KnpLabs/KnpMenuBundle for documentation).

Configuration

Define your breadcrumbs per route under the kayrault_breadcrumb root key. Each route contains an items list. Each item can be translated and optionally linked to a route.

# config/packages/kayrault_breadcrumb.yaml
kayrault_breadcrumb:
  # Optional: configure the Home entry (added automatically as the first item)
  home_route: 'app_home'
  home_label: 'kayrault_breadcrumb.common.home'
  home_translatable: true
  home_translation_domain: 'KayraultBreadcrumbBundle'

  routes:
    app_dashboard:
      items:
        - { label: 'Dashboard', translatable: true, translation_domain: 'messages' }
    app_article_show:
      items:
        - { label: 'menu.articles', translatable: true, translation_domain: 'messages', route: 'app_article_index' }
        - label: 'article.show'
          translatable: true
          translation_domain: 'messages'
          translation_parameters:
            - { key: '%name%', value: 'Acme' }

Notes:

The builder adds a "home" item by default. You can customize it with the home_* options above. If home_translatable is true, the label is translated using home_translation_domain.
Item fields:
- label (string, required)
- route (string|null)
- translatable (bool, default: true)
- translation_domain (string|null, default: messages when translatable)
- translation_parameters (list of key/value pairs)

Assets and templates

Default template: @KayraultBreadcrumb/menu/breadcrumb.html.twig
Optional CSS provided at public/assets/styles/breadcrumb.css (publish or import in your asset pipeline if desired).

Documentation

Full documentation lives in the docs/ folder of this repository. Start with docs/ to explore advanced usage, template overrides, and customization.

Contributing

Contributions are welcome! Please:

Follow PSR-12 and Symfony coding standards.
Run quality tools before opening a PR:
- PHP Lint & CS: vendor/bin/php-cs-fixer fix --diff
- Twig CS: vendor/bin/twig-cs-fixer lint templates --diff (see https://github.com/vincentlanglet/Twig-CS-Fixer)
- Static analysis: vendor/bin/phpstan analyse
Describe your change and include tests when applicable.

License

This bundle is released under the MIT License. See the LICENSE file for details.

kayrault / breadcrumb-bundle

Maintainers

Details