azri / symfony-breadcrumb
Symfony bundle for easy setup of breadcrumbs
Installs: 38
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 1
Open Issues: 0
Type:symfony-bundle
Requires
- php: >=8.0
- symfony/framework-bundle: 6.1.*
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.11
- phpunit/phpunit: ^9.5
- twig/twig: ^3.0
Suggests
- twig/twig: To render breadcrumbs with a twig template
This package is auto-updated.
Last update: 2024-04-13 04:44:01 UTC
README
Introduction
This Symfony bundle provides integration of breadcrumbs via route config and rendering in your Twig templates. This bundle is heavily inspired by the inactive thormeier/breadcrumb-bundle
Requirements
Symfony >= 6.0.*
php >= 8.0
Installation
Step 1: Composer require
$ composer require azri/symfony-breadcrumb
Step2: Enable the bundle in the kernel
<?php
// config/bundles.php
return [
// ...
Azri\BreadcrumbBundle\AzriBreadcrumbBundle::class => ['all' => true],
];
Configuration
Enable the bundle in your config/azri_breadcrumb.yaml:
# config/azri_breadcrumb.yaml
azri_breadcrumb: ~
The template defaults to a very basic one, providing a <ul>
with <li>
and <a>
for every breadcrumb.
Usage
Basic
A breadcrumb tree is created by the fields label
and parent_route
in the defaults
of a route. Basic tree example:
# routing.yml
acme_demo_home:
path: /
options:
breadcrumb:
label: Home
acme_demo_contact:
path: /contact
options:
breadcrumb:
label: Contact
parent_route: acme_demo_home
acme_demo_catalogue:
path: /catalogue
options:
breadcrumb:
label: 'Our Catalogue'
parent_route: acme_demo_home
acme_demo_catalogue_categories:
path: /catalogue/categories
options:
breadcrumb:
label: 'All categories'
parent_route: acme_demo_catalogue
Would result in a breadcrumb tree like:
acme_demo_home
|- acme_demo_contact
`- acme_demo_catalogue
`- acme_demo_catalogue_categories
If the current route is acme_demo_catalogue
, the breadcrumbs would for instance show the following:
Home > Our Catalogue
Since the configuration of the breadcrumbs happens on routing config, it's generally agnostic from how the routing configuration happens. This means that configuring breadcrumbs for instance via annotations is perfectly possible:
/**
* ...
* @Route(
* "/contact",
* name="acme_demo_contact",
* options={
* "breadcrumb" = {
* "label" = "Contact",
* "parent_route" = "acme_demo_home"
* }
* })
* ...
*/
#[Route(
'/contact',
name: 'acme_demo_contact',
options: [
'breadcrumb' => [
'label' => 'Contact',
'parent_route' => 'acme_demo_home'
]
],
)]
The configuration can also be done in XML and PHP.
Dynamic routes
If you happen to have dynamic routes or dynamic translations that you need in your breadcrumbs, they can be defined like so:
# routing.yml
acme_demo_product_detail:
path: /products/{id}
options:
breadcrumb:
label: 'Produkt: %%name%%'
parent_route: acme_demo_catalogue
(This example uses a string with a placeholder in the routing directly. You can also define the label text in a translation file and only use the translation key as the label. The template will handle the translation and replacing.)
Notice the double %
to escape the parameter in the label. This needs to be done, because routing.yml
is being parsed by the Symfony container and recognizes constructs, such as %name%
as a container parameter
and tries to inject those. The double-%
escapes it, the template is handling the rest.
You can then set parameters for both directly on the Breadcrumb
object, for instance:
<?php
// MyController
use Azri\BreadcrumbBundle\Provider\BreadcrumbProviderInterface;
// ...
public function productDetailAction(BreadcrumbProviderInterface $breadcrumbProvider)
{
$product = ...;
// ...
$breadcrumbProvider
->getBreadcrumbByRoute('acme_demo_product_detail')
->setRouteParams([
'id' => $product->getId(),
])
->setLabelParams([
'name' => $product->getName(),
]);
// ...
}
Please note that the breadcrumb must be defined on the route in order to set parameters.
Dynamic breadcrumbs
If you happen to have a dynamic routing tree, for instance a tree of category pages that can go infinitely deep, you can add breadcrumbs that are not defined on a route on the fly. For instance like this:
<?php
use Azri\BreadcrumbBundle\Model\Breadcrumb;
// ...
// Route of the product, we want the categories before this
$productCrumb = $breadcrumbProvder->getBreadcrumbByRoute('acme_demo_product_detail');
$collection = $breadcrumbProvider->getBreadcrumbs();
foreach ($product->getCategories() as $category) {
$newCrumb = new Breadcrumb(
'Category: %name%', // Label
'acme_demo_category', // Route
['id' => $category->getId()], // Route params
['name' => $category->getName()] // Label params
);
// Adds $newCrumb right in front of $productCrumb
$collection->addBreadcrumbBeforeCrumb($newCrumb, $productCrumb);
// Or: ->addBreadcrumb(), ->addBreadcrumbAtPosition(), ->addBreadcrumbAfterCrumb(), ->addBreadcrumbToStart()
}
These breadcrumbs are not stored in the cache though.
Displaying in twig
Call the twig extension as following:
{# someTemplate.html.twig #}
{# ... #}
{{ breadcrumbs() }}
{# ... #}
Using the bootstrap template
The bundle also provides a default implementation for Bootstrap. It can be used as follows:
# config/azri_breadcrumb.yaml
azri_breadcrumb:
template: '@AzriBreadcrumb/breadcrumbs_bootstrap.html.twig'
Replacing the default template
If you want to use a custom template, add the following to your config/azri_breadcrumb.yaml
# config/azri_breadcrumb.yaml
azri_breadcrumb:
template: 'my twig template path'
Your custom breadcrumb template receives a variable called breadcrumbs
that is a collection that represents your
breadcrumbs, ordered by highest in the tree to lowest.
A single breadcrumb
has the fields route
, routeParameters
, label
and labelParameters
. route
and routeParameters
are used to generate a path in twig, i.e. path(breadcrumb.route, breadcrumb.routeParameters)
, whereas label
and
labelParameters
are used to generate the text for the breadcrumb, i.e.
{{ (breadcrumb.label)|trans(breadcrumb.labelParameters) }}
Your custom template might look something like this:
{# myBreadcrumbs.html.twig #}
<div>
{% for breadcrumb in breadcrumbs %}
<a href="{{ path(breadcrumb.route, breadcrumb.routeParameters) }}">
{{ breadcrumb.label|replace({"%%": "%"})|trans(breadcrumb.labelParameters) }}
</a>
{% endfor %}
</div>
The replacing of %%
with single %
happens inside the template. See "Dynamic routes" as why this is needed.
Have a look at Resources/views/breadcrumbs.html.twig
and Resources/views/breadcrumbs_bootstrap.html.twig
to see the default implementations.
Customize implementations
The model class and/or its collection can be replaced by own implementations, that implement the
Azri\BreadcrumbBundle\Model\BreadcrumbInterface
and
Azri\BreadcrumbBundle\Model\BreadcrumbCollectionInterface
:
# config/azri_breadcrumb.yaml
azri_breadcrumb:
model_class: 'Acme\Breadcrumbs\Model\MyModel'
collection_class: 'Acme\Breadcrumbs\Model\MyCollection'
The provider service ID can be replaced by setting the parameter provider_service_id
# config/azri_breadcrumb.yaml
azri_breadcrumb:
provider_service_id: acme.breadcrumbs.my_provider
Caching
This bundle uses the routing cache to store breadcrumb lists per route on cache:warmup
. They are then turned into
a BreadcrumbCollection
on demand.