Breadcrumb Widget Laravel Package

Getting Started

First, the honest framing: this is a Symfony bundle (WidgetBreadcrumbBundle) that plugs a breadcrumb widget into Victoire DCMS, a Symfony-based CMS. It is not a Laravel package — there is no service provider, no Blade views, no config/*.php to publish. For a Laravel developer, the practical value is as a reference implementation you may port, not a dependency you install. Adding it to a Laravel composer.json will pull Symfony/Victoire constraints you cannot satisfy.

If you are actually on Symfony + Victoire:

1. composer require friendsofvictoire/breadcrumb-widget (verify the exact package name in the repo's composer.json — the repo name and Packagist name often differ for these bundles).
2. Register the bundle in app/AppKernel.php (Symfony 2/3 era) or config/bundles.php (Symfony 4+), following whatever the repo's README shows.
3. Clear the cache (bin/console cache:clear) and open a page in Victoire's edit mode.
4. Add the Breadcrumb widget into a template zone, typically the header area.
5. Override the bundled Twig template so the markup matches your theme.

Where to look first, in this order:

• composer.json — tells you the Symfony and Victoire version pins. This is the single most important file; it usually decides whether the bundle is even installable for you.
• The bundle class (*Bundle.php) — registration and any compiler passes.
• The widget class — what data source it uses (Victoire page/menu hierarchy, most likely) and what it passes to the view.
• Resources/views/** — the Twig template you will override. This is where 90% of your day-to-day changes happen.
• Resources/config/ — service definitions and widget tags.

First use case: drop the widget into a page template header so DCMS-rendered pages automatically show a trail derived from the page hierarchy, then theme it via a Twig override. That is the entire intended usage.

Implementation Patterns

Editor-driven placement. In Victoire, business users place widgets; developers register them and control presentation. Your job is (a) make the widget appear in the editor and (b) make its output match the design. Do not build page-specific breadcrumb logic in PHP if a template override can do it.

Template override over code changes. The standard Symfony cascade applies: override the widget's Twig template in your app's templates/bundles/... directory (or app/Resources/... on older Symfony). This survives bundle updates and is the cheapest way to restyle, re-order separators, add icons, or add SEO markup.

Upgrade the markup while you're in there. These small CMS widgets almost never ship structured data. In your override, add:

• a <nav aria-label="Breadcrumb"> landmark,
• aria-current="page" on the last item,
• a BreadcrumbList JSON-LD block.

That is often a bigger win than the widget itself.

Custom trails. If your breadcrumb must reflect something other than the DCMS page tree (e.g. product → category → home), don't fight the widget. Either:

• inject your own data into the template via a Twig function/service, or
• write a small custom Victoire widget that reuses the same rendering pattern.

Subclassing the existing widget is possible but usually more coupling than it's worth.

Theming and translations. Style with your own CSS against the widget's class names; override translation files for labels ("Home", "You are here"). Keep separator characters in CSS (::after) rather than in the template so designers can change them without touching Twig.

Caching. Victoire caches rendered widgets with the page. If your breadcrumb depends on request state (locale, query params, authenticated user), verify the cache key or you will serve stale trails. Test with the cache enabled, not just in dev.

Porting to Laravel (the realistic path). If your goal is "I saw this and want it in Laravel," don't bridge it. Reimplement:

• a Breadcrumb service that takes a stack of [label, url] pairs,
• a Blade component <x-breadcrumb :items="$items" />,
• a composer/view composer that builds the stack from route names or model ancestry.

That's roughly 50 lines and gives you full control, testing, and no Symfony coupling.

Gotchas and Tips

• Zero stars, zero dependents. Treat this as unmaintained. No security response, no issue triage, likely no docs beyond a README. If you adopt it, fork it into your own VCS and pin the fork.
• Version lock is the killer. Victoire-era bundles target Symfony 2/3 and old PHP. They will not install on Symfony 5/6 or PHP 8 without patching. Check composer.json before spending any time.
• Not Laravel-compatible, period. No service provider, no Blade, no publishable config/assets. Do not add it to a Laravel project hoping for a quick breadcrumb; you will spend more time removing it than writing your own.
• Silent widget absence. Victoire discovers widgets via service tags/config. If the widget doesn't show in the editor, the usual cause is a missing tag or an unregistered bundle — and it fails quietly. Check debug:container for the widget service and its tags.
• Template path mismatches fall back silently. If your override path is wrong, Twig renders the bundle's default template with no warning. Confirm with debug:twig that your override is the one being resolved.
• Cache everywhere. After changing a Twig template or translation, clear the Symfony cache and re-save/clear the DCMS page cache. Half of "my change didn't apply" reports are cache.
• Debugging. Use the Symfony profiler's Twig panel to see which template rendered and what variables were passed. dump() in Twig or a temporary {{ dump() }} is faster than guessing at the widget's data shape.
• Extension points, in order of preference: Twig template override → bundle inheritance → subclass the widget → event subscriber. Only move down that list when the layer above genuinely can't express what you need.
• Accessibility and SEO are on you. The default markup is unlikely to include a nav landmark, aria-current, or structured data. Budget an hour to add them in the override.
• Recommendation: if you are on Victoire already, this is a small, low-risk convenience — fork and pin it. If you are on Laravel or greenfield Symfony, skip it and write the ~50-line breadcrumb yourself; you'll get better markup, tests, and zero legacy constraints.