Capabilities

The AAM_Framework_Service_Capabilities service provides a programmatic API for managing WordPress capabilities within the AAM Framework.

This service allows developers to:

• Add or remove capabilities
• Explicitly allow or deny capabilities
• Change capability slugs
• Check capability existence and state
• Work with dynamically assigned capabilities through AAM’s abstraction layer

The service works with both:

• WordPress Roles (WP_Role)
• WordPress Users (WP_User)

# Definition

class AAM_Framework_Service_Capabilities {

    public add(string $capability, bool $is_granted = true, bool $ignore_format = false) : bool
    public remove(string $capability) : bool
    public deny(string $capability, bool $ignore_format = false) : bool
    public allow(string $capability, bool $ignore_format = false) : bool
    public replace(string $old_slug, string $new_slug, bool $ignore_format = false) : bool
    public exists(string $capability) : bool

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

}

# Overview

The Capabilities service acts as a high-level abstraction over the native WordPress capability system.

Unlike direct WordPress capability manipulation, this service introduces:

• Dynamic capability management
• JSON policy compatibility
• Explicit allow/deny states
• Runtime capability manipulation
• AAM resource integration
• Extensible filtering hooks

# Supported Access Levels

The service only supports the following access levels:

Attempting to manipulate capabilities for unsupported access levels triggers a RuntimeException.

# Capability States

A capability can exist in one of three states:

Example:

$capabilities->allow('edit_posts');
$capabilities->deny('delete_users');

# Capability Format Validation

By default, capability slugs must match:

/^[a-z\d\-_]+/

Valid examples:

edit_posts
manage_options
custom-capability
plugin_feature_1

Invalid examples:

EditPosts
edit posts
edit.posts

To bypass validation, pass true as the third parameter $ignore_format:

$capabilities->add('Custom.Capability', true, true);

# Methods

# add()

Add a capability to the current access level.

public add(
    string $capability,
    bool $is_granted = true,
    bool $ignore_format = false
) : bool

# Parameters

# Returns

# Examples

Grant capability:

$service->add('edit_private_posts');

Add denied capability:

$service->add('delete_users', false);

Ignore slug validation:

$service->add('Custom.Capability', true, true);

# Exceptions

Throws internally:

• InvalidArgumentException
• RuntimeException

Converted to WP_Error through the framework error handler.

# remove()

Remove capability from the access level.

public remove(string $capability) : bool

# Parameters

# Returns

# Example

$service->remove('edit_private_posts');

This method completely removes the capability assignment.

It differs from deny() because:

# allow()

Explicitly grant a capability.

public allow(
    string $capability,
    bool $ignore_format = false
) : bool

# Example

$service->allow('manage_options');

Alias of:

add($capability, true);

# deny()

Explicitly deny a capability.

public deny(
    string $capability,
    bool $ignore_format = false
) : bool

# Example

$service->deny('publish_posts');

Alias of:

add($capability, false);

Denied capabilities remain explicitly assigned.

Example:

$service->deny('edit_posts');

$service->exists('edit_posts'); // true
$service->is_denied('edit_posts'); // true

# replace()

Replace one capability slug with another.

public replace(
    string $old_slug,
    string $new_slug,
    bool $ignore_format = false
) : bool

# Parameters

# Example

$service->replace(
    'old_plugin_capability',
    'new_plugin_capability'
);

# exists()

This method checks whether the capability exists directly on the access level. It does NOT evaluate inherited WordPress permissions.

public exists(string $capability) : bool

# Example

$service->exists('edit_posts');

A denied capability still exists.

$service->deny('edit_posts');

$service->exists('edit_posts'); // true

# is_allowed()

Determine if capability is granted.

public is_allowed(string $capability) : bool

The method resolves capability status in the following order:

1. Explicit AAM permission
2. aam_capability_is_allowed_filter
3. Native WordPress capability resolution

# Example

if ($service->is_allowed('manage_options')) {
    // Access granted
}

# is_denied()

Determine if capability is denied.

public is_denied(string $capability) : bool

# Example

if ($service->is_denied('delete_users')) {
    // Access denied
}

# WordPress Integration

Internally the service relies on native WordPress APIs:

# AAM Filters

# aam_capability_is_allowed_filter

Override capability resolution.

# Example

add_filter(
    'aam_capability_is_allowed_filter',
    function($result, $capability, $resource) {

        if ($capability === 'temporary_access') {
            return true;
        }

        return $result;
    },
    10,
    3
);

# Error Handling

All public methods wrap exceptions and return:

WP_Error

instead of throwing exceptions directly.

# Common Errors

# Invalid Capability Slug

$service->add('Invalid Capability');

Result:

WP_Error: Valid capability slug is required

# Unsupported Access Level

WP_Error: The access level visitor cannot have capabilities