README

A powerful navigation management package for Filament v4 that allows you to dynamically manage your Filament panel navigation menus through a user-friendly interface.

📖 简体中文文档 | English Documentation

Features

✨ Rich Feature Set

🎯 Dynamic navigation management through Filament UI
🔄 Automatic synchronization of Filament resources and pages
🌳 Tree-structured menu hierarchy support
🎨 Customizable navigation groups, icons, and badges
🔐 Role-based access control
🌍 Multi-language support (English, Simplified Chinese, Traditional Chinese)
⚡ Navigation caching for better performance
📦 Easy installation and setup

Installation

You can install the package via Composer:

composer require ycookies/filament-nav-manager

Publish and Run Migrations

php artisan filament-nav-manager:install

This command will:

Publish the configuration file
Publish migration files
Ask if you want to run migrations
Allow you to sync panels

Or manually:

php artisan vendor:publish --tag="filament-nav-manager-migrations"
php artisan migrate
php artisan vendor:publish --tag="filament-nav-manager-config"

Configuration

Enable the Plugin

Add the plugin to your Filament panel provider:

use Ycookies\FilamentNavManager\FilamentNavManagerPlugin;
use Ycookies\FilamentNavManager\Models\NavManager;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentNavManagerPlugin::make())
        ->navigation(
            NavManager::generate()
                ->panel($panel->getId())
                ->cacheTime(config('nav-manager.cache_seconds', 0))
                ->toClosure()
        );
}

Configure Permissions

Edit config/nav-manager.php:

return [
    // Allow specific roles to access Nav Manager
    'allowed_roles' => ['admin', 'super_admin'], // or null for all authenticated users
    
    // Cache navigation for better performance (in seconds)
    'cache_seconds' => 3600, // 0 to disable caching
    
    // Database table name
    'table_name' => 'nav_manager',
    
    // Navigation group for Nav Manager resource in sidebar
    'navigation_group' => null, // null to use translation, or custom name like 'System', 'Settings'
];

Customize Navigation Group

You can customize which navigation group the Nav Manager resource appears in:

// config/nav-manager.php
return [
    'navigation_group' => 'System Settings', // Custom group name
    // or
    'navigation_group' => null, // Use default translation
];

Usage

Syncing Filament Resources and Pages

Option 1: Via UI

Navigate to "Navigation Manager" in your Filament panel
Click the "Sync Filament Menu" button
Confirm the sync operation

Option 2: Via Command Line

Sync a specific panel:

php artisan filament-nav-manager:sync admin

Or sync all panels during installation:

php artisan filament-nav-manager:install

Managing Navigation Items

Once installed, you'll see "Navigation Manager" in your Filament navigation. From there you can:

✅ Create new navigation items
✅ Edit existing items
✅ Delete items
✅ Reorder items (drag and drop if tree view is enabled)
✅ Toggle visibility
✅ Manage icons and badges
✅ Set permissions

Navigation Item Types

The package supports several navigation item types:

Group - A navigation group that can contain child items
Resource - Links to a Filament resource
Page - Links to a Filament page
Route - Links to a Laravel route
URL - Links to any URL (internal or external)

Navigation Structure

Navigation items are organized in a hierarchical tree structure:

Navigation Group
├── Resource Item
├── Page Item
└── Navigation Group
    ├── Resource Item
    └── Route Item

Advanced Usage

Programmatic Navigation Management

You can also manage navigation programmatically:

use Ycookies\FilamentNavManager\Models\NavManager;

// Create a navigation item
NavManager::create([
    'title' => 'My Menu',
    'type' => NavManager::TYPE_RESOURCE,
    'target' => \App\Filament\Resources\Users\UserResource::class,
    'panel' => 'admin',
    'parent_id' => 0,
    'order' => 1,
    'show' => true,
    'icon' => 'heroicon-o-users',
]);

// Sync panel resources and pages
$panel = Filament::getPanel('admin');
$count = NavManager::syncPanel($panel);

// Clear navigation cache
NavManager::flushNavigationCache('admin');

Custom Navigation Generation

use Ycookies\FilamentNavManager\Models\NavManager;

// Generate navigation for a specific panel
$navigation = NavManager::navigationForPanel('admin', cacheSeconds: 3600);

// Use in panel configuration
$panel->navigation(
    NavManager::generate()
        ->panel('admin')
        ->cacheTime(3600)
        ->toClosure()
);

Multi-Language Support

The package includes translations for:

🇬🇧 English (en)
🇨🇳 Simplified Chinese (zh_CN)
🇹🇼 Traditional Chinese (zh_TW)

Translations are automatically loaded. Set your application locale:

config(['app.locale' => 'zh_CN']);

Role-Based Access Control

Configure which roles can access the Navigation Manager:

// config/nav-manager.php
return [
    'allowed_roles' => ['admin', 'super_admin'],
];

If using Spatie Laravel Permission:

// The package automatically checks if user has any of the allowed roles
'allowed_roles' => ['admin', 'super_admin'],

Set to null to allow all authenticated users:

'allowed_roles' => null, // All authenticated users can access

Tree View Support

If your application has a treeView table macro (commonly used for hierarchical data), the navigation table will automatically use it for a better tree-structured display.

Clearing Navigation Cache

use Ycookies\FilamentNavManager\NavManagerNavigationGenerator;

// Clear cache for current panel
NavManagerNavigationGenerator::flush();

// Clear cache for specific panel
NavManagerNavigationGenerator::flush('admin');

Or via model:

use Ycookies\FilamentNavManager\Models\NavManager;

NavManager::flushNavigationCache('admin');

Database Schema

The package creates a nav_manager table with the following structure:

id - Primary key
parent_id - Parent menu item ID (0 for top-level)
panel - Filament panel ID
order - Display order
title - Menu title
type - Menu type (group, resource, page, route, url)
icon - Heroicon name
uri - URI path
target - Resource class, Page class, or route name
extension - Extension identifier
show - Visibility toggle
badge - Badge text
badge_color - Badge color
is_collapsed - Collapsed state
permission - Required permission
created_at / updated_at - Timestamps

Commands

Install Command

php artisan filament-nav-manager:install

Runs migrations and optionally syncs panels.

Sync Command

php artisan filament-nav-manager:sync {panel}

Syncs Filament resources and pages for a specific panel.

Troubleshooting

Navigation Not Appearing

Ensure the plugin is registered in your Panel Provider
Check that navigation items have show = true
Verify user has required roles (if configured)
Clear navigation cache: NavManager::flushNavigationCache()

Sync Not Working

Verify the panel ID exists
Check that resources/pages are properly registered in the panel
Review error logs for specific issues

Permission Issues

Check config/nav-manager.php for allowed_roles configuration
Verify user roles are correctly assigned
Ensure Spatie Laravel Permission is installed if using roles

Requirements

PHP >= 8.2
Laravel >= 10.0
Filament >= 4.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.

Support

📧 Email: 3664839@qq.com
🐛 Issues: GitHub Issues
📖 Documentation: GitHub Wiki

Changelog

Please see CHANGELOG for more information on what has changed recently.

Made with ❤️ by eRic

ycookies / filament-nav-manager

Maintainers

Details