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.
Note! While we are all about the latest and greatest when it comes to PHP language, we also are extremely serious about backward compatibility. That is why we consciously made the decision to keep AAM compatible with at least PHP 5.6. However, AAM is 100% object-oriented so it is strongly encouraged to be proficient in this paradigm.
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.
FYI! You can download our boilerplate plugin from the Github repository that can be used as a good starting point for a new AAM add-on or to play with code samples from this reference.
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).
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.
FYI! You can learn more about multi-role support from the WordPress access control for users with multiple roles article.
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.
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 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.
Note! the AAM::api()->getConfig can return only options that belong to section, so always make sure that this section is defined.
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.
FYI! Always keep in mind that not a single object (resource) in a WordPress website is stand-alone. It either relates to other object(s) or access to it vary from user to user.
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).
You can learn more about inheritance mechanism from the AAM access settings inheritance mechanism article.
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();
});
}AAM offers a single API endpoint that gives you all necessary methods to work with AAM objects, subjects and configurations.
Always use AAM::api() static method to obtain an instance of AAM API. Do not use other classes directly as they may 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 as the names may 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.
object AAM::api()Instance of AAM API object.
Get AAM configuration that is either set through AAM UI or on the Settings->ConfigPress tab.
mixed AAM::api()->getConfig(string $option, mixed $default = null)Configuration value or default value if nothing was found. Typically it returns string or array.
if (AAM::api()->getConfig('core.settings.frontendAccessControl')) {
// Access to the frontend is enabled. Do something here.
}Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Get the user by the specified ID or current user if none is provided.
AAM_Core_Subject AAM::api()->getUser(int $id = null)If $id is not provided, AAM returns either AAM_Core_Subject_Visitor instance if user is not authenticated otherwise AAM_Core_Subject_User.
// 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';
}Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
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.
AAM_Core_Object AAM_Core_Subject->getObject(string $type, mixed $id = null, bool $skipInheritance = false)Instance of AAM object that derives from AAM_Core_Object abstract class.
// Get instance of Post with ID 5 that has access settings for user with ID 2
$post = AAM::api()->getUser(2)->getObject('post', 5);
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
The AAM_Core_Object_Post object is the abtraction layer to work with an individual post record. Under post record we mean any post, page, media attachment or custom post type. Basically anything that is stored in the wp_posts database table.
In the example below, we retrieve a post with ID 345. The retrieved object will contain already initialized access settings for the current user.
$post = AAM::getUser()->getObject(AAM_Core_Object_Post::OBJECT_TYPE, 345);From here the $post contains the instance of AAM_Core_Object_Post that is the additional layer that wraps WP_Post object. Which means, you can access all its public properties properties (e.g. $post->post_title, $post->post_author, etc.).
This object also can be used to programmatically check all saved access settings and even set new. In the example below, we restrict access to read the post.
$post = AAM::getUser()->getObject(AAM_Core_Object_Post::OBJECT_TYPE, 345);
if ($post->updateOptionItem('restricted', true)->save()) {
// Yes! Settings are saved
}
The AAM_Core_Object_Post::updateOptionItem method sets the permission while AAM_Core_Object_Post::save persists it in the database. This type of separation was done for performance reasons.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
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.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
AAM comes with the “JWT Tokens” service that programmatically issues and maintains JWT access tokens for users. During the process of issuing a token, AAM defines the list of claims for it. You have the ability to change this list with aam_jwt_claims_filter filter.
In the example below, we are going to add the user’s email and name to the list of claims and the code is prepared as a stand-alone plugin so it should work out-of-box.
<?php
/**
* Plugin Name: AAM Cauldron
* Description: Just a playground for any AAM custom code
* Version: 0.0.1
* Author: Vasyl Martyniuk
* Author URI: https://vasyltech.com
*
* -------
* LICENSE: This file is subject to the terms and conditions defined in
* file 'LICENSE', which is part of AAM Protected Media Files source package.
**/
namespace AAM\AddOn\Cauldron;
/**
* Main add-on's bootstrap class
*
* @package AAM\AddOn\Cauldron
* @author Vasyl Martyniuk
* @version 0.0.1
*/
class Bootstrap
{
/**
* Single instance of itself
*
* @var AAM\AddOn\Cauldron\Bootstrap
*
* @access private
* @version 0.0.1
*/
private static $_instance = null;
/**
* Initialize the object
*
* @return void
*
* @access protected
* @version 0.0.1
*/
protected function __construct()
{
add_filter('aam_jwt_claims_filter', function($claims) {
$user = get_user_by('ID', $claims['userId']);
return array_merge($claims, array(
'sub' => $user->user_email,
'name' => $user->display_name
));
});
}
/**
* Activation hook
*
* @return void
*
* @access public
* @version 0.0.1
*/
public static function activate()
{
global $wp_version;
if (version_compare(PHP_VERSION, '5.6.40') === -1) {
exit(__('PHP 5.6.40 or higher is required.'));
} elseif (version_compare($wp_version, '4.7.0') === -1) {
exit(__('WP 4.7.0 or higher is required.'));
} elseif (!defined('AAM_VERSION') || (version_compare(AAM_VERSION, '6.0.0') === -1)) {
exit(__('Free Advanced Access Manager plugin 6.0.0 or higher is required.'));
}
}
/**
* Initialize and get single instance of itself
*
* @return AAM\AddOn\Cauldron\Bootstrap
*
* @access public
* @version 0.0.1
*/
public static function init()
{
if (is_null(self::$_instance)) {
self::$_instance = new self;
}
return self::$_instance;
}
}
if (defined('ABSPATH')) {
// Activation hooks
register_activation_hook(__FILE__, __NAMESPACE__ . '\Bootstrap::activate');
// Initialize AAM hooks
add_action('init', function() {
\AAM\AddOn\Cauldron\Bootstrap::init();
});
} The final set of claims will be something like this:
{
"iat": 1580820135,
"iss": "https://demo.aamplugin.com",
"exp": 1581511333,
"jti": "15572261-f177-447e-ad93-08320d7dbd2b",
"userId": 4,
"revocable": true,
"refreshable": false,
"sub": "subscriber@aamplugin.com",
"name": "Alison Brown"
}Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Not yet documented. Sorry...
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Documentation is under development. If you have any specific questions, please feel free to submit your question on our For Developers forum page.
Not yet documented. Sorry...
Not yet documented. Sorry...
Not yet documented. Sorry...