WordPress Advanced Access Manager Plugin

Introduction

AAM was designed and implemented by developers for developers. It is flexible, powerful and has a light API as well as dozens of internal hooks and configurations.

We’ve tried hard to be less opinionated about how things have to be done and focused only on what is most essential for developers to create beautiful websites. That is why, while we providing an abstract layer on top of the WordPress core access controls, we also keep it simple.

The developer reference page is structured in the way that you can learn the concepts and technics by practicing them. That is why each section, contains at least one snippet of copy&paste code.

Core Concepts

AAM is tightly integrated with WordPress core. Our main goal is to find a way to utilize existing WordPress functionality and do not create alternative ways or reinvent existing features that supposedly work “better”.

We believe that the current WordPress core state of functionality is as good as it can be considering the amount of website using it and impressive backward compatibility. That is why AAM does not create any new database tables and uses a couple, slightly modified external libraries for JWT and Access Policy services. You can find those libraries in the /vendor folder.

To master AAM, you should understand few fundamental concepts: Objects, Subjects, ConfigPress and finally how access settings are inherited (propagated).

Objects

AAM object is a website resource that you manage access to for your users, roles or visitors. An object can be any website post, page, category, backend menu, etc.

In this sample, we simply dumping the entire AAM post object for the current post ID:

<?php

/**
 * Plugin Name: AAM Cauldron
 * Description: Just a playground for any functionality that is related to AAM
 * Version: 0.0.1
 * Author: Vasyl Martyniuk 
 * Author URI: https://vasyltech.com
 **/

if (defined('ABSPATH')) {
    add_action('wp', function () {
        $current_id = get_the_ID();

        if ($current_id) {
            var_dump(\AAM::getUser()->getObject(
                \AAM_Core_Object_Post::OBJECT_TYPE, $current_id
            ));
            exit;
        }
    });
}

An object can also be used as a “container” for some general-purpose settings for any user, role or visitor. For example login, logout redirect, default category or access denied redirect rules. The only big difference between objects that contain access settings and general-purpose settings is in merging mechanism when a user has two or more roles. While in the first case, AAM merges access settings based on defined preference, in the second case, the last role overrides settings from the previous role.

In the example below, we are checking if access denied redirect rule for the frontend is set to redirect the user to some URL, and if so, then dump all the access denied redirect settings.

<?php

/**
 * Plugin Name: AAM Cauldron
 * Description: Just a playground for any functionality that is related to AAM
 * Version: 0.0.1
 * Author: Vasyl Martyniuk 
 * Author URI: https://vasyltech.com
 **/

if (defined('ABSPATH')) {
    add_action('wp', function () {
        $redirect = \AAM::getUser()->getObject(
            \AAM_Core_Object_Redirect::OBJECT_TYPE
        );

        if ($redirect->get('frontend.redirect.type') === 'url') {
            var_dump($redirect->getOption());
        }
    });
}

Under the hood, each declared object extends abstract class AAM_Core_Object that contains minimum required methods to handle the most common use-cases. Each individual instance of an object may have a different set of methods to do things that are specific to its domain.

AAM has several core objects included in the basic AAM version and few available with add-ons. You can find the complete list of all available objects in the Core Objects section or, if necessary, create your own object. You can learn about creating a custom object from the Create Custom Object section.

Subjects

AAM subject is the general definition for whom access is managed for. While object answers the question how, subject answers the question who.

For example, you may restrict access to the website URI /category/protected-content (object URI) for all users (subject User) that belong to role (subject Role) Subscribers.

AAM comes with 4 predefined subjects that cover all the known user-cases: User, Role, Visitor and Default.

In the majority of the cases, you will work with either subject type User or Visitor to determine if current user/visitor has access to requested resource or can perform certain action upon it.

To simplify the developer’s duty, AAM comes with a simple static method that returns a correct subject type based on the sender’s state:

// Return current user: either AAM_Core_Subject_User or AAM_Core_Subject_Visitor
AAM::getUser();

// The alternative way to retrieve current user
AAM::api()->getUser();

To learn more about each core subject and how to work with them, refer to the Core Subjects section.

ConfigPress

ConfigPress is the INI-based configuration engine for AAM core. The most complete list of available configurations you can find in the ConfigPress section, however you are free to define your own configurations and programmatically retrieve them with AAM::api()->getConfig method.

For example if you defined a custom JWT token expiration, you can retrieve it as following:


; JWT token will expire in 1 hour
authentication.jwt.expires = 3600

$expires = AAM::api()->getConfig("authentication.jwt.expires", 86400);

where the first argument is a ConfigPress option while the second argument is a default value that will be returned if option is not defined.

Inheritance Mechanism

AAM has a quite sophisticated and flexible access inheritance mechanism. It is something that “stitches” together objects and subjects based on how they are related to each other.

The major benefit for using AAM comes with the fact that it takes into consideration relationships between objects, users and roles, and merges settings accordingly to their’s hierarchical placement (where lower-level settings override higher-level settings).

In the first example, we will programmatically restrict access to the backend menu “Pages” for everybody, and override it for Administrator role.

<?php

/**
 * Plugin Name: AAM Cauldron
 * Description: Just a playground for any functionality that is related to AAM
 * Version: 0.0.1
 * Author: Vasyl Martyniuk 
 * Author URI: https://vasyltech.com
 **/

if (defined('ABSPATH')) {
    register_activation_hook(__FILE__, function() {
        $menu = \AAM::api()->getDefault()->getObject(
            \AAM_Core_Object_Menu::OBJECT_TYPE
        );

        // Restricting access to the "Pages" backend menu
        $menu->updateOptionItem('edit.php?post_type=page', true)->save();

        // Explicitly override access only for the Administrator role
        \AAM::api()->getRole('administrator')->getObject(
            \AAM_Core_Object_Menu::OBJECT_TYPE
        )->updateOptionItem('edit.php?post_type=page', false)->save();
    });
}

API

AAM offers a single API endpoint that gives you all necessary methods to work with AAM objects, subjects and configurations.

AAM::api

Description

object AAM::api()

Returns

Instance of AAM API object.

AAM:api()->getConfig

Get AAM configuration that is either set through AAM UI or on the Settings->ConfigPress tab.

Description

mixed AAM::api()->getConfig(string $option, mixed $default = null)

Parameters

option – option name
default – value to return if option does not exist (default value is null)

Returns

Configuration value or default value if nothing was found. Typically it returns string or array.

Example

if (AAM::api()->getConfig('core.settings.frontendAccessControl')) {
    // Access to the frontend is enabled. Do something here.
}

AAM:api()->getRole

AAM:api()->getUser

Get the user by the specified ID or current user if none is provided.

Description

AAM_Core_Subject AAM::api()->getUser(int $id = null)

Parameters

id – optional user Id.

Returns

If $id is not provided, AAM returns either AAM_Core_Subject_Visitor instance if user is not authenticated otherwise AAM_Core_Subject_User.

Example

// Check if current visitor has ability to see Post Categories widgets on the frontend.
// Get access settings for current user to frontend widgets
$metaboxes = AAM::api()->getUser()->getObject('metabox');

// Check if user has access to the widget that shows list of categories
if ($menu->has('widgets', 'WP_Widget_Categories')) {
    echo 'The list of categories is denied. Please login to see them';
}

AAM:api()->getVisitor

AAM::api()->getDefault

Core Objects

Object, in the context of AAM functionality, is something that you manage access to (e.g. post, page, category, backend menu) or a collection or settings/properties (e.g. login redirect, access denied redirect).

Object never exists independently from a subject (user, visitor, role or default settings) and always has to be obtained through an instance of AAM_Core_Subject with the getObject() method.

Description

AAM_Core_Object AAM_Core_Subject->getObject(string $type, mixed $id = null, bool $skipInheritance = false)

Parameters

type – is an object type like post, menu, capability etc.
id – optional. Some objects do not have ids (e.g. menu, login redirect) and some do (e.g. post, term, type).
$skipInheritance – optional. If set as true, then do not invoke inheritance mechanism and return settings that defined only for current subject

Returns

Instance of AAM object that derives from AAM_Core_Object abstract class.

Example

// Get instance of Post with ID 5 that has access settings for user with ID 2
$post = AAM::api()->getUser(2)->getObject('post', 5);

AAM_Core_Object_Menu

AAM_Core_Object_Toolbar

AAM_Core_Object_Metabox

AAM_Core_Object_Post

AAM_Core_Object_Policy

AAM_Core_Object_Uri

AAM_Core_Object_Route

AAM_Core_Object_Redirect

AAM_Core_Object_LoginRedirect

AAM_Core_Object_LogoutRedirect

AAM\AddOn\IPCheck\Object\IPCheck

AAM\AddOn\PlusPackage\Object\Taxonomy

AAM\AddOn\PlusPackage\Object\Term

AAM\AddOn\PlusPackage\Object\Type

Core Subjects

AAM_Core_Subject_User

AAM_Core_Subject_Role

AAM_Core_Subject_Visitor

AAM_Core_Subject_Default

Filters & Actions

AAM has numerous of hooks that can be used by custom functionality to extend access management. In WordPress core hooks are divided into two categories – filters and actions so AAM hooks are named accordingly.

aam_menu_object_option_filter

aam_metabox_object_option_filter

aam_post_object_option_filter

aam_route_object_option_filter

aam_uri_object_option_filter

aam_token_typecast_filter

aam_post_read_access_pipeline_filter

aam_extract_jwt_filter

aam_auth_response_filter

aam_post_add_role_action

aam_post_update_role_action

aam_clear_settings_action

aam_initialize_user_action

ConfigPress

How to ..?

Create Custom Object

Developer Reference

Introduction

Core Concepts

Objects

Subjects

ConfigPress

Inheritance Mechanism

API

AAM::api

Description

Returns

AAM:api()->getConfig

Description

Parameters

Returns

Example

AAM:api()->getRole

AAM:api()->getUser

Description

Parameters

Returns

Example

AAM:api()->getVisitor

AAM::api()->getDefault

Core Objects

Description

Parameters

Returns

Example

AAM_Core_Object_Menu

AAM_Core_Object_Toolbar

AAM_Core_Object_Metabox

AAM_Core_Object_Post

AAM_Core_Object_Policy

AAM_Core_Object_Uri

AAM_Core_Object_Route

AAM_Core_Object_Redirect

AAM_Core_Object_LoginRedirect

AAM_Core_Object_LogoutRedirect

AAM\AddOn\IPCheck\Object\IPCheck

AAM\AddOn\PlusPackage\Object\Taxonomy

AAM\AddOn\PlusPackage\Object\Term

AAM\AddOn\PlusPackage\Object\Type

Core Subjects

AAM_Core_Subject_User

AAM_Core_Subject_Role

AAM_Core_Subject_Visitor

AAM_Core_Subject_Default

Filters & Actions

aam_menu_object_option_filter

aam_metabox_object_option_filter

aam_post_object_option_filter

aam_route_object_option_filter

aam_uri_object_option_filter

aam_token_typecast_filter

aam_post_read_access_pipeline_filter

aam_extract_jwt_filter

aam_auth_response_filter

aam_post_add_role_action

aam_post_update_role_action

aam_clear_settings_action

aam_initialize_user_action

ConfigPress

How to ..?

Create Custom Object