Breadcrumbs Bundle Laravel Package

Getting Started

Reality check for Laravel developers: whiteoctober/breadcrumbs-bundle is a Symfony2 bundle, not a Laravel package. It has no service provider, no config/breadcrumbs.php, and no Blade integration. The closest Laravel equivalent is diglactic/laravel-breadcrumbs (or davejamesmiller/laravel-breadcrumbs for older apps). Read this assessment with that in mind — you will be porting concepts, not installing this package into a Laravel app.

Status update (1.4.5): The package was archived in 2019, but 1.4.5 is a post-archive maintenance patch (it fixes the deprecated Twig spaceless tag, #110). Treat it as "lightly maintained again / patched in place," not "actively developed." It is still Symfony-2-era, still not a Laravel package, and still carries no security-fix guarantee you should rely on for anything long-lived.

If you are actually in a legacy Symfony2 project:

1. Require it: composer require whiteoctober/breadcrumbs-bundle (pin to a compatible Symfony 2.x constraint; 1.4.5 is the current patch line).
2. Register in app/AppKernel.php:

   new WhiteOctober\BreadcrumbsBundle\WhiteOctoberBreadcrumbsBundle(),
   

3. First use case — define a simple trail in a controller and render it in Twig:

   // Controller
   $breadcrumbs = $this->get('white_october_breadcrumbs');
   $breadcrumbs->addItem('Home', $this->generateUrl('homepage'));
   $breadcrumbs->addItem('Blog', $this->generateUrl('blog_index'));
   $breadcrumbs->addItem('Post'); // current page, no URL
   

   {# Twig template #}
   {{ wo_breadcrumbs() }}
   

4. Where to look first: WhiteOctober\BreadcrumbsBundle\Breadcrumbs (the service) and the white_october_breadcrumbs Twig extension. Those are the two public surfaces you will actually touch. For 1.4.5 specifically, also glance at the bundle's bundled Twig template — that is where the spaceless fix landed.

Implementation Patterns

Controller-defined trails (most common). Inject or fetch white_october_breadcrumbs, call addItem(label, url?, translationParameters?) in the order you want them rendered. This is the pattern to copy into a Laravel breadcrumb service — an ordered list of [label, url] tuples resolved per request.

Config-defined breadcrumbs. The bundle supports an app/config/breadcrumbs.yml style definition keyed by route, letting you declare trails declaratively and only add dynamic segments in the controller. This maps cleanly onto a Laravel routes/breadcrumbs.php file if you are porting.

Layout-level rendering. Render {{ wo_breadcrumbs() }} once in your base template so every page picks up whatever the controller defined (or nothing, producing empty output). Avoid rendering per-view unless you need different trail depth per page.

Custom Twig templates. Override the markup by passing a template: {{ wo_breadcrumbs({'template': 'AcmeBundle:Breadcrumbs:custom.html.twig'}) }}. This is your extension point for Bootstrap/Tailwind markup.

Twig-version compatibility (relevant to 1.4.5). The default template was updated to stop using the deprecated {% spaceless %} tag. If you have overridden the template, your copy is untouched — port the same fix yourself, since spaceless is removed outright in Twig 3. If you are on Twig 1.x, 1.4.5 is a drop-in, behaviour-neutral upgrade.

Translation-aware labels. addItem accepts translation parameters, so labels can be run through the translator with placeholders. In a Laravel port, wire this to __() instead.

Integration tips for a Laravel translation of the concept:

• Register a singleton breadcrumb generator bound to the request/route.
• Define trails in a dedicated routes/breadcrumbs.php file, loaded by a service provider.
• Use a Blade @breadcrumbs directive or a <x-breadcrumbs> component for rendering.
• Keep the "current page has no URL" convention — it drives the disabled/active state in your markup.

Gotchas and Tips

• Archived-then-patched. 1.4.5 shows the repo is receiving narrow compatibility patches again, but do not read that as a maintenance commitment. No security-fix SLA. For Symfony 4+, fork it as a bundle or migrate to a maintained alternative (davidmpaz/breadcrumbs-bundle or a modern equivalent).
• The 1.4.5 fix only covers the bundled template. Any template you pass to wo_breadcrumbs() that contains {% spaceless %} will still emit the deprecation (Twig 2.x) or break (Twig 3). Grep your own templates after upgrading.
• Patch-level upgrade only. 1.4.5 is a bugfix; no new API, no BC breaks. addItem() semantics, config keys, and the Twig function signature are unchanged — so there is no reason to hold back if you are already pinned to 1.4.x.
• Symfony-only, Twig-only. No Blade, no Laravel service provider, no container bindings you can reuse. Treat everything here as a design reference.
• addItem order is literal. There is no implicit "auto-generate from URL segments" behavior — you build the trail yourself, which is a feature (explicit > magic) but means any dynamic route needs controller work.
• Empty trail output. If a controller never calls addItem, wo_breadcrumbs() renders nothing — easy to think the extension is broken when it is just silent.
• Template/namespace resolution in custom templates. Custom Twig templates must live in a registered namespace (AcmeBundle:... in Symfony 2.x syntax). Wrong bundle name = empty or exception.
• Translator and separator configuration live in bundle config (white_october_breadcrumbs.separator and related keys) — check DependencyInjection/Configuration.php in the repo when in doubt, since docs are thin.
• Debugging tip: dump $breadcrumbs->getItems() (or the service in a container-aware context) before rendering to confirm the trail exists; most "it doesn't render" reports are actually "nothing was added." After a Twig bump, a deprecation in the log pointing at spaceless means you are either on <1.4.5 or using a stale custom template.
• Porting to Laravel: mirror the API surface (addItem($label, $url = null), render()) inside a small service class so controller code reads almost identically — this package's API is its main reusable asset.