Menu Management

Overview

The Menu Management system provides flexible navigation control with support for multiple menus, nested items (parent-child relationships), custom ordering, and various menu locations throughout your site.

Database Structure

Menus Table
Menu Items Table

The menus table defines top-level menu containers:

menus
  - id: bigint (primary key)
  - name: string (unique)
  - created_at: timestamp
  - updated_at: timestamp

Examples:

Primary Navigation
Footer Menu
Sidebar Menu
Mobile Menu

Reference: database/migrations/2025_05_25_175641_create_menus_table.php:14

The menu_items table stores individual menu links:

menu_items
  - id: bigint (primary key)
  - title: string (display text)
  - url: string (nullable, link destination)
  - parent_id: bigint (nullable, foreign key to menu_items)
  - order: unsigned integer (default: 0)
  - target: string (nullable, '_blank' or '_self')
  - icon_class: string (nullable, e.g., 'fa-home')
  - menu_group: string (default: 'primary')
  - created_at: timestamp
  - updated_at: timestamp

Self-Referential: parent_id creates nested menu structureReference: database/migrations/2025_05_25_175649_create_menu_items_table.php:14

Model Relationships

class Menu extends Model
{
    protected $fillable = ['name'];

    // Get all items in this menu, ordered by position
    public function items()
    {
        return $this->hasMany(MenuItem::class)->orderBy('order');
    }
}

Key Points:

Each menu has many items
Items automatically ordered by order field
Unique menu names prevent duplicates

Reference: app/Models/Menu.php:7

MenuItem Model

class MenuItem extends Model
{
    protected $fillable = [
        'menu_id', 'label', 'url', 'parent_id', 'order'
    ];

    // Parent menu container
    public function menu()
    {
        return $this->belongsTo(Menu::class);
    }

    // Child items (submenu)
    public function children()
    {
        return $this->hasMany(MenuItem::class, 'parent_id')
            ->orderBy('order');
    }

    // Parent item (for nested items)
    public function parent()
    {
        return $this->belongsTo(MenuItem::class, 'parent_id');
    }
}

Relationships:

Menu: Each item belongs to one menu
Parent: Optional parent item for nesting
Children: Child items ordered by position

Reference: app/Models/MenuItem.php:7

Hierarchical Organization

Menus support unlimited nesting levels:

Primary Menu
├── Home
├── Products
│   ├── Software
│   ├── Hardware
│   └── Services
│       ├── Consulting
│       └── Support
├── About
│   ├── Team
│   └── History
└── Contact

Implementation:

// Top-level item
$products = MenuItem::create([
    'menu_id' => $menuId,
    'title' => 'Products',
    'url' => '/products',
    'parent_id' => null,
    'order' => 2
]);

// Nested item
$software = MenuItem::create([
    'menu_id' => $menuId,
    'title' => 'Software',
    'url' => '/products/software',
    'parent_id' => $products->id,
    'order' => 1
]);

User Workflows

Creating a Menu

Define Menu Container
- Create new menu with unique name
- Example: “Primary Navigation”, “Footer Links”
Choose Menu Location
- Set menu_group to identify placement:
  - primary - Main navigation header
  - footer - Footer links
  - sidebar - Sidebar navigation
  - mobile - Mobile-specific menu
Add to Theme
- Reference menu in Blade templates
- Apply appropriate styling

Database Entry:

Menu::create(['name' => 'Primary Navigation']);

Adding Menu Items

Item Creation Workflow

Enter Item Details
- Title: Display text (e.g., “Home”, “About Us”)
- URL: Link destination (e.g., /about, https://example.com)
- Order: Position in menu (lower numbers first)
Configure Behavior
- Target: _self (same window) or _blank (new tab)
- Icon: Optional CSS class (e.g., fa-home, bi-house)
Set Parent (Optional)
- Leave parent_id null for top-level items
- Set parent_id to create dropdown/submenu
Assign to Menu
- Link to parent menu via menu_id
- Set menu_group for organization

Example:

MenuItem::create([
    'menu_id' => 1,
    'title' => 'About Us',
    'url' => '/about',
    'parent_id' => null,
    'order' => 3,
    'target' => '_self',
    'icon_class' => 'fa-info-circle',
    'menu_group' => 'primary'
]);

Reordering Menu Items

Drag-and-Drop Ordering

The order field controls item sequence:Updating Order:

// Update multiple items after drag-and-drop
foreach ($newOrder as $index => $itemId) {
    MenuItem::where('id', $itemId)->update(['order' => $index]);
}

Automatic Ordering:

Items retrieved with orderBy('order')
Lower numbers appear first
Equal numbers ordered by creation date

Best Practice:

Use increments of 10 (10, 20, 30) for easy insertion
Renumber after major reordering

Creating Nested Menus

Submenu Structure

Create Parent Item
- Add top-level menu item
- Note the item ID
Add Child Items
- Create new items with parent_id set to parent item ID
- Set unique order values for each child

Recursive Loading

// Load menu with all nested children
$menu = Menu::with('items.children')->find(1);

Example Structure:

// Parent
$services = MenuItem::create([
    'title' => 'Services',
    'url' => '#',
    'parent_id' => null,
    'order' => 10
]);

// Children
MenuItem::create([
    'title' => 'Web Development',
    'url' => '/services/web',
    'parent_id' => $services->id,
    'order' => 1
]);

MenuItem::create([
    'title' => 'Mobile Apps',
    'url' => '/services/mobile',
    'parent_id' => $services->id,
    'order' => 2
]);

Frontend Display

Rendering Menus

Simple Menu
Nested Menu
Recursive Component

Basic menu without nesting:

@php
    $menu = \App\Models\Menu::where('name', 'Primary Navigation')
        ->with('items')
        ->first();
@endphp

<nav>
    <ul>
        @foreach($menu->items as $item)
            <li>
                <a href="{{ $item->url }}" target="{{ $item->target ?? '_self' }}">
                    @if($item->icon_class)
                        <i class="{{ $item->icon_class }}"></i>
                    @endif
                    {{ $item->title }}
                </a>
            </li>
        @endforeach
    </ul>
</nav>

Recursive menu with submenus:

@php
    $menu = \App\Models\Menu::where('name', 'Primary Navigation')
        ->with('items.children')
        ->first();
@endphp

<nav>
    <ul>
        @foreach($menu->items->where('parent_id', null) as $item)
            <li>
                <a href="{{ $item->url }}">
                    {{ $item->title }}
                </a>
                
                @if($item->children->count() > 0)
                    <ul class="submenu">
                        @foreach($item->children as $child)
                            <li>
                                <a href="{{ $child->url }}">
                                    {{ $child->title }}
                                </a>
                            </li>
                        @endforeach
                    </ul>
                @endif
            </li>
        @endforeach
    </ul>
</nav>

Blade component for unlimited nesting:

{{-- resources/views/components/menu-item.blade.php --}}
<li>
    <a href="{{ $item->url }}" target="{{ $item->target ?? '_self' }}">
        @if($item->icon_class)
            <i class="{{ $item->icon_class }}"></i>
        @endif
        {{ $item->title }}
    </a>
    
    @if($item->children->count() > 0)
        <ul>
            @foreach($item->children as $child)
                <x-menu-item :item="$child" />
            @endforeach
        </ul>
    @endif
</li>

Usage:

<ul>
    @foreach($menu->items->where('parent_id', null) as $item)
        <x-menu-item :item="$item" />
    @endforeach
</ul>

The menu_group field allows multiple menu sets:

Primary Navigation

Group: primary

Main site header menu
Product categories
Key pages

Footer Menu

Group: footer

Company info links
Legal pages
Social media

Sidebar Menu

Group: sidebar

Category filters
Quick links
User dashboard

Mobile Menu

Group: mobile

Simplified navigation
Touch-optimized
Hamburger menu

Usage:

$footerMenu = Menu::where('name', 'Footer Links')
    ->whereHas('items', function($query) {
        $query->where('menu_group', 'footer');
    })
    ->with(['items' => function($query) {
        $query->where('menu_group', 'footer');
    }])
    ->first();

Advanced Features

External Links

Linking to External Sites

Menu items support full URLs:

MenuItem::create([
    'title' => 'GitHub',
    'url' => 'https://github.com/yourcompany',
    'target' => '_blank',
    'icon_class' => 'fab fa-github'
]);

Target Options:

_self - Open in same window (default)
_blank - Open in new tab
_parent - Open in parent frame
_top - Open in full window

Icon Integration

The icon_class field supports any icon library:Font Awesome:

'icon_class' => 'fas fa-home'

Bootstrap Icons:

'icon_class' => 'bi bi-house-door'

Blade Template:

@if($item->icon_class)
    <i class="{{ $item->icon_class }} me-2"></i>
@endif
{{ $item->title }}

Active State Detection

Highlighting Current Page

Detect active menu items:

@foreach($menu->items as $item)
    <li class="{{ request()->is($item->url) ? 'active' : '' }}">
        <a href="{{ $item->url }}">
            {{ $item->title }}
        </a>
    </li>
@endforeach

Advanced Matching:

@php
    $isActive = request()->url() === url($item->url) ||
                request()->is(trim($item->url, '/') . '/*');
@endphp

<li class="{{ $isActive ? 'active' : '' }}">

Database Constraints

Foreign Key Cascade

Deleting a menu item cascades to children:

$table->foreign('parent_id')
    ->references('id')
    ->on('menu_items')
    ->onDelete('cascade');

Behavior:

Deleting parent item removes all children
Prevents orphaned menu items
Maintains data integrity

Reference: database/migrations/2025_05_25_175649_create_menu_items_table.php:24

Unique Constraints

Menu Names: Must be unique

$table->string('name')->unique();

Prevents:

Duplicate menu containers
Ambiguous menu references

Best Practices

Performance

Eager Loading:

// Load menu with all nested items
Menu::with('items.children.children')->find(1);

Caching:

Cache::remember('menu.primary', 3600, function() {
    return Menu::where('name', 'Primary')
        ->with('items')
        ->first();
});

Organization

Naming Convention:

Use descriptive menu names
Consistent menu_group values
Document custom groups

Ordering Strategy:

Use increments of 10
Reserve gaps for insertion
Periodic renumbering

Common Use Cases

E-commerce: Product category navigation
Corporate Sites: Multi-level department structure
Documentation: Sidebar navigation with nested sections
Multi-language: Different menus per locale
User Roles: Dynamic menus based on permissions

Getting Started

Core Features

User Management

Admin Panel

Advanced

Menu Management

Overview

Database Structure

Model Relationships

Menu Model

MenuItem Model

Menu Structure

Hierarchical Organization

User Workflows

Menu Creation Workflow

Item Creation Workflow

Drag-and-Drop Ordering

Submenu Structure

Frontend Display

Rendering Menus

Menu Groups

Primary Navigation

Footer Menu

Sidebar Menu

Mobile Menu

Advanced Features

Linking to External Sites

Adding Icons to Menu Items

Highlighting Current Page

Database Constraints

Foreign Key Cascade

Unique Constraints

Best Practices

Performance

Organization

Common Use Cases

Build docs developers (and LLMs) love

Getting Started

Core Features

User Management

Admin Panel

Advanced

​Overview

​Database Structure

​Model Relationships

​Menu Model

​MenuItem Model

​Menu Structure

​Hierarchical Organization

​User Workflows

​Menu Creation Workflow

​Item Creation Workflow

​Drag-and-Drop Ordering

​Submenu Structure

​Frontend Display

​Rendering Menus

​Menu Groups

Primary Navigation

Footer Menu

Sidebar Menu

Mobile Menu

​Advanced Features

​Linking to External Sites

​Adding Icons to Menu Items

​Highlighting Current Page

​Database Constraints

​Foreign Key Cascade

​Unique Constraints

​Best Practices

Performance

Organization

​Common Use Cases

Build docs developers (and LLMs) love

Overview

Database Structure

Model Relationships

Menu Model

MenuItem Model

Menu Structure

Hierarchical Organization

User Workflows

Menu Creation Workflow

Item Creation Workflow

Drag-and-Drop Ordering

Submenu Structure

Frontend Display

Rendering Menus

Menu Groups

Advanced Features

Linking to External Sites

Adding Icons to Menu Items

Highlighting Current Page

Database Constraints

Foreign Key Cascade

Unique Constraints

Best Practices

Common Use Cases