Breadcrumbs Bundle Laravel Package

Getting Started

This one needs a framing note before anything else: rollerworks/breadcrumbs-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no facade, no config/breadcrumbs.php, and it does not ship a Composer extra.laravel block. v0.1.4 is a single Symfony 4 compatibility fix, which tells you where the maintainers' attention is pointed — the Symfony DI container, not Laravel's.

So "getting started" splits into two realistic paths.

Path A — you actually want it in a Laravel app (rare, and you should justify it). The only sane route is to pull in the underlying crumb-building logic rather than the bundle. Install it for inspection, not for wiring:

composer require rollerworks/breadcrumbs-bundle --dev

Then read vendor/rollerworks/breadcrumbs-bundle/ — specifically the builder/factory services and the Resources/config/ service definitions — and port the crumb-resolution idea into your own BreadcrumbService. Expect to rewrite, not integrate: the bundle's assumptions (Twig extension, Symfony routing RouterInterface, tagged services, container-compiled config tree) do not map onto Laravel's container without shims.

Path B — you're in a Symfony codebase alongside Laravel work. Then this is a normal install:

composer require rollerworks/breadcrumbs-bundle

Register the bundle in config/bundles.php, and confirm you are on Symfony 4.x — that is precisely what 0.1.4 unblocks.

Where to look first: the bundle's config tree definition and its Twig extension. Those two files tell you the entire mental model faster than any README: crumbs are declared as config, resolved by route, and rendered by Twig.

First use case: a static-ish breadcrumb trail for a content hierarchy (Home › Section › Article) where the trail is derivable from the current route plus one or two parameters — product page from a category slug, article from a section slug. That is the sweet spot. If your trail is highly dynamic or permission-dependent per user, you will fight the config-driven design.

Implementation Patterns

Config-driven trails, one set per area. The bundle's core idiom is a named breadcrumb set declared in YAML: each crumb has a label, a route, and optional route parameters. Multiple sets let you define shop and blog trails independently and pick between them per controller or per template. In Laravel terms, think of it as a config file of named route-based trails — closer to a menu builder than to a runtime API.

Route-parameter interpolation is the pattern that earns its keep. The value here is that a crumb's label and route params can be derived from the current request rather than hard-coded. A single set definition serves /category/{slug}/product/{id} for every product, with no per-controller code. If you replicate anything in Laravel, replicate this: define the trail shape once, resolve the dynamic parts from the route.

Render at the layout level, not the controller. The Twig extension renders the trail; breadcrumbs belong in the layout partial so every page gets them without controller plumbing. The Laravel analogue is a Blade component reading from a Breadcrumbs singleton populated by middleware or a route-model-binding-aware resolver — do not hand $breadcrumbs into every view.

Integration tip for mixed codebases: if you have a Laravel app and a Symfony app sharing a design system, keep the markup contract (a <nav aria-label="Breadcrumb"> with an ordered list, last item non-linked) identical on both sides and reimplement the builder per framework. Do not attempt to share the bundle's objects across the boundary — the service definitions are container-compiled and will not survive.

Version pinning matters here. v0.1.x is pre-1.0 with an unstable API. Pin exactly (0.1.4), not ^0.1, and read the diff before bumping. A patch-level release in this series changed framework compatibility, which is a lot of blast radius for a third component.

Gotchas and Tips

v0.1.4 is a compatibility patch, not a feature release. The entirety of it is a Symfony 4 fix from an outside contributor. Practical read: the supported Symfony range shifted, so verify your symfony/framework-bundle constraint resolves cleanly and re-run your container compile (bin/console cache:clear, then a warmup) after upgrading. In a Symfony 4 app you were likely broken before this; in a Symfony 2/3 app, test before assuming nothing moved.

Nothing here is Laravel-tested. The Symfony 4 fix is exactly the kind of change that says "the maintainers are tracking one framework." Expect zero consideration for Laravel's container semantics, Illuminate\Routing, or Blade. Any Laravel usage is unsupported and yours to own.

Pre-1.0 API churn. At 0.1.x, class names and config keys can move in a patch release. Wrap the bundle behind your own thin renderer/twig-extension call so an upgrade touches one file, not fifty templates. This is cheap insurance and pays off on the next 0.1.x bump.

Config tree caching bites in dev. Symfony compiles bundle config into the container cache. Changing breadcrumb definitions in YAML without clearing the cache produces "my edit did nothing" confusion — a classic. Always clear before debugging why a crumb is stale.

Label translation is a common surprise. Crumbs usually pass through the translator; if a label renders as a raw key (e.g. breadcrumb.shop), that is a missing translation domain/message, not a bundle bug. Check the domain configured for the set.

Debugging strategy: dump the resolved crumb collection at the Twig extension boundary rather than inside the builder. The builder runs during rendering and failures there surface as template exceptions with unhelpful stacks; a dump() on the final array isolates whether the problem is definition (nothing matched the route) or rendering.

Extension points are the real reason to use it. The tagged-service design lets you swap the builder or the factory via the container if you need a custom resolution strategy (permissions, feature flags, per-locale trails). Before forking, check whether your need is already a service override — it usually is, and it survives upgrades better than a fork.

When to skip it entirely: if you are in Laravel, use a small purpose-built service plus a Blade component. You will write ~80 lines, own the code, and avoid a Symfony-container dependency in an artisan-served app. This bundle's value proposition is strongest precisely where Laravel is absent.