Filament Navigation Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require van-ons/filament-navigation
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="VanOns\FilamentNavigation\FilamentNavigationServiceProvider" --tag="config"
   

2. Register the Plugin: Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \VanOns\FilamentNavigation\FilamentNavigationPlugin::make(),
           ]);
   }
   

3. First Use Case:

   • Access the Navigation resource in Filament (/admin/resources/navigation).
   • Create a root menu item (e.g., "Dashboard").
   • Add child items (e.g., "Posts", "Users") via drag-and-drop.
   • Assign a URL (e.g., filament.admin.resources.posts.index) or resource (e.g., PostResource::class).
   • Save and test by visiting /admin/navigation.

Implementation Patterns

Core Workflows

1. Dynamic Menu Generation: Use the Navigation resource to define menus programmatically:

   use VanOns\FilamentNavigation\Resources\NavigationResource;
   
   NavigationResource::getNavigation()
       ->addItem('Dashboard', 'filament.admin.dashboard')
       ->addItem('Posts', PostResource::class)
           ->addChild('Create Post', 'filament.admin.resources.posts.create');
   

2. Conditional Visibility: Hide/show items based on user roles or permissions:

   NavigationResource::getNavigation()
       ->addItem('Admin', 'filament.admin.pages.admin')
       ->visible(fn () => auth()->user()->can('manage-admin'));
   

3. Nested Resource Integration: Link directly to Filament resources or custom pages:

   NavigationResource::getNavigation()
       ->addItem('Users', UserResource::class)
       ->addItem('Settings', SettingsPage::class);
   

4. Custom Icons/Styling: Use Blade components or Tailwind classes:

   ->icon('heroicon-o-home')
   ->activeWhen(fn () => request()->is('admin/dashboard'))
   ->class('bg-blue-500 text-white');
   

Advanced Patterns

• Multi-Language Support: Use Filament’s localization features to translate menu items:

  ->title(__('filament-navigation::navigation.items.dashboard'));
  

• API-Driven Menus: Fetch navigation from an external API and hydrate the Navigation model:

  $navigation = Navigation::first();
  $navigation->items = collect(json_decode($apiResponse))->map(fn ($item) => [
      'title' => $item->title,
      'url' => $item->url,
      'children' => $item->children ?? [],
  ]);
  $navigation->save();
  

• Event-Based Updates: Trigger navigation updates via events (e.g., after user login):

  use VanOns\FilamentNavigation\Events\NavigationUpdated;
  
  event(new NavigationUpdated());
  

Gotchas and Tips

Common Pitfalls

1. Caching Issues:

   • Clear Filament’s view cache after changes:

     php artisan filament:cache-clear
     

   • Ensure navigation is excluded from caching in config/filament.php:

     'cache' => [
         'enabled' => true,
         'except' => ['navigation'],
     ],
     

2. URL Resolution:

   • Use absolute paths (e.g., filament.admin.resources.posts.index) for resource links to avoid 404s.
   • For custom routes, ensure they’re registered in routes/web.php before the Filament routes.

3. Drag-and-Drop Glitches:

   • Disable JavaScript optimizations in config/filament.php if drag-and-drop feels laggy:

     'optimize' => false,
     

4. Permission Conflicts:

   • If items disappear unexpectedly, check:
     • visible() conditions.
     • Filament’s built-in permissions (canAccess()).
     • Middleware interfering with navigation rendering.

Debugging Tips

• Inspect Rendered HTML: Use browser dev tools to verify if items are rendered but hidden (e.g., due to visible() logic).
• Log Navigation Data: Dump the raw navigation structure in a service provider:

  \Log::debug('Navigation items:', [
      'items' => \VanOns\FilamentNavigation\Resources\NavigationResource::getNavigation()->items,
  ]);
  

• Check for Overrides: Ensure no other plugins (e.g., filament/spatie-laravel-settings) are modifying the navigation.

Extension Points

1. Custom Navigation Providers: Override the default provider in config/filament-navigation.php:

   'navigation_provider' => \App\Providers\CustomNavigationProvider::class,
   

   Implement VanOns\FilamentNavigation\Contracts\NavigationProvider.

2. Add Custom Fields: Extend the NavigationItem model:

   use VanOns\FilamentNavigation\Models\NavigationItem;
   
   class ExtendedNavigationItem extends NavigationItem
   {
       protected $casts = [
           'custom_data' => 'array',
       ];
   }
   

3. Hook into Rendering: Use Filament’s after hooks to modify navigation dynamically:

   FilamentNavigation::after(function (Navigation $navigation) {
       $navigation->items->first()->title = 'Updated Title';
   });
   

4. Localization: Publish and extend the language files:

   php artisan vendor:publish --provider="VanOns\FilamentNavigation\FilamentNavigationServiceProvider" --tag="lang"