Admin Toolbar

The Admin Toolbar service provides a programmatic API for managing visibility of WordPress admin toolbar items through the AAM Framework.

This service allows you to:

• Retrieve all registered admin toolbar items
• Retrieve a specific toolbar item
• Hide (deny) toolbar items
• Allow previously restricted toolbar items
• Reset toolbar permissions
• Check current access state for toolbar items

# Definition

class AAM_Framework_Service_AdminToolbar {

    public deny(string $item_id) : bool
    public allow(string $item_id) : bool
    public reset(string $item_id = null) : bool

    public is_denied(string $item_id) : bool
    public is_allowed(string $item_id) : bool

}

# Overview

The Admin Toolbar service manages access permissions for items displayed in the WordPress admin toolbar (WP_Admin_Bar).

Internally, the service:

• Reads toolbar items from the WordPress admin bar
• Normalizes the toolbar structure
• Persists permissions through AAM resources
• Supports parent-child inheritance for restrictions
• Caches toolbar structure for performance optimization

# Service Methods

# deny

Restrict (hide) a toolbar item.

public function deny(string $item_id): bool

# Parameters

# Return Value

Returns:

• true on success
• WP_Error on failure

# Example

$toolbar = AAM::api()->admin_toolbar();

$toolbar->deny('comments');

When a parent toolbar item is denied, all child items are considered restricted as well.

# allow

Allow access to a toolbar item.

public function allow(string $item_id): bool

# Parameters

# Return Value

Returns:

• true on success
• WP_Error on failure

# Example

$toolbar = AAM::api()->admin_toolbar();

$toolbar->allow('updates');

# reset

Reset toolbar permissions.

public function reset(string $item_id = null): bool

# Parameters

# Return Value

Returns:

• true on success
• WP_Error on failure

# Examples

Reset a specific item permission:

$toolbar->reset('comments');

Reset all toolbar permissions:

$toolbar->reset();

When no item identifier is provided, all toolbar permissions for the current access level are removed.

# is_denied

Check if a toolbar item is restricted.

public function is_denied(string $item_id): bool

# Parameters

# Return Value

Returns:

• true if denied
• false if allowed

# Example

if ($toolbar->is_denied('comments')) {
    // Toolbar item is hidden
}

# Permission Resolution Logic

The method determines access in the following order:

1. Direct item permission
2. Parent item permission inheritance
3. Third-party filter overrides

# is_allowed

Check if a toolbar item is allowed.

public function is_allowed(string $item_id): bool

# Parameters

# Return Value

Returns:

• true if allowed
• false if denied

# Example

if ($toolbar->is_allowed('site-name')) {
    // Toolbar item is visible
}

Although not listed in the minimal definition, the service also exposes helper methods for retrieving toolbar structure.

# get_items

Retrieve all admin toolbar items.

public function get_items(): array

# Return Value

Returns a normalized toolbar tree structure.

# Example

$items = $toolbar->get_items();

# Response Structure

[
    [
        'slug' => 'site-name',
        'uri' => '/wp-admin/',
        'name' => 'My Site',
        'is_restricted' => false,
        'children' => [
            [
                'slug' => 'dashboard',
                'uri' => '/wp-admin/',
                'name' => 'Dashboard',
                'is_restricted' => false,
                'parent_id' => 'site-name'
            ]
        ]
    ]
]

# items

Alias for get_items.

public function items(): array

# get_item

Retrieve a single toolbar item.

public function get_item(string $slug): array

# Parameters

# Exceptions

Throws OutOfRangeException if item does not exist.

# Example

$item = $toolbar->get_item('comments');

# item

Alias for get_item.

public function item(string $item_id): array

# Toolbar Item Structure

Each toolbar item is normalized into the following structure.

# Top-Level Item

[
    'slug' => 'comments',
    'uri' => '/wp-admin/edit-comments.php',
    'name' => 'Comments',
    'is_restricted' => false,
    'children' => []
]

# Child Item

[
    'slug' => 'new-post',
    'uri' => '/wp-admin/post-new.php',
    'name' => 'Post',
    'is_restricted' => false,
    'parent_id' => 'new-content'
]

# Permission Inheritance

Toolbar permissions inherit from parent items.

For example:

new-content
 ├── new-post
 ├── new-page
 └── media

If new-content is denied:

$toolbar->deny('new-content');

All child items are automatically treated as denied.

# Toolbar Item Identification

Toolbar items are identified by their WordPress admin bar node IDs.

Examples:

# Internal Permission Model

Permissions are stored using the AAM resource system with:

resource_type = TOOLBAR
action = list

The service internally maps:

deny()  => effect = deny
allow() => effect = allow

# Caching

The toolbar structure is cached using the option:

aam_admin_toolbar

The cache lifetime is:

31536000 seconds (1 year)

The cache is rebuilt automatically when toolbar items are reloaded.

# WordPress Integration

The service integrates directly with:

• WP_Admin_Bar
• WordPress toolbar node hierarchy
• AAM access level resources
• WordPress filter system

# Filters

# aam_admin_toolbar_is_denied_filter

Allows third-party customization of toolbar access decisions.

# Usage

add_filter(
    'aam_admin_toolbar_is_denied_filter',
    function($is_denied, $slug, $resource) {

        if ($slug === 'comments') {
            return true;
        }

        return $is_denied;
    },
    10,
    3
);

# Parameters

# Error Handling

All public methods internally catch exceptions and return:

WP_Error

on failure.

Recommended usage:

$result = $toolbar->deny('comments');

if (is_wp_error($result)) {
    echo $result->get_error_message();
}

# Usage Example

# Restrict Toolbar Items for a Role

$toolbar = AAM::api()->admin_toolbar();

$toolbar->deny('comments');
$toolbar->deny('updates');
$toolbar->deny('customize');

# Check Toolbar Visibility

if ($toolbar->is_allowed('updates')) {
    echo 'Updates menu is visible';
}

# Reset All Toolbar Permissions

$toolbar->reset();

# Performance Notes

The service uses:

• Reflection API to access toolbar nodes
• In-memory toolbar caching
• Persistent database caching
• Pre-normalized toolbar structures

This minimizes repeated traversal of the WordPress admin toolbar tree.

# Important Notes

# Group and Container Nodes

Toolbar nodes of type:

• container
• group

are ignored during normalization because they are structural wrappers only.

# HTML Sanitization

Toolbar titles are sanitized with:

wp_strip_all_tags()

before storage.

# URI Normalization

Toolbar URLs are converted into relative paths by stripping the site URL.

Example:

https://example.com/wp-admin/edit.php

becomes:

/wp-admin/edit.php