Breadcrumb Kit Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. There is no extra.laravel block, no package auto-discovery, no Blade views, and no Artisan publishable config. The first decision is where it runs:

• In a Symfony app: composer require nowo-tech/breadcrumb-kit-bundle, then register it in config/bundles.php (use the PSR-4 namespace from the package's composer.json — likely Nowo\BreadcrumbKitBundle\BreadcrumbKitBundle), and confirm the real config surface with:

  php bin/console config:dump-reference <bundle_alias>
  

  That dump is the single best "look here first" reference for this package, since the repo is young and documentation may lag.
• In a Laravel app: don't expect php artisan vendor:publish. Run composer require, then open vendor/nowo-tech/breadcrumb-kit-bundle/src and look for the trail resolver service and its config array. The route-matching and label resolution logic is usually a small, framework-agnostic service you can bind into Laravel's container; the Twig functions, DI extension, and compiler passes will not load.

First use case (either framework): a trail under the page header — Home > Section > Current page. Define 2–3 route patterns in config, pick the trail for the current request, and render it as a single collection call. Verify the resolved trail array before wiring any template, e.g. dump the resolver output for a known route.

Implementation Patterns

• Route-name-driven definitions. Key trails off route names (with parameter placeholders), not URLs. Renaming a route then breaks exactly one config entry instead of silently degrading every template. Reserve URL matching for legacy or external paths.
• Translate at render, not at config load. Put translation keys (page.section.title) in config and resolve them in the template/collection renderer. Never call trans() from inside a config closure — container compilation may run without a request locale.
• Optional links as a first-class case. The leaf crumb is usually text, not a link; so are gated/archived nodes. Model url: null explicitly and make your template branch on it rather than emitting href="".
• Collection-level presentation. Render the whole breadcrumb in one call and let the bundle own separators, home crumb, and (if offered) BreadcrumbList JSON-LD. Resist building the trail in the template — you lose i18n and the null-link handling.
• Wrap it once. Add an app-level BreadcrumbBuilder interface with the bundle behind it. Your templates depend on Breadcrumb[] (label, url, active), so you can swap the bundle later without touching views.
• Laravel mirror pattern. If you do adapt it: bind a resolver service that reads config('breadcrumbs.trails'), register a Breadcrumb facade, and render through a Blade component that reproduces the bundle's emitted markup (class names, aria-current="page", <ol>/<ul> list). Cache resolved trails per route+params when trails are static — they're pure functions of route and locale.
• Nesting. Use parent keys to compose sub-sections (admin. prefix, admin.users.), so section crumbs inherit rather than repeat.

Gotchas and Tips

• Framework mismatch is the main risk. Bundle service IDs, the Twig extension, and the compiler pass won't autoload in Laravel. Call the underlying service; never call the Twig extension from application code.
• Route renames fail silently. A crumb whose pattern no longer matches typically just disappears. Add a test that iterates your configured patterns and asserts each one resolves for a real route — this catches it at CI time.
• Locale in config closures. Symfony config is often evaluated during container compilation. If you need request-dependent labels, keep them as keys and defer translation.
• Cache freezing. In Symfony, clear the container cache after config changes (bin/console cache:clear). In Laravel, config:cache bakes whatever you read at boot — make sure nothing locale- or request-dependent is captured there.
• Debugging order. Dump the resolver/trail object first, then check the rendered collection, then the HTML. Most "missing breadcrumb" reports are a non-matching route pattern, not a template bug.
• Low bus factor: 0 stars, 0 dependents, single release line. Pin an exact version in composer.json, vendor the template, check CHANGELOG.md/UPGRADING.md for a BC policy, and keep the wrapper interface so replacement is a config change.
• Preferred extension points: decorators around the trail resolver and extra config entries — not modifications to the DI extension or compiler passes, which are the pieces most likely to change between releases.
• Testing: one unit test asserting trail contents (labels, urls, order, null-link flags) for a representative route, plus one request-level test confirming the trail appears on the page. That covers the realistic failure modes without coupling to bundle internals.