Access Levels
RC 1
This is the documentation for the AAM 7.0.0-rc.1 release. We are actively working on the documentation that may change before stable release announcement.
Definition
interface AAM_Framework_AccessLevel_Interface {
public get_resource(string $resource_type, bool $reload = null) : AAM_Framework_Resource_Interface
public get_preference(string $preference_type, $reload = null) : AAM_Framework_Preference_Interface
public get_parent() : AAM_Framework_AccessLevel_Interface|null
public urls(array $settings = []) : AAM_Framework_Service_Urls
public api_routes(array $settings = []) : AAM_Framework_Service_ApiRoutes
public jwts(array $settings = []) : AAM_Framework_Service_Jwts
public login_redirect(array $settings = []) : AAM_Framework_Service_LoginRedirect
public logout_redirect(array $settings = []) : AAM_Framework_Service_LogoutRedirect
public backend_menu(array $settings = []) : AAM_Framework_Service_BackendMenu
public admin_toolbar(array $settings = []) : AAM_Framework_Service_AdminToolbar
public metaboxes(array $settings = []) : AAM_Framework_Service_Metaboxes
public widgets(array $settings = []) : AAM_Framework_Service_Widgets
public not_found_redirect(array $settings = []) : AAM_Framework_Service_NotFoundRedirect
public access_denied_redirect(array $settings = []) : AAM_Framework_Service_AccessDeniedRedirect
public roles(array $settings = []) : AAM_Framework_Service_Roles
public users(array $settings = []) : AAM_Framework_Service_Users
public posts(array $settings = []) : AAM_Framework_Service_Posts
public terms(array $settings = []) : AAM_Framework_Service_Terms
public taxonomies(array $settings = []) : AAM_Framework_Service_Taxonomies
public post_types(array $settings = []) : AAM_Framework_Service_PostTypes
public capabilities(array $settings = []) : AAM_Framework_Service_Capabilities
public settings(array $settings = []) : AAM_Framework_Service_Settings
public policies(array $settings = []) : AAM_Framework_Service_Policies
public hooks(array $settings = []) : AAM_Framework_Service_Hooks
// Alias methods
public caps(array $settings = []) : AAM_Framework_Service_Capabilities
}
AAM recognizes four primary access levels: default, role, user, and visitor. These levels create a hierarchy that ensures proper access control for all user types.
Default Level: This is the highest level in the access control hierarchy. The default level defines the access settings for all users, roles, and visitors, including administrators. Any access settings applied at this level are inherited by all other levels below it, ensuring a base level of permissions.
Role Level: This level encompasses specific roles, such as Subscriber or Editor roles. Access settings defined at the role level inherit permissions from the default level. By managing roles individually, you can customize permissions for different types of users while maintaining a consistent structure.
User Level: At this level, individual users inherit permissions from their assigned roles. You can assign access settings directly to a specific user, further refining access control beyond what is available at the role level.
Visitor Level: Visitors are unauthenticated users who automatically inherit access settings from the default level. This ensures that even without specific user roles, visitors still adhere to a base access structure.
The framework's primary responsibility is to take into consideration relationships between these access levels and properly prepare access controls and preferences. When necessary, it also resolves any settings ambiguities.
To learn more about access settings inheritance mechanism, refer to the Understanding the access controls inheritance mechanism article.
Working with Access Levels
Using PHP, you can interact with these access levels through the AAM::api() entry point. The API provides a straightforward way to obtain instances of different access levels and customize their settings.
This is the list of all available methods that you can use to obtain various access levels:
// Get current user. If current user is not authenticated, the visitor access level
// is assumed
AAM::api()->user();
// Various ways to get user access level
AAM::api()->user('john@example.xyz'); // By email
AAM::api()->user('john'); // By user_login
AAM::api()->user(12); // By user ID
AAM::api()->user(new WP_User(12)); // By WP_User instance
// Get a role
AAM::api()->role('shop_manager');
// Get the visitor access level
AAM::api()->visitor();
AAM::api()->anonymous();
AAM::api()->guest();
// Get the default access level
AAM::api()->default();
AAM::api()->any();
AAM::api()->anyone();
AAM::api()->everyone();
AAM::api()->all();
Once you have an instance of an access level, you can obtain pre-configured instance of any AAM service and define access controls or preferences to the specific access level. Suppose you want to define URL access for the Subscriber role. By setting access controls at this role level, all users with the Subscriber role will automatically inherit these permissions. This capability makes it easy to manage permissions globally for specific user types.
// Get an instance of URL service through role access level
$service = AAM::api()->role('subscriber')->urls();
// Restrict access to a very specific URL
$service->restrict('/private-area');
Alternatively, you can pass an instance of access level to the service as following:
$service = AAM::api()->urls(
AAM::api()->role('subscriber')
);
When should you use access level?
From the two examples above, you can see that there are two distinct ways to work with AAM services: directly through an access level instance or by passing the instance into the desired service.
Both methods yield the same results with equal efficiency. AAM utilizes internal in-memory caching to prevent redundant access level instance creation. Ultimately, the choice comes down to your personal preference.
Virtual Assistant