AAM Developer Reference

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

We are trying really hard to be less opinionated about how things need to be done and more focused only on what is the most essential for developers to create beautiful websites.

Please do not hesitate to provide feedback or start contributing to the AAM core to the AAM GitHub repository.

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

We believe that current WordPress core state of functionality is as good as it can be considering amount of website using it and impressive backward compatibility. That is why AAM does not create any new database tables or utilizes external frameworks.

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

On one hand, AAM Object is a website resource that you want to manage access to for your users, roles or visitors. For example it can be any website post, page, hierarchical term, backend menu etc.

On another hand, AAM Object is a container for some settings for any user, role or visitor. For example login, logout redirect or access denied redirect rules.

AAM has several core objects included in the basic AAM version and few available with premium extensions. Some objects are listed below in the Core Objects section. There are few objects that are omitted from this tutorial because they either should not be used directly or still not finalized.

You can create your own object and register it with AAM core by utilizing aam-object-filter filter. Please do not hesitate to contact us directly if you need a custom object. We are more than happy to help you out.

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:

[aam]
; 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.

To learn more about the idea of ConfigPress please check AAM Configurations article.

AAM has the most sophisticated access inheritance mechanism that is available for the WordPress CMS. You will not find other frameworks or plugins for WordPress that have similar functionality.

AAM takes in consideration relationships between objects, users and roles, and propagates settings accordingly to their’s hierarchical placement. For example, WordPress user can have a parent role and if no access settings defined for that specific user, AAM tries to inherit access settings from the user’s parent role and even if role does not have any settings, AAM fallback to the default (global) settings.

It gets even more complex with WordPress content as any post can have a parent post or term and any term can have multiple parent terms.

You can learn more about inheritance mechanism from the How does AAM inherit access settings article.

We tried to make it easy for you to work with AAM functionality. That is why you have only single API class that gives you all necessary methods to work with AAM objects and configurations.

You should always use AAM::api() static method to obtain an instance of AAM API. Do not use other classes directly because most likely they will be changed in the near future and we cannot guarantee that they’ll be backward compatible. Also do not rely on the name of the object that AAM::api() returns because the name will be changes in the future AAM releases.

The AAM::api() static method returns the singleton of AAM API object that has all necessary methods to work with current user and AAM configurations.

Description

object AAM::api()

Returns

Instance of AAM API object.

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.
}

Get user by 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';
}

Deny current HTTP request. By default it invokes AAM core functionality that will redirect user based on Access Denied Redirect rule.

Description

void AAM::api()->denyAccess(mixed $params = null)

Parameters

• params – optional list of additional parameters that will be passed to the access denied handler.

Example

// Deny access to a website if user's email domain is not mydomain.com.
$api = AAM::api();

// Get current user
$user = $api->getUser();

// If user's email does not belong to mydomain.com domain, then deny access
if (!preg_match('/@mydomain\.com$/i', $user->user_email)) {
    $api->denyAccess();
}

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 user and always has to be obtained through an instance of AAM either AAM_Core_Subject_User or AAM_Core_Subject_Visitor with a the getObject() method.

Description

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

Parameters

• type – is an object type like post, menu, capability etc.
• id – optional object id. Some objects do not have ids (e.g. menu, login redirect) and some do (e.g. post, term, type).

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);

WordPress backend menu object contains access settings that are defined for user.

Note! It is useless to use this object with AAM_Core_Subject_Visitor instance because visitors (unauthenticated users) do not have access to the backend.

Get Instance

$object = AAM::api()->getUser()->getObject('menu');

Methods

• boolean AAM_Core_Object_Menu->has(string $menu)

• boolean AAM_Core_Object_Menu->allow(string $menu)

• boolean AAM_Core_Object_Menu->deny(string $menu)

The $menu parameter is literally a URI with GET params. For example the full URL to the Pages menu is https://mydomain.com/wp-admin/edit.php?post_type=pages. In this case highlighted part of the mentioned URL should be passed as $menu parameter.

WordPress metaboxes and widgets object contains access settings that are defined for user or visitor for both frontend widgets and backend metaboxes and widgets.

Get Instance

$object = AAM::api()->getUser()->getObject('metabox');

Methods

• boolean AAM_Core_Object_Metabox->has(string $screen, string $id)

• boolean AAM_Core_Object_Metabox->allow(string $screen, string $id)

• boolean AAM_Core_Object_Metabox->deny(string $screen, string $id)

In WordPress, metaboxes and widgets are rendered for a specific $screen. That is why you can have two or more metaboxes with the same ID that are rendered on different screens. You can find the correct screen and ID on the Metaboxes & Widgets tab with AAM 5.4 or higher.

Post object contains all access settings that are defined for user or visitor for any post, page or custom post type for frontend, backend and WP API.

Typically there is an assumption that you either “allow” or “deny” access to a post and this is what most plugins and frameworks for WordPress do today. However with AAM you have couple dozens of different ways to customize access to your content. For example you can limit content, set time expiration, monetize access or even specify how many times user can open a post for reading. And you can do that for frontend, backend and RESTful/RPC-XML API separately and for any user, group of users (roles), visitors or set a default access for everybody.

Get Instance

// the_ID() is WordPress core function that returns current post ID
$object = AAM::api()->getUser()->getObject('post', the_ID());

Note! You have to provide the second argument which is a valid post ID and under post we mean any post, page, attachment or custom post type. So literally any post that is stored inside the wp_posts database table.

Methods

• boolean AAM_Core_Object_Post->has(string $property)

• boolean AAM_Core_Object_Post->update(string $property, mixed $value)

• boolean AAM_Core_Object_Post->remove(string $property)

Properties

• frontend.list – boolean true/false or integer 1/0. Either show or hide a post on the frontend.
• frontend.list_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either show or hide a post on the frontend for users that are not authors of a post.
• frontend.read – boolean true/false or integer 1/0. Either allow or deny access to read, open or view a post.
• frontend.read_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either allow or deny access to read, open or view a post by user who is not an author or a post.
• frontend.limit – boolean true/false or integer 1/0. Limit access to a post by replacing post’s content with a defined teaser message.
• frontend.teaser – string. Either plain or HTML text that is used to replace a post’s content if frontend.limit property is set. The teaser message may also contain shortcodes.
• frontend.access_counter – boolean true/false or integer 1/0. Activate post access counter and restrict access to read, view or open post when specified threshold met.
• frontend.access_counter_limit – integer. Number of times a post can be read, viewed or opened before it gets restricted.
• frontend.comment – boolean true/false or integer 1/0. Either allow or restrict ability to comment on post.
• frontend.redirect – boolean true/false or integer 1/0. Redirect a user to a different location. Good way to redirect if post or page is deprecated or temporary is not available for reading, viewing or opening.
• frontend.location – string. Combination of type of redirect (“page” for existing page; “url” for valid URL; “callback” for custom PHP callback) and redirect value separated by pipe “|” symbol. For example “page|123” is redirect to an existing page ID 123; “url|https://mydomain.com/hello” is redirect to the URL https://mydomain.com/hello; and “callback|MyCustomClass::redirect” is a custom callback that invokes MyCustomClass::redirect static method.
• frontend.protected – boolean true/false or integer 1/0. Either post is password protected or not.
• frontend.password – string. Password that a post is protected with if frontend.password is set.
• frontend.expire – boolean true/false or integer 1/0. Either access to a post expire or not.
• frontend.expire_datetime – datetime. Valid date and time string in the future that can be evaluated with strtotime PHP function. For example 2018-07-17 15:10:25.
• frontend.monetize – boolean true/false or integer 1/0. Note! Available with E-Commerce premium extension. Either monetize access to a post or not. If set, then access will be restricted to a post until user purchases access to it.
• frontend.eproduct – integer. Valid custom post type ID that represents the E-Product user has to purchase in order to obtain access to a post.
• backend.list – boolean true/false or integer 1/0. Either show or hide a post on the backend.
• backend.list_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either show or hide a post on the backend for users that are not authors of a post.
• backend.edit – boolean true/false or integer 1/0. Either allow or deny access to edit a post on the backend.
• backend.edit_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either allow or deny access to edit a post on the backend by an user who is not a post’s author.
• backend.delete – boolean true/false or integer 1/0. Either allow or deny to trash a post on the backend.
• backend.delete_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either allow or deny to trash a post on the backend by an user who is not a post’s author.
• backend.publish – boolean true/false or integer 1/0. Either allow to publish a post on the backend if it is not published yet.
• backend.publish_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either allow or deny to publish a post by an user who is not a post’s author on the backend if it is not published yet.
• api.list – boolean true/false or integer 1/0. Either filter out or not a post from the post list during an RESTful/RPC-XML API request.
• api.list_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either filter out or not a post from the post list during an RESTful/RPC-XML API request for users that are not authors of a post.
• api.read – boolean true/false or integer 1/0. Either allow or deny access to retrieve a post during an RESTful/RPC-XML API request.
• api.read_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either allow or deny access to retrieve a post during an RESTful/RPC-XML API request by an user who is not a post’s author.
• api.limit – boolean true/false or integer 1/0. Either limit access to a post content during the RESTful/RPC-XML API request. If set, the post’s content will be replaced with teaser message.
• api.teaser – string. Either plain or HTML text that is used to replace a post content if api.limit property is set.
• api.access_counter – boolean true/false or integer 1/0. Activate post access counter and restrict access to retrieve a post when specified threshold met.
• api.access_counter_limit – integer. Number of times a post can be retrieved before it gets restricted.
• api.comment – boolean true/false or integer 1/0. Either allow or restrict ability to comment on post.
• api.protected – boolean true/false or integer 1/0. Either post is password protected or not.
• api.password – string. Password that a post is protected with if api.password is set.
• api.expire – boolean true/false or integer 1/0. Either access to a post expire or not.
• api.expire_datetime – datetime. Valid date and time string in the future. For example 2018-07-17 15:10:25.
• api.edit – boolean true/false or integer 1/0. Either allow or deny access to update a post with RESTful/RPC-XML API request.
• api.edit_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either allow or deny access to update a post with RESTful/RPC-XML API request by an user who is not a post’s author.
• api.delete – boolean true/false or integer 1/0. Either allow or deny access to trash a post with RESTful/RPC-XML API request
• api.delete_others – boolean true/false or integer 1/0. Note! Available with Plus Package premium extension. Either allow or deny access to trash a post with RESTful/RPC-XML API request by an user who is not a post’s author.

Example

// Check if current user has ability to comment on a post
$object = AAM::api()->getUser()->getObject('post', the_ID());

if ($object->has('frontend.comment')) {
    // user is not allowed to comment on a post because frontend.comment is set to 1
}

Not yet documented. Sorry...

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.

Please do not hesitate to contact us if you think AAM needs additional hooks or you simply can’t figure out how to hook your custom functionality.

This filter executes only if JWT Authenticate feature is enabled and can be used to mutate the default set of claims for an issued JWT token.

The callback function should access one argument that is an array of claims. By default AAM issues JWT token with 3 claims: issued at, token expiration time (default is 24 hours) and authenticated user ID.

If you need to change only expiration time for an issued JWT token, you can use ConfigPress option authentication.jwt.expires.

For more information about JWT authentication check How to authenticate WordPress user with JWT token article.

This filter executes only if JWT Authenticate feature is enabled and can be used to change the HTTP response for authentication request. The filter can be used to modify both failed and success responses.

The callback function should access one argument that is an instance of WP_REST_Response class.

For more information about JWT authentication check How to authenticate WordPress user with JWT token article.

By default, most Apache servers drop Authorization HTTP headers so technically there is no way to pass it down to the PHP executable. To avoid this constrain, AAM uses Authentication HTTP header instead however you can override this behavior with aam-jwt-authentication-header-filter filter.

Your custom callback function may accept an optional one argument that contains current JWT token from the Authentication HTTP header if it was included in HTTP request. In response, the callback function has to return valid JWT token, otherwise AAM will fail to authenticate user.

For more information about JWT authentication check How to authenticate WordPress user with JWT token article.

This filter can be used to either mutate existing AAM object or return a custom object. For example premium Plus Package extension uses this filter to return 2 custom objects for term and post type that contain access settings for any term and any post type respectively.

The custom callback function should accept four arguments where:

• – First argument is either instance of AAM_Core_Object class or null;
• – Second argument is a string that contains object slug (e.g. post, metabox, term)
• – Third argument is an object ID (e.g. post ID, term ID)
• – Fourth argument is an instance of AAM_Core_Subject_User or AAM_Core_Subject_Visitor class

When AAM instantiates post object, it also initializes all access settings that belong to a post for current user or visitor. For example when you invoke $user->getObject(‘post’, 123), AAM will instantiate a new instance of AAM_Core_Object_Post class and also trigger inheritance mechanism to identify correct access settings for a post.

The first step that AAM does is checks if there are any access settings defined for a particular post and if not, it applies aam-post-access-filter filter so any external functionality can hook into the access settings inheritance mechanism. The premium Plus Package extension uses this hook to inherit access settings from post’s parent terms or default settings if any are specified.

The callback function should accept two argument where the first argument is an array of access settings and the second argument is instance of an AAM_Core_Object_Post class.

This action is triggered before AAM check if current user or visitor has access to a post. This is a good hook to mutate post’s access settings before authorization process.

The custom callback function should accept one argument which is an instance of AAM_Core_Object_Post class.

This action is triggered after AAM successfully authorize current user to read a post.

Keep in mind, that this action will be not triggered if current user is not authorized to read a post because user will be redirected based on Access Denied Redirect rule.

Hook that will be triggered when AAM plugin about to be uninstalled. This action can be used to perform any additional clean-up procedures.

ConfigPress is the AAM configuration engine that is based on INI format. So basically it is a key/value pairs of various configurations that define the way AAM works. For example by default only users that have administrator capability can access AAM UI however with page.capability option you can specify any other capability and user with that specific capability assigned will be able to get access to the AAM UI.

To retrieve any AAM configurations, you should use AAM::api()->getConfig($option) method.

All the configuration can be defined on the AAM->Settings->ConfigPress tab.

Configure what settings AAM should exports. With this option you can define what type of information can be exported from a website and later imported to another.

Default Value

array('system' => 'roles,utilities,configpress')

For more information about the export/import feature, please refer to the How to export and import AAM settings

Configure WordPress capability that manages access to the AAM page.

Default Value

'administrator'

For more information about managing access to the AAM page, please refer to the How to manage access to AAM page for other users

Configure time span in seconds for issued JWT token.

Default Value

86400

For more information about JWT token, please refer to the How to authenticate WordPress user with JWT token

Configure login delay in seconds that is applied to every request to authenticate user. This is very useful feature to significantly slow down brute force attacks.

Default Value

1

For more information about secure login, please refer to the How does AAM Secure Login works

Configure how long AAM will put user’s login attempts on hold if number of allowed login attempts exceeded defined threshold.

Default Value

'20 minutes'

For more information about JWT token, please refer to the How to authenticate WordPress user with JWT token

Configure how many login attempts are allowed before user will be temporary locked out.

Default Value

20

For more information about JWT token, please refer to the How to authenticate WordPress user with JWT token

Configure internal AAM caching status.

It is strongly recommended to keep AAM caching enabled at all times. Otherwise your website performance may be slightly reduced. AAM has several internal “smart” ways to clean-up cache if specific access settings were changed.

Default Value

'enabled'

For more information about internal AAM caching mechanism, please refer to the How does AAM cache works

Configure how AAM should store cached access settings for your content. By default, to increase performance, all access settings to posts, pages, custom post types and terms are stored per each user. This might increase database space usage however significantly increases website performance. If space is a concern, you can redefine the way cache is stored.

Default Value

array('role', 'visitor', 'user')

For more information about internal AAM caching mechanism, please refer to the How does AAM cache works

Configure user id that inherits all created content by expired user that is about to be automatically deleted.

Default Value

null

For more information about temporary user accounts, please refer to the How to create temporary WordPress user account

Configure physical path to the directory where AAM extensions are located.

Default Value

WP_CONTENT_DIR . '/aam/extension'

Do not store AAM extensions inside the Advanced Access Manager plugin folder because they all will be automatically deleted by WordPress core each time you update basic AAM version.