Filament Resource Manager Laravel Package

Getting Started

Navigation Studio is a Filament plugin for authoring, versioning, and reviewing navigation profiles (the menus/sidebars that map to your panel resources). v1.3 turns it from a "menu builder" into a proper review workflow, so the fastest path to value is to treat it as a draft → preview → publish pipeline rather than an editor.

1. Install and register the plugin in your panel provider, then publish the config:

   composer require <vendor>/navigation-studio
   php artisan vendor:publish --tag=navigation-studio-config
   

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(NavigationStudioPlugin::make());
   }
   

   There are no new migrations in v1.3; if you're upgrading, just composer update and clear caches.

2. Look here first, in this order:

   • The config file — especially the profile/publishing keys and the permission-mapping array.
   • The docs sections that v1.3 touched: Profile import/export, Role preview, Version comparison, and the newly clarified Automatic publishing behavior.
   • The Filament resource pages the plugin registers (Profiles, Versions) — that's where the day-to-day UI lives.

3. First use case — onboard yourself in 10 minutes: open Navigation Studio, duplicate the current live profile into a draft, reorder/hide a couple of resources, use Role preview to simulate what an editor sees, then compare the draft against the published version before hitting publish. That single loop exercises every new v1.3 feature (drafts, role preview, version comparison, publishing) and is exactly what your team will do before every nav change.

Implementation Patterns

Draft-first workflow. Never edit the published profile directly. Keep a long-lived draft per environment, make changes there, and use version comparison to review the diff before publishing. This maps cleanly to a PR-style review: draft = branch, publish = merge.

Role preview as a QA gate. Before publishing, run Role preview against each of your app's real roles (admin, editor, viewer…) and check the "why is this hidden" explanations. This is the cheapest way to catch a resource that's accidentally invisible to a role. For apps not on Spatie, wire your own mapping in config:

// config/navigation-studio.php
'permission_map' => [
    'view-reports' => [App\Permissions::REPORTS_VIEW],
    // ...
],

Custom permission mappings let you reuse Navigation Studio's audience rules even when your authz is homegrown.

Import/export for environment promotion. Export a reviewed draft as JSON from staging, commit it (or attach it to a release ticket), and import into production. Import validates first and previews settings without mutating existing profiles — it only creates a new unpublished draft. That makes it safe to run in a deploy step, but it means promotion is a two-step operation: import → review in the UI → publish.

Version comparison during code review. When a teammate changes nav, ask for the version diff rather than a screenshot. Comparing two published versions (or published vs. draft) surfaces added/removed resources, field changes, and audience changes side by side — useful for release notes and for auditing "who removed the Billing menu?"

Multi-panel apps. Register the plugin on each panel and keep profiles per panel; role preview and version comparison operate per profile, so cross-panel drift is visible but not auto-reconciled.

i18n. v1.3 ships English and Arabic for the new controls. If you support Arabic, verify RTL layout of the diff view and role-preview drawer in your theme before rolling out.

Pin Filament. v1.3 is tested against Filament 3/4/5 signature compatibility. If you're on a custom Filament fork or a beta minor, constrain the version in composer.json and re-run the plugin's test suite after Filament upgrades.

Gotchas and Tips

• Images are not in the JSON. Import/export covers profile structure and settings, but referenced image files must be transferred separately. Add an explicit asset-copy step (or a shared CDN path) to your promotion runbook, otherwise imported drafts render with broken icons.
• Role preview is a simulation, not authorization. It explains why an item would be hidden based on navigation rules, but your Laravel policies/gates still decide real access. Don't use it as an authz test — use it to debug "why doesn't this menu show up?" mismatches between nav rules and policies.
• Import always creates an unpublished draft. It will not overwrite or publish. If your deploy expects nav to change immediately after import, it won't — schedule the publish (or a reviewer) as a separate step.
• Automatic publishing behavior was clarified in v1.3. Read that doc section carefully: depending on config, certain edits can auto-publish. If your team expects strict draft-only semantics, set the publishing flag explicitly and test it — silent auto-publish is the most likely source of "nav changed without review" surprises.
• Diff scope is structural. Version comparison reports added/removed resources, field changes, and audience changes — not styling, ordering edge cases, or media. For pixel-level checks, still eyeball the panel.
• Cache clearing matters. After import/publish, clear Filament and config caches (php artisan filament:optimize-clear, config:clear) or you'll debug a "stale menu" that's actually cached.
• Config is the extension point. Permission mappings, publishing behavior, and profile options all live in config/navigation-studio.php; publish and version-control it rather than editing vendor defaults.
• No new migrations ≠ no migrations. v1.3 adds none, but fresh installs still need the package's earlier migrations — run php artisan migrate on first install and check the docs' install page.
• Debugging hidden items: start with Role preview's explanations, then compare the draft to the published version, then check your policy mapping. That order isolates nav-rule bugs from app-authz bugs fast.