Filament Menu Manager Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require notebrainslab/filament-menu-manager
   php artisan filament-menu-manager:install
   

   Run migrations to create the menu_items and menu_locations tables.

2. Register the Plugin: Add to app/Providers/Filament/AdminPanelProvider.php (or app/Providers/FilamentPanelProvider.php for Filament v5):

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Notebrainslab\FilamentMenuManager\FilamentMenuManagerPlugin::make(),
           ]);
   }
   

3. First Use Case: Access the plugin via the Filament admin panel (default URL: /admin/menu-manager). Create a new location (e.g., "Primary Navigation") and add menu items via:

   • Custom Links: Directly input URLs, titles, and icons.
   • Eloquent Models: Link to database records (e.g., Post, Page) by configuring a source.

Implementation Patterns

Core Workflows

1. Defining Menu Locations: Locations are created in the plugin UI but can be pre-configured via a seed:

   // database/seeders/MenuManagerSeeder.php
   use Notebrainslab\FilamentMenuManager\Models\MenuLocation;
   
   public function run()
   {
       MenuLocation::create(['name' => 'Primary Navigation']);
       MenuLocation::create(['name' => 'Footer Links']);
   }
   

2. Adding Eloquent Model Sources: Register a model as a menu item source in config/filament-menu-manager.php:

   'sources' => [
       'posts' => [
           'model' => \App\Models\Post::class,
           'label' => 'Posts',
           'url' => fn ($record) => route('posts.show', $record),
           'icon' => 'heroicon-o-document-text',
       ],
   ],
   

   Access the source in the plugin UI under "Add Item" > "Eloquent Sources".

3. Dynamic Menu Rendering: Fetch menu items for a location in a Blade view or Livewire component:

   use Notebrainslab\FilamentMenuManager\Facades\MenuManager;
   
   $primaryMenu = MenuManager::getMenu('Primary Navigation');
   

   Render with:

   <ul>
       @foreach($primaryMenu as $item)
           <li><a href="{{ $item->url }}">{{ $item->title }}</a></li>
       @endforeach
   </ul>
   

4. Customizing Item Display: Extend the MenuItem model or use a custom view for rendering:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       \Notebrainslab\FilamentMenuManager\MenuManager::macro('renderItem', function ($item) {
           return view('custom.menu-item', compact('item'));
       });
   }
   

5. Integration with Filament Pages: Use the MenuManager facade to inject menus into Filament resources/pages:

   use Notebrainslab\FilamentMenuManager\Facades\MenuManager;
   
   public static function getNavigationItems(): array
   {
       return MenuManager::getMenu('Sidebar')->toArray();
   }
   

Advanced Patterns

1. Conditional Menu Items: Filter menu items based on user roles or other logic:

   $menu = MenuManager::getMenu('Primary Navigation')
       ->where('visible_to', auth()->user()->role);
   

2. Real-Time Updates: Leverage Livewire to update menus dynamically:

   public function updatedMenu()
   {
       $this->emit('menuUpdated');
   }
   

   Listen in JavaScript:

   Livewire.on('menuUpdated', () => {
       location.reload(); // Or fetch updated menu via AJAX
   });
   

3. Multi-Language Support: Use Laravel localization with a custom title attribute:

   'sources' => [
       'pages' => [
           'model' => \App\Models\Page::class,
           'title' => fn ($record) => __($record->title),
       ],
   ],
   

4. API Access: Expose menu endpoints via Laravel routes:

   Route::get('/api/menus/{location}', function ($location) {
       return MenuManager::getMenu($location);
   });
   

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If menu_items table already exists, manually merge columns or reset migrations.
   • Fix: Drop the table and re-run migrations:

     php artisan migrate:fresh --env=testing
     

2. SortableJS Conflicts:

   • Avoid duplicate SortableJS instances if other plugins use it (e.g., Spatie Media Library).
   • Fix: Exclude the plugin’s JS in your layout:

     @filamentScripts
     @stack('filament-menu-manager-scripts')
     

3. Auto-Save Delays:

   • Auto-save may feel laggy with large menus due to debouncing (default: 500ms).
   • Fix: Adjust in config/filament-menu-manager.php:

     'auto_save_debounce' => 200, // Milliseconds
     

4. Eloquent Source Caching:

   • Model sources may cache queries if not configured properly.
   • Fix: Ensure url and title closures are lazy-loaded:

     'url' => fn ($record) => route('posts.show', $record, false), // Disable cache
     

5. Permission Issues:

   • Users without view menu manager permission will see a 403 error.
   • Fix: Assign permissions via Filament’s User resource or middleware:

     public function authorizeAccess(): void
     {
         $this->authorize('view menu manager');
     }
     

Debugging Tips

1. Log Menu Queries: Enable query logging in AppServiceProvider:

   public function boot()
   {
       if (app()->environment('local')) {
           \DB::enableQueryLog();
       }
   }
   

   Dump queries after fetching a menu:

   $menu = MenuManager::getMenu('Primary Navigation');
   \Log::info(\DB::getQueryLog());
   

2. Check Plugin Assets:

   • Clear Filament’s cache if styles/JS fail to load:

     php artisan filament:cache-reset
     php artisan view:clear
     

3. Validate Menu Locations: Ensure locations exist before rendering:

   if (!MenuManager::hasLocation('Primary Navigation')) {
       abort(404);
   }
   

Extension Points

1. Custom Menu Item Types: Extend the MenuItem model or create a trait:

   namespace App\Models;
   
   use Notebrainslab\FilamentMenuManager\Models\MenuItem;
   
   class CustomMenuItem extends MenuItem
   {
       public function getCustomAttribute()
       {
           return $this->attributes['custom_data'] ?? null;
       }
   }
   

2. Override Default Views: Publish and modify views:

   php artisan vendor:publish --tag="filament-menu-manager-views"
   

   Override resources/views/vendor/filament-menu-manager/....

3. Add Custom Fields: Extend the MenuItem form using Filament’s FormBuilder:

   use Notebrainslab\FilamentMenuManager\Forms\Components\MenuItemForm;
   
   MenuItemForm::modify(function (MenuItemForm $form) {
       $form->addComponents([
           TextInput::make('custom_field')
               ->columnSpanFull(),
       ]);
   });
   

4. Hook into Menu Events: Listen for item creation/updates:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Notebrainslab\FilamentMenuManager\Events\MenuItemSaved::class => [
           \App\Listeners\LogMenuChanges::class,
       ],
   ];
   

5. Dark Mode Customization: Override CSS variables in your app’s stylesheet:

   :root {
       --filament-menu-manager-bg: #1a1a1a;
       --filament-menu-manager-text: #e0e0e0;
   }