Filament Site Navigation Laravel Package

Getting Started

Start with the plugin's README and its config/ file — that's where the navigation "handles" (menu locations), caching behaviour, and model bindings are defined. The day-one flow is:

1. composer require rectitude-open/filament-site-navigation
2. Publish and run migrations (the package ships navigation + navigation item tables) and publish the config if you need to change handles or models.
3. Register the plugin on the Filament panel you want editors to use:

   ->plugin(FilamentSiteNavigationPlugin::make())
   

4. Run php artisan filament:assets / clear cached config, then open the panel — a navigation management UI appears where editors build menus.

First use case: a single main header menu with mixed link types (internal page, custom URL) and one level of nesting. Create the navigation record, add a few items, drag to order, then render it in Blade via the package's helper/view for that handle. Get one menu rendering end-to-end before touching multi-menu or localization.

Given v1.10.0 is a translation/labels release, the first thing to verify after upgrading is that the form and action modals read correctly in your panel's locale — if you only support English, nothing else in your setup changes.

Implementation Patterns

Handle-per-location. Treat navigation handles as named slots (header, footer, sidebar) rather than creating one giant tree. Each Blade layout asks for its own handle, so marketing can reorder the footer without touching the header.

Render in a layout partial, cache at the handle level. Wrap the render call in Cache::remember("nav:{$handle}", ...) and bust it from the navigation/navigation-item model events (saved, deleted, and reorder events). Rendering per-request is fine for small sites but reorder-heavy admin usage makes stale-cache bugs the #1 support ticket.

Link types are the integration seam. Internal links should be stored as morph-style references (model + id) so a renamed page or changed slug doesn't break the menu; custom URLs are for external links and anchors only. Build a small NavigationItemPresenterDTO (label, url, target, children) and map the package's items into it — that keeps your Blade templates and any JSON/API output independent of the package's internal schema.

Localization pattern. With 1.10.0's added translations and localized labels, the common pattern is: one navigation record per locale/handle (e.g. header_en, header_de) OR one record with translated item labels, depending on how your content is structured. If your pages are localized, keep the tree structure identical across locales and only swap labels/URLs — mismatched tree shapes between locales are painful to reconcile later. Publish the package translations (php artisan vendor:publish --tag=...) only if you need to override strings; otherwise let the panel locale drive it.

Seeding for repeatable environments. Seed navigation handles and items in a seeder keyed by a stable key/slug column so local, staging, and production converge. Never seed by auto-increment ID.

Testing. Use Filament's testing helpers against the navigation resource pages (assertCanSeeTableRecords, callAction) for the admin side, and a single feature test asserting the rendered Blade output for a handle — that one test catches most ordering/visibility regressions.

Gotchas and Tips

• Nested ordering is the fragile part. Reordering parents with children can produce orphaned or duplicated sort values. After upgrading, re-save any deeply nested menus once and spot-check order/parent_id values; if the package exposes a reorder action, prefer it over manual sorting.
• Caching + reorder = stale menus. Any cache you add must be invalidated on item move, not just on create/delete. If you use a model observer, hook the reorder/order_column update event explicitly.
• Locale fallback surprises. New translations mean the form labels now follow the panel/app locale. If a panel's locale has no translation for a newly added string, you'll see mixed-language UI rather than English — check config('app.locale') and set an explicit fallback.
• Authorization is opt-in. Decide early whether navigation editing is restricted; add the resource to a policy or gate rather than letting every panel user reorder the header.
• Extension points: the config's model bindings let you swap in a subclass if you need extra columns (e.g. an icon, a visibility flag). Do that in the config, not by editing vendor files — and re-check the binding after each minor upgrade, since a new version can add columns the package expects.
• Upgrade hygiene for a translation-only release: this is a safe patch/minor. Run php artisan view:clear and config:clear after composer update, then eyeball the form and action modals in each locale your panel supports — that's exactly what 1.10.0 touched.