Navigation Bundle Laravel Package

Getting Started

Before anything else: this is a Symfony bundle, not a Laravel package. There is no service provider, no facade, no config publishing. If you're evaluating it from a Laravel codebase, treat it as a reference implementation of the companion library rybakit/navigation, not something you composer require into a Laravel app.

First steps (if you're in a Symfony context):

composer require rybakit/navigation-bundle

Register the bundle in app/AppKernel.php (Symfony 2/3/4 era):

$bundles = [
    new Rybakit\Bundle\NavigationBundle\RybakitNavigationBundle(),
];

Then define your first navigation container in config.yml — the bundle is configuration-driven, so nothing renders until you declare at least one container. A minimal "main menu" container with a couple of items is the fastest way to see output.

Where to look first:

• The bundle's DependencyInjection/Configuration.php for the exact config schema (this is the source of truth — docs are thin).
• The Twig extension class for the render function name and options.
• The upstream rybakit/navigation README for item/container/matcher semantics, since the bundle just wires those into the container.

First use case: a top-nav or sidebar menu where one item is "active" depending on the current request. That's what the matcher system is for.

Implementation Patterns

Config-defined containers. The typical workflow is declaring navigation trees in YAML/PHP config rather than building them in controllers. Items get a label, URI, optional attributes, and optional children. This keeps menus out of PHP and lets non-devs edit them.

Rendering via Twig. The bundle exposes a Twig function (roughly {{ navigation('main') }}) that resolves the configured container service and hands it to a renderer. The renderer walks the tree and outputs markup — in practice you'll often override the template to match your CSS framework.

Active-state matching. Each container can be paired with a matcher (URI, regex, or callback). The matcher is evaluated against the current request, and matching items get an "active" attribute/class at render time. This is the main reason to use the package over hand-rolled arrays: you get a clean separation between what the menu is and whether an item is current.

Integration pattern — porting to Laravel. If you like the model, the realistic path is to use the standalone rybakit/navigation library and write a small NavigationServiceProvider that:

1. Registers Container instances as singletons bound by name.
2. Provides a Blade directive or @navigation('main') helper backed by a view composer.
3. Wraps a matcher around Laravel's Request ($request->is(...), route()->getName()).

That gives you ~90% of the bundle's value without the Symfony coupling.

Alternative in Laravel. For most apps spatie/laravel-menu or lavary/laravel-menu already cover this ground with better support and a current codebase. Benchmark against those before porting.

Gotchas and Tips

• Abandoned / stale. Last release 2017. Expect PHP 7-era constraints, likely no official PHP 8 support, and Symfony version pins that will conflict with modern stacks. Verify composer why-not before committing.
• Zero dependents and 7 stars is a strong signal: no community fixes, no examples beyond the README, no Stack Overflow answers. Debugging will be reading source.
• Config schema is undocumented. The Configuration.php node definitions are authoritative. If a key is silently ignored, it's almost always a typo’d node name being pruned by the config tree.
• Matcher evaluation timing. Matchers typically run against the current request at render time — if you render a menu outside a request context (console command, queue job, mailable) you'll get wrong or empty active states. Guard menu rendering behind a request check.
• Rendering is template-driven. Default markup is unlikely to match your frontend. Plan to publish/override templates early rather than post-processing HTML strings.
• Extension points are the matcher and renderer interfaces: implement MatcherInterface for custom "current page" logic (e.g., matching by route object instead of URI) and a custom renderer if you need JSON/API menu output.
• Symfony bundle conventions leak. Service IDs, tagged services, and the Resources/config layout are all Symfony-specific — don't expect Laravel-friendly abstractions, and don't try to shoehorn the bundle into a Laravel app. Pull in the underlying library instead.
• Version pinning. If you must use it, pin the exact version and vendor the code if necessary — the upstream repo may not accept PRs for PHP/Symfony compatibility.

Bottom line for a Laravel developer: don't install this. Read it for the container + matcher design, then either use rybakit/navigation directly with a thin Laravel adapter, or reach for a maintained Laravel menu package. The conceptual model is worth borrowing; the delivery mechanism is not.