Getting Started

Minimal Steps to First Use

Installation Run composer require lunestudio/filament-navigation-manager and execute php artisan filament-navigation-manager:install to publish migrations and assets.

Register Plugin Add the plugin to your AdminPanelProvider:

public function panel(Panel $panel): Panel {
    return $panel
        ->default()
        ->plugins([
            FilamentNavigationManagerPlugin::make(),
        ]);
}

Publish Config Run php artisan vendor:publish --tag="filament-navigation-manager-config" to customize settings like the model or labels.
Migrate & Seed Run php artisan migrate and optionally seed default menus via php artisan db:seed --class=NavigationManagerSeeder (if provided).
First Menu Creation Access the /admin/menus route (default) to create your first menu via the Filament UI. Use the built-in CRUD interface to define:
- Menu name/label
- Navigation items (links, groups, or submenus)
- Visibility rules (e.g., user roles, permissions)

First Use Case: Dynamic Admin Dashboard Menu

Create a top-level menu (e.g., "Dashboard") with child items like:

"Analytics" (link to /admin/analytics)
"Reports" (link to /admin/reports)
"Settings" (group with sub-items: "Profile", "Notifications")

Use the Visibility tab to restrict access to specific user roles (e.g., admin).

Implementation Patterns

Core Workflows

Menu Hierarchy Management
- Parent-Child Relationships: Use the nested UI to create hierarchical menus (e.g., "Products" → "Categories" → "Edit").
- Drag-and-Drop: Reorder items via Filament’s built-in sortable tables (if enabled in config).
- Bulk Actions: Delete/update multiple items using Filament’s bulk operations.
Dynamic Rendering
- Blade Integration: Render menus in views with:
```
@foreach (\Lunestudio\FilamentNavigationManager\Facades\NavigationManager::getMenu('dashboard') as $item)
    <a href="{{ $item->url }}">{{ $item->label }}</a>
@endforeach
```
- Livewire/Alpine: Fetch and update menus dynamically without page reloads by leveraging Filament’s reactivity.
Conditional Logic
- Visibility Rules: Attach policies or gates to menu items:
```
// In your Menu model or policy
public function visibleTo(User $user): bool {
    return $user->hasPermission('view_dashboard');
}
```
- Contextual Menus: Use Filament’s canAccessPanel() or custom logic to show/hide menus based on:
  - User roles ($user->isAdmin()).
  - Session data (session('active_tab')).
  - Request parameters (request()->routeIs('admin.*')).
Integration with Filament Resources
- Auto-Generated Links: Link directly to Filament resources:
```
NavigationItem::make()
    ->label('Users')
    ->url(fn () => Filament::getCurrentPanel()->getDashboardUrl())
    ->icon('heroicon-o-users')
```
- Resource-Specific Menus: Create menus tied to specific resources (e.g., "Posts" menu only visible when managing posts).

Advanced Patterns

Custom Menu Providers Extend functionality by creating a custom provider:

use Lunestudio\FilamentNavigationManager\Contracts\MenuProvider;

class CustomMenuProvider implements MenuProvider {
    public function getMenus(): array {
        return [
            'api' => [
                'label' => 'API Docs',
                'url' => 'https://docs.example.com/api',
                'visible' => fn () => auth()->user()->isDeveloper(),
            ],
        ];
    }
}

'providers' => [
    \App\Providers\CustomMenuProvider::class,
],

Menu Caching Cache menus for performance (e.g., in AppServiceProvider):

public function boot() {
    Cache::remember('filament-navigation-menus', now()->addHours(1), function () {
        return \Lunestudio\FilamentNavigationManager\Facades\NavigationManager::getAllMenus();
    });
}

Multi-Tenant Menus Scope menus to tenants by overriding the query in the Menu model:

protected static function booted() {
    static::addGlobalScope('tenant', function (Builder $builder) {
        $builder->where('tenant_id', tenant()->id);
    });
}

Localization Use Filament’s localization features to support multi-language menus:

NavigationItem::make()
    ->label(__('menus.dashboard'))
    ->url('/admin/dashboard')

Gotchas and Tips

Pitfalls

Migration Conflicts
- Issue: Running filament-navigation-manager:install after creating custom Menu migrations may cause conflicts.
- Fix: Manually merge migration files or use php artisan migrate:fresh in a staging environment.
Visibility Logic Overhead
- Issue: Complex visibility rules (e.g., nested conditions) can slow down menu rendering.
- Fix: Cache results of visible() checks or use simpler conditions where possible.
Plugin Registration Order
- Issue: Menus may not appear if FilamentNavigationManagerPlugin::make() is not added before other plugins that modify the panel.
- Fix: Place it early in the plugins() array or use ->after()/->before() methods.
URL Generation Edge Cases
- Issue: Hardcoded URLs in menus break during deployment if the base path changes.
- Fix: Use Filament’s URL helpers:
```
url(fn () => Filament::getCurrentPanel()->getDashboardUrl())
```
Permission Caching
- Issue: Changes to user permissions may not reflect immediately in menus due to caching.
- Fix: Clear the cache after permission updates:
```
php artisan cache:clear
```

Debugging Tips

Log Menu Data Dump menu data for debugging:

dd(\Lunestudio\FilamentNavigationManager\Facades\NavigationManager::getMenu('dashboard'));

Check Visibility Rules Test visibility logic in Tinker:

php artisan tinker
>>> $menuItem->visible(auth()->user())

Inspect Published Assets Verify CSS/JS assets are published correctly:

php artisan vendor:publish --tag="filament-navigation-manager-assets"

Database Queries Enable query logging to debug slow menu loads:

DB::enableQueryLog();
$menus = \Lunestudio\FilamentNavigationManager\Facades\NavigationManager::getAllMenus();
dd(DB::getQueryLog());

Extension Points

Custom Menu Model Extend the default Menu model to add fields (e.g., priority, color):
```
php artisan make:model MenuExtension --model=Lunestudio\FilamentNavigationManager\Models\Menu
```
Update the config to use your extended model.

Custom Navigation Item Types Add new item types (e.g., "Button", "Divider") by extending the NavigationItem class:

class CustomNavigationItem extends NavigationItem {
    public static function make(): static {
        return new static();
    }

    public function getView(): string {
        return 'filament-navigation-manager::custom-item';
    }
}

Event Listeners Hook into menu events (e.g., MenuCreated, MenuUpdated) to trigger actions:

use Lunestudio\FilamentNavigationManager\Events\MenuCreated;

MenuCreated::listen(function (MenuCreated $event) {
    \Log::info("Menu '{$event->menu->name}' created by {$event->user->name}");
});

API Endpoints Expose menus via API using Filament’s HTTP layer:

Route::get('/api/menus', function () {
    return \Lunestudio\FilamentNavigationManager\Facades\NavigationManager::getAllMenus();
});

Configuration Quirks

Default Navigation Group Set navigation_group in config to organize menus in Filament’s sidebar:

'resources' => [
    'navigation_group' => 'Settings', // Groups under "Settings" in sidebar
],

Asset Publishing If styles/JS don’t load, republish assets:

php artisan vendor:publish --tag="filament-navigation-manager-assets" --force

Model Binding Ensure the Menu model’s id column is `unsignedBigInteger

Filament Navigation Manager Laravel Package