Menu Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Centric Design (now explicit and load-bearing): v3.0.0 is a full rewrite built on top of Aropixel AdminBundle 3.0. The AdminBundle dependency was previously a soft blocker; it is now the foundation. There is no path to Laravel usage that does not first port or replace AdminBundle 3.0 (Symfony 6.4/7.x/8.x, Doctrine ORM 2/3) — still a poor fit for Laravel.
• AdminBundle 3.0 as a Hard Requirement: The menu editor UI lives in the AdminBundle 3.0 interface. Laravel admin stacks (Filament, Backpack, Nova) cannot consume it. In Laravel the editor must be rebuilt natively, not adapted.
• Doctrine ORM 2 or 3: The bundle now spans Doctrine ORM 2 and 3. Both are outside Laravel's default Eloquent model layer. Any Doctrine-in-Laravel bridge (laravel-doctrine) would be a second ORM in the stack — high complexity for a navigation feature.
• Front-End Rendering Helpers: New in v3 — useful as a design reference, but Twig-oriented and tied to Symfony's templating/asset pipeline. Blade equivalents would be a rewrite, not a port.
• Stimulus.js Integration: Unchanged assumption — Symfony UX Stimulus for the editor/drag-and-drop. Laravel-side equivalent remains Alpine.js or Livewire, requiring a rewrite of the JS logic.

Integration Feasibility

• Still Low — and now structurally lower:
  • No in-place upgrade path even within Symfony (per UPGRADE-3.0.md), meaning the internal design changed substantially. Any Laravel fork based on v2.x cannot be rebased; it would need to be re-forked from v3.
  • Frontend (Twig → Blade): Rendering helpers must be reimplemented as Blade directives/components.
  • Backend (Symfony controllers → Laravel routes): The v3 editor is AdminBundle-driven; equivalent Laravel controllers, policies, and validation rules must be authored from scratch.
  • Database (Doctrine → Laravel migrations): Configurable menus and depth settings imply schema changes versus v2. Doctrine migrations do not translate; the schema must be re-derived from the new entities.
• Genuinely Portable Pieces (small but real):
  • Pluggable item sources (doc/sources.md): The source contract is the most framework-agnostic idea in the release. It maps cleanly to Laravel service-container bindings and a MenuSource interface with tagged implementations.
  • Front-end rendering helpers (doc/front-end.md): Useful as a specification for Blade output (nesting, active-state, depth limits) even when the code is unusable.
  • Configurable menus and depth: A configuration model that translates directly to a Laravel config file / settings table.
• Asset Pipeline: Unchanged — Stimulus registration has no place in a Vite-based Laravel build without rewriting the controllers.

Technical Risk

• High Risk, Different Shape Than Before:
  • Upstream churn risk is now real: v3 is a rewrite with no migration path, so further breaking releases are plausible. A fork must track a moving target rather than a frozen 2022 codebase.
  • Two-layer coupling: Previously one Symfony dependency (AdminBundle); now the bundle and AdminBundle 3.0 must be considered a unit. Porting one without the other is not viable.
  • Doctrine ORM 3 support widens the compatibility surface the team would inherit if attempting a Doctrine bridge.
  • Drag-and-drop: Unchanged rewrite risk — Alpine/Livewire logic must be authored and tested for race conditions and ordering integrity.
• Revised Risk Assessment of the Upstream Project (this materially changes the prior view):
  • Active development has resumed — the prior "no active development since 2022" finding is no longer accurate and should be struck from the record.
  • Documentation has improved — installation, sources, front-end, and upgrade docs now exist. They are Symfony-targeted, but they shorten the reverse-engineering effort for a Laravel-native reimplementation.
  • Community signal still weak for a Laravel use case; nothing in the release notes suggests Laravel awareness.

Key Questions

1. Has anything in v3 changed the Laravel calculus?
   • No. The rewrite deepens the Symfony coupling. This release does not improve Laravel fit; it resets the upstream baseline.
2. Does v3 make a Laravel fork more or less attractive?
   • Less. A v2 fork was a frozen, if stale, target. A v3 fork is a fresh rewrite on a moving upstream, with no upgrade path to inherit. Re-forking from v3 discards v2-based work.
3. Is the framework-agnostic value worth extracting?
   • Yes, narrowly: the pluggable item-source contract and the configurable menus/depth model are worth reading and reimplementing natively. The code itself is not portable.
4. What is the Laravel-native replacement?
   • Unchanged shortlist: spatie/laravel-menu (simple, Eloquent-based, no drag-and-drop), orchid/navigation (feature-rich, Symfony-inspired), or a custom Eloquent + Livewire solution. A custom build now has a better specification to work from thanks to the v3 docs.
5. Does the AdminBundle 3.0 requirement remain a non-starter?
   • Yes. If the team will not adopt Symfony/AdminBundle, the bundle is a non-starter for Laravel — unchanged from the prior assessment.
6. Who is the actual consumer of this release?
   • Existing Symfony applications on AdminBundle 3.0. There is no Laravel audience for v3.0.0.

Integration Approach

Stack Fit

• Laravel Incompatibility Confirmed and Deepened:
  • Framework coupling: Now transitive through AdminBundle 3.0, not just direct Symfony components.
  • ORM: Doctrine ORM 2/3 vs. Eloquent — unchanged gap, now spanning two ORM majors.
  • Frontend: Twig rendering helpers + Stimulus vs. Blade + Alpine/Livewire.
• Where Partial Fit Still Exists:
  • Item-source abstraction: The pluggable source concept maps well to Laravel's container and tagged bindings.
  • Configuration model: Configurable menus and depth limits translate directly to Laravel config/settings.
  • Rendering semantics: The front-end helpers doc is a usable spec for Blade component output.

Migration Path

Option 1: Fork v3 and Rewrite (High Effort — now higher than before)

Note: any prior v2 fork work is not reusable; v3 has no in-place upgrade path even within Symfony.

1. Replace AdminBundle 3.0 coupling: Substitute Laravel service providers and a native admin surface (Filament/Nova/Livewire).
2. Replace Doctrine entities: Re-derive the schema from the v3 entities into Eloquent models and Laravel migrations, including configurable menus and depth settings.
3. Rewrite front end: Twig rendering helpers → Blade components/directives; Stimulus editor → Alpine/Livewire.
4. Adapt routing and DI: Laravel routes, policies, form requests, and container bindings.
5. Port item sources: Implement the source contract as a Laravel interface with tagged implementations.
6. Test: Nesting depth, ordering, active-state, custom sources, concurrent edits.

Option 2: Spec-and-Build Hybrid (Recommended)

• Do not fork. Use v3 documentation (doc/sources.md, doc/front-end.md, UPGRADE-3.0.md) as the requirements specification for a native Laravel implementation.
• Deliver: Eloquent models with nested relationships and depth constraints; a Livewire/Filament editor with drag-and-drop; a MenuSource interface bound via the container; Blade components for rendering.
• Rationale: captures the genuinely portable design ideas at a fraction of fork cost, with no upstream tracking obligation.

Option 3: Abandon and Replace

• spatie/laravel-menu for simple, Eloquent-backed menus.
• orchid/navigation if richer hierarchy features are needed.
• Custom Eloquent + Livewire where drag-and-drop is required.

Compatibility

Sequencing

1. Record the decision: Document that v3 does not change Laravel fit and that no v2 fork work carries forward (no in-place upgrade path).
2. Mine the docs: Extract the source contract, depth/config model, and rendering semantics into a short internal spec. Timebox this.
3. Prototype natively: Minimal Eloquent menu model with nesting and depth limits; Blade rendering; one item source bound via the container.
4. Build the editor: Livewire or Filament drag-and-drop with ordering integrity and optimistic-lock handling.
5. Extend sources: Additional MenuSource implementations (pages, links, sections) with query-cost review.
6. Test and cut over: Depth limits, active-state, concurrency, and cache invalidation on menu mutation.
7. Only if step 2/3 fails: Reopen the fork discussion, scoped to v3 with an explicit upstream-tracking owner.

Operational Impact

Maintenance

• Fork route: Cost increased. Upstream is active again, so a fork must track a moving target with a history of breaking rewrites rather than idling on a 2022 snapshot.
• Native build route: Cost is bounded and owned internally — no upstream churn, no second ORM, no Symfony abstraction layer.
• Dependency hygiene: Adopting v3 in a Laravel context implies Doctrine ORM 2/3 plus Symfony packages; avoid unless a Doctrine bridge is already an approved pattern.
• Documentation: Materially improved upstream, but entirely Symfony-facing. Laravel-side runbooks remain a team responsibility.

Support

• Upstream support is Symfony-shaped: Issues and docs assume AdminBundle 3.0. Laravel questions will not be answered upstream.
• No Laravel precedent: v3 introduces no Laravel guidance; community examples remain near-nonexistent for this stack combination.
• Mitigation: Internal ownership of the native implementation, with the v3 docs pinned as the reference spec.

Scaling

• Query shape: Deep, configurable menus amplify N+1 risk. Use eager loading / recursive CTEs where supported, and enforce the configured depth cap at query time.
• Item sources: Each registered source adds query cost on editor load. Cache source lists and invalidate on menu mutation.
• Rendering: Blade component recursion should be cached at the fragment layer; menu output is highly cacheable and invalidated on reorder.
• Editor concurrency: Drag-and-drop under simultaneous edits needs ordering locks or version columns; depth limits should be validated server-side, not only in the UI.

Failure Modes

Ramp-Up

• Team learning curve: Moderate for the native route (Eloquent + Livewire/Filament, already familiar); steep for the fork route (Symfony DI, Doctrine, AdminBundle 3.0, Stimulus).
• Doc-driven onboarding: The v3 sources.md and front-end.md docs are the fastest way to brief engineers on intended behavior without reading Symfony source.
• Estimated effort: Native implementation with editor and two to three sources is a well-scoped feature-sized effort. A v3 fork is a multi-sprint undertaking with permanent upstream-tracking overhead.
• Recommendation: Update the assessment to "do not adopt; extract the design, build natively." Re-evaluate only if the team standardizes on Symfony/AdminBundle 3.0 or the upstream project publishes Laravel support.