How it Works
After activating the plugin, a new custom role will be added for each membership level on your site. The custom roles will be set to have a
display_name as the membership level’s name and the
pmpro_role_x, where x is the membership level’s ID.
The plugin will automatically create a new role for every existing or newly added membership level. The custom roles created by this plugin have the same basic capabilities as the “subscriber” role. You can adjust the custom role capabilities using the method outlined below.
- New members will have their role set after completing checkout.
- All existing members will keep their previous role. You will need to perform a custom database query to bulk update the roles for existing members, if desired.
- When user’s membership is cancelled or removed, the custom roles assigned for their previous level will be removed and the site default role will be assigned. You can adjust your site default role under Settings > General in the WordPress admin.
- PMPro Plus members can install the add on via the Memberships > Add Ons admin page.
- Or, download the plugin file and upload the ‘pmpro-roles’ directory to the ‘/wp-content/plugins/’ directory of your site.
- Activate the plugin through the ‘Plugins’ menu in WordPress.
- Navigate to Memberships > Settings > Memberships Levels > Edit Level in the WordPress admin.
- Locate the “Role Settings” section.
- Check the boxes for one or more custom roles to be assigned to the membership level.
- Save settings.
- New members of this level will have the custom role as defined in this setting. Existing members will not have their role adjusted.
Custom Role Capabilities
Custom role capabilities are equivalent to WordPress
subscriber role capabilities. You can adjust the role’s capabilities using the
pmpro_roles_default_caps filter in a custom function. For more information on WordPress Roles and Capabilities, see this article from WordPress.org.
You can also use a plugin like User Role Editor to add or remove custom capabilities via a settings page in the WordPress dashboard. Below is a screenshot of editing a custom role created with this Add On within the User Role Editor settings page.
Removing the Add On
If you no longer want to use this plugin, click the “Delete and Deactivate” link in the plugin’s action links on the Plugins page in the WordPress dashboard. This will update all users with a custom membership role and set their “role” back to the WordPress “subscriber” default.
Action and Filter Hooks
The following actions and filters are available in this Add On:
do_action( 'pmpro_roles_delete_membership_level', $delete_id );
do_action( 'pmpro_roles_after_role_change', $user, $old_user_levels, $old_roles, $new_roles );
apply_filters( 'pmpro_roles_downgraded_role', get_option( 'default_role' ) );
apply_filters( 'pmpro_roles_exclude_other_pmpro_roles', true, $level_id );
apply_filters( 'pmpro_roles_hide_admin_role', true, $edit_level );
apply_filters( 'pmpro_roles_default_caps', $capabilities );
Based on the original PMPro Roles plugin by Josh Levinson in 2013.