Navigation Laravel Package

Technical Evaluation

Assessment summary: This is not a Laravel package. It is a small, framework-agnostic PHP navigation-tree builder whose only first-party adapter is a Symfony bundle (everlutionsk/navigation-bundle). The TPM framing is "candidate component, reference implementation, or fork source" — not "install and ship."

Architecture fit

• The core models navigation as a tree of items with rendering separated out — a reasonable shape for a Laravel app that wants a structured menu model instead of hard-coded Blade navs.
• There is no Laravel service provider, config stub, facade, or Blade integration. All framework glue is ours to design, own, and test.
• MIT license plus a framework-agnostic core means we can fork into an internal namespace with minimal legal friction — the single most useful lever available.
• Fit is low-to-moderate against a standard Laravel stack; fit is poor if we expect a drop-in package with auto-discovery and publishable assets.

Integration feasibility

• Composer install plus a menu-build spike is feasible in 1–2 engineer-days; production hardening (provider, config, caching, tests, CI matrix) is realistically 3–5 engineer-days plus review.
• Risk is not installability, it is the absence of evidence: 1 star, 0 dependents, one tagged release in May 2021. No production usage signal exists anywhere in the ecosystem.
• The README is thin and defers usage guidance to the Symfony bundle, implying the intended consumer path is a DI container we do not have. Expect to reverse-engineer the API from source.

Technical risk

• Abandonment (high): last release 2021-05-14. Every PHP/Laravel upgrade path is ours to maintain. No upstream advisory channel exists.
• Version constraint (high): a 2021 tag likely pins PHP 7.x–8.0-era constraints and may conflict with current Laravel LTS requirements or force composer platform overrides.
• Bus factor (high): effectively a single-maintainer project with no visible triage or release cadence.
• Quality signal (medium): Scrutinizer badges are historical artifacts, not current CI evidence. Treat as stale.
• Scope (medium): navigation libraries often conflate item modeling with rendering and authorization-aware filtering. If permission and active-trail logic are baked into the renderer rather than exposed as hooks, we will fight it.

Key questions for the spike

1. What PHP versions and framework contracts does the core actually require? Does any Symfony dependency leak into the core namespace?
2. Is there a clean extension point for per-user permission filtering, active-trail detection, and locale-aware labels?
3. Is rendering pluggable (so we can render with Blade components) or baked into HTML string output?
4. What does the item data model look like, and how cleanly does it map to our existing menu/content sources?
5. Is the API small enough that a clean-room internal reimplementation costs less than adopting and maintaining a fork?

Recommendation: Do not take a direct runtime dependency. Either (a) use it as a reference spec and build a ~300-line internal navigation builder, or (b) fork it into our vendor namespace with a Laravel adapter, tests, and a named owner. Option (a) is likely cheaper given the surface area, and the "opportunity" score (low) supports that conclusion.

Integration Approach

Stack fit

• Treat it as a pure-PHP library consumed inside Laravel. Required glue: a NavigationServiceProvider (singleton bindings for the menu registry/builder), config/navigation.php, a repository class mapping our content/menu sources into the item model, and Blade components (<x-nav.menu />) or a recursive partial for rendering.
• Wrap everything behind our own interfaces (MenuRepository, MenuRenderer, MenuItem) so the third-party API never appears in application code. This is the most important design decision — it converts a risky dependency into a swappable implementation detail.

Migration path

• Inventory current navigation surfaces (header, footer, sidebar, breadcrumbs, mobile drawer) and their data sources.
• Build the new menu model behind a feature flag; run shadow rendering in parallel against the current implementation and diff output in tests and staging.
• Flip per surface, starting with the lowest-traffic menu (footer) before primary/header navigation.
• Keep the old code path behind a config switch for one release cycle, then delete.

Compatibility

• Verify PHP constraints against our target runtime first. If it requires an older PHP, stop and go in-house rather than downgrading the platform.
• Confirm the core has no Symfony contracts; if it does, that is a disqualifier for a Laravel-only shop.
• Test against current and next Laravel LTS plus the PHP versions inside our support window, in CI.
• Pin the exact version (no caret range) and commit the lockfile; register it in the dependency inventory.

Sequencing

1. Timeboxed spike (1–2 days): install, model one real menu from live data, render it.
2. Architecture review: evaluate API shape and extension points against the key questions above.
3. Record a build-vs-fork-vs-adopt decision as an ADR with cost estimates.
4. If proceeding: fork/adapter, provider + config + Blade components, unit and feature tests, CI matrix.
5. Feature-flagged rollout per surface with shadow-diff validation.
6. Document, hand off ownership, and close the spike branch.

Operational Impact

Maintenance

• De facto ownership transfers to us on day one. Budget a small but permanent line item: PHP/Laravel upgrade compatibility, dependency scans, and bug fixes.
• Pin exactly; vendor the fork if adopted; annotate the entry in the dependency register as "unmaintained upstream."
• Include it in SCA/security scanning, since no upstream advisory process exists.

Support

• Upstream support is effectively zero: no issue triage, no release cadence, no maintainer SLA. Internal support means internal documentation and a named owner.
• If forked, add the internal package to the service catalog with an owning team and an escalation path.
• Record known limitations in the ADR so future engineers do not rediscover them.

Scaling

• Menu construction is CPU-trivial; the real cost is data access. Expect N+1 queries pulling items unless we eager-load or cache.
• Cache the compiled navigation tree per role/locale/tenant, with event-driven invalidation on content or permission changes. Avoid per-request rebuilds on high-traffic pages.
• Header/footer menus render on nearly every request, so cache hit rate matters far more than the library's own performance.

Failure modes and mitigations

• Upstream abandonment blocks a framework upgrade → fork; keep the adapter thin so replacement is contained.
• Composer constraint conflict on PHP/Laravel upgrade → pin and isolate; fork and relax constraints if needed.
• Silent vulnerability with no advisory → SCA scanning plus code review of any fork diff.
• Presentation logic leaking into domain models → enforce the renderer interface boundary in code review.
• Stale menus after content edits → explicit cache keys and invalidation hooks wired to content events.
• Knowledge concentration in one engineer → pair on the spike; write integration notes and an ADR.

Ramp-up

• Small API surface: a competent Laravel engineer should be productive in 1–2 days, with the caveat that knowledge starts with whoever ran the spike. Ramp artifacts: ADR, one-page integration guide, an example menu definition, and a test fixture demonstrating permission filtering and active-state handling.

Bottom line: low strategic value, non-trivial ownership cost, weak ecosystem evidence. Leverage it as a design reference or a small internal fork; avoid an unpinned direct dependency in a production Laravel application.