## Filter: wpd_alpha_insights_menu_items

Modify the Alpha Insights menu structure by adding, removing, or reordering menu items.

### Description

This is the recommended filter for customizing the Alpha Insights navigation menu. It provides a structured array of menu items that you can modify before the menu is rendered. Perfect for adding custom pages, removing unwanted sections, or reorganizing the navigation.

#### Location

File: `includes/classes/WPDAI_Admin_Menu.php`

Method: `WPDAI_Admin_Menu::register_alpha_insights_menu()`

Line: ~561

### Parameters

Parameter | Type | Description
--- | --- | ---
$alpha_insights_menu | array | Multi-dimensional array of menu items and submenus

#### Return

Type: array

Description: Modified menu structure array

### Menu Item Structure

    array(
        'menu-slug'   =>
        array(
        'label'   => 'Display Name',
        'url'   => admin_url('admin.php?page=menu-slug'),
        'icon'   => '<svg>...</svg>',
        // Optional icon HTML
        'order'   => 10,
        // Optional ordering
        'children'   =>
        array(
        // Optional submenu items
        'submenu-slug'   =>
        array(
        'label'   => 'Submenu Item',
        'url'   => admin_url('admin.php?page=submenu-slug'),
        'order'   => 1
    )
    )
    )
    )

### Example Usage

### Add Custom Menu Item

    add_filter( 'wpd_alpha_insights_menu_items', 'add_custom_menu_item' );
    function add_custom_menu_item( $menu )
    {
        // Add new top-level menu item
        $menu['custom-analytics'] = array(
            'label' => 'Custom Analytics',
            'url' => admin_url('admin.php?page=custom-analytics'),
            'icon' => '<svg width="20" height="20"><path d="M10 2L2 7v10l8 5 8-5V7z"/></svg>',
            'order' => 50,
            'children' => array(
                'overview' => array(
                    'label' => 'Overview',
                    'url' => admin_url('admin.php?page=custom-analytics&subpage=overview'),
                    'order' => 1
                ),
                'detailed' => array(
                    'label' => 'Detailed Reports',
                    'url' => admin_url('admin.php?page=custom-analytics&subpage=detailed'),
                    'order' => 2
                )
            )
        );
        return $menu;
    }

### Remove Menu Items

    add_filter( 'wpd_alpha_insights_menu_items', 'remove_unwanted_items' );
    function remove_unwanted_items( $menu )
    {
        // Remove specific menu items
        unset( $menu['website-traffic'] );
        // Remove Website Traffic section
        unset( $menu['integrations'] );
        // Remove Integrations section

        // Remove specific submenu item
        if ( isset( $menu['reports']['children']['product-performance'] ) )
        {
            unset( $menu['reports']['children']['product-performance'] );
        }
        return $menu;
    }

### Reorder Menu Items

    add_filter( 'wpd_alpha_insights_menu_items', 'reorder_menu' );
    function reorder_menu( $menu )
    {
        // Change order values to reorder menu
        if ( isset( $menu['dashboard'] ) )
        {
            $menu['dashboard']['order'] = 1;
        }
        if ( isset( $menu['reports'] ) )
        {
            $menu['reports']['order'] = 2;
        }
        if ( isset( $menu['expenses'] ) )
        {
            $menu['expenses']['order'] = 3;
        }
        if ( isset( $menu['settings'] ) )
        {
            $menu['settings']['order'] = 99;
            // Move to end
        }
        return $menu;
    }

### Rename Menu Items

    add_filter( 'wpd_alpha_insights_menu_items', 'rename_menu_items' );
    function rename_menu_items( $menu )
    {
        // Change "Reports" to "Analytics"
        if ( isset( $menu['reports'] ) )
        {
            $menu['reports']['label'] = 'Analytics';
        }
        // Change "Expenses" to "Costs"
        if ( isset( $menu['expenses'] ) )
        {
            $menu['expenses']['label'] = 'Cost Management';
        }
        return $menu;
    }

### Add Submenu Items

    add_filter( 'wpd_alpha_insights_menu_items', 'add_custom_submenu' );
    function add_custom_submenu( $menu )
    {
        // Add custom submenu under Reports
        if ( isset( $menu['reports']['children'] ) )
        {
            $menu['reports']['children']['custom-report'] = array(
                'label' => 'Custom Report',
                'url' => admin_url('admin.php?page=reports&subpage=custom-report'),
                'order' => 999
            );
        }
        return $menu;
    }

### Conditional Menu Items

    add_filter( 'wpd_alpha_insights_menu_items', 'conditional_menu_items' );
    function conditional_menu_items( $menu )
    {
        // Only show advanced features to administrators
        if ( ! current_user_can( 'manage_options' ) )
        {
            unset( $menu['advanced-settings'] );
        }
        // Show integration menu only if API is connected
        if ( ! get_option( 'my_api_connected' ) )
        {
            unset( $menu['integrations'] );
        }
        // Add wholesale menu for wholesale users
        $user = wp_get_current_user();
        if ( in_array( 'wholesale_customer', $user->roles ) )
        {
            $menu['wholesale-reports'] = array(
                'label' => 'Wholesale Reports',
                'url' => admin_url('admin.php?page=wholesale-reports'),
                'order' => 25
            );
        }
        return $menu;
    }

### Group Related Items

    add_filter( 'wpd_alpha_insights_menu_items', 'group_menu_items' );
    function group_menu_items( $menu )
    {
        // Create new "Marketing" parent menu
        $menu['marketing'] = array(
            'label' => 'Marketing',
            'url' => admin_url('admin.php?page=marketing'),
            'order' => 30,
            'children' => array()
        );
        // Move Facebook Ads under Marketing
        if ( isset( $menu['facebook-ads'] ) )
        {
            $menu['marketing']['children']['facebook-ads'] = $menu['facebook-ads'];
            unset( $menu['facebook-ads'] );
        }
        // Move Google Ads under Marketing
        if ( isset( $menu['google-ads'] ) )
        {
            $menu['marketing']['children']['google-ads'] = $menu['google-ads'];
            unset( $menu['google-ads'] );
        }
        return $menu;
    }

### Add External Links

    add_filter( 'wpd_alpha_insights_menu_items', 'add_external_links' );
    function add_external_links( $menu )
    {
        $menu['help-docs'] = array(
            'label' => 'Documentation',
            'url' => 'https://docs.example.com',
            'icon' => '<svg>...</svg>',
            'order' => 100,
            'external' => true // Add custom flag
        );
        return $menu;
    }

### Best Practices

- Use unique slugs for custom menu items
- Check if menu items exist before modifying them
- Use the 'order' property to control menu sequence
- Keep menu structure shallow (max 2-3 levels)
- Test menu with different user roles and capabilities
- Provide fallback icons or use existing ones

### Important Notes

- Menu items are cached - clear cache after changes
- URLs should use `admin_url()` for WordPress compatibility
- Lower order numbers appear first in the menu
- Children inherit parent visibility/capability requirements
- Custom pages need to be registered separately

### Default Menu Items

Alpha Insights includes these default menu items:

- `dashboard` - Main dashboard
- `reports` - Report builder
- `expenses` - Expense management
- `cost-of-goods` - Cost of goods manager
- `website-traffic` - Traffic analytics
- `advertising` - Ad campaign tracking
- `integrations` - Third-party integrations
- `settings` - Plugin settings

### Menu Item Properties

Property | Type | Required | Description
--- | --- | --- | ---
label | string | Yes | Display text
url | string | Yes | Link destination
icon | string | No | SVG icon HTML
order | int | No | Menu position
children | array | No | Submenu items

### Debugging

    add_filter( 'wpd_alpha_insights_menu_items', 'debug_menu_structure', 999 );
    function debug_menu_structure( $menu )
    {
        error_log( 'Alpha Insights Menu Structure:' );
        error_log( print_r( $menu, true ) );
        return $menu;
    }

### Related Filters

- wpd_alpha_insights_menu_html - Modify rendered menu HTML
- wpd_alpha_insights_active_parent_menu_item - Control active parent
- wpd_alpha_insights_active_submenu_item - Control active submenu

### Related Classes

- `WPDAI_Admin_Menu` - Menu management class