Repository files navigation

A user role management plugin for WordPress that puts you in full control of your site's permissions.

This plugin is forked from the last release of the popularjustintadlock/members plugin, before it's codebase was hijacked and turned into a sales pitch for a premium plugin by it's new maintainers.

• Role Manager: Allows you to edit, create, and delete roles as well as capabilities for these roles.
• Multiple User Roles: Give one, two, or even more roles to any user.
• Explicitly Deny Capabilities: Deny specific caps to specific user roles.
• Clone Roles: Build a new role by cloning an existing role.

In order to refocus plugin responsibilities, original features below were removed inv3.0.0. If you still require these features you can use thev2.2.1 release, or another version of this plugin.

• Content Permissions: Gives you control over which users (by role) have access to post content.
• Shortcodes: Shortcodes to control who has access to content.
• Widgets: A login form widget and users widget to show in your theme's sidebars.
• Private Site: You can make your site and its feed completely private if you want.

composer require freshsystems/wp-permission-manager:^3

If you're notusing Composer with WordPress, you can alternatively download the ZIP archive from the releases page and upload/install the plugin manually. The plugin will be made available through the WordPress Plugin Directory after significant refactoring inv4.0.0.

• Update Composer/package details.
• Update UI visible plugin and menu names (Members →WP Permission Manager).
• Remove non-functional admin settings pages (i.e. 'Donate').

• Remove all 'Shortcodes'.
• Remove all 'Widgets'.
• Remove all 'Content Permission' functionality.
• Remove 'Private Site' functionality.
• Remove all 'add-ons' functionality.
• Make the core 'Role Manager' always enabled.
• Bump minumum PHP version requirement to>= 5.6.20.

• Replace remaining "members" terminology (translation text-domain, slug use, etc.).
• Maybe incorporate relevant add-ons (license dependant) into the plugin's core.
• Replace the plugin's namespace, e.g.Members\ →Fresh\PermissionManager\.
• Replace the prefix for all filter/action hook names and functions (deprecate the originals for permanent backwards-compatibility), e.g.members_register_cap_group() →Fresh\PermissionManager\register_cap_group(),members_register_cap_groups →wppm_register_cap_groups.
• Consider implementing some enhancements proposed injustintadlock/members - 3.0.0 Milestone.
• Updatereadme.md documentation and addreadme.txt files.
• Publish to the WordPress Plugin Directory.

The Role Manager feature allows you to edit and add new roles as well as add and remove both default capabilities and custom capabilities from roles. It is an extremely powerful system.

Any changes you make to users and roles using this feature are permanent changes. What I mean by this is that if you deactivate or uninstall this plugin, the changes won't revert to their previous state. This plugin merely provides a user interface for you to make changes directly to your WordPress database. Please use this feature wisely.

This feature can be both a blessing and a curse, so I'm going to ask that you use it wisely. Use extreme caution when assigning new capabilities to roles. You wouldn't want to grant Average Joe theedit_plugins capability, for example.

You can find the settings page for this feature under the "Users" menu. It will be labeled "Roles". When clicking on the menu item, you'll be take to a screen similar to the edit post/page screen, only it'll be for editing a role.

In the "Edit Capabilities" box on that screen, you simply have to tick the checkbox next to the capability you want to grant or deny.

Every capability can have one of three "states" for a role. The role can begranted,denied, or simply not have a capability.

• Granting a capability to a role means that users of that role will have permission to perform the given capability.
• Denying a capability means that the role's users are explicitly denied permission.
• A role that is neither granted nor denied a capability simply doesn't have that capability.

Note: When assigning multiple roles to a single user that have a conflicting capability (e.g., grantedpublish_posts and deniedpublished_posts cap), it's best to enable the denied capabilities override via the Members Settings screen. This will consistently make sure that denied capabilities always overrule granted capabilities. With this setting disabled, WordPress will decide based on thelast role given to the user, which can mean for extremely inconsistent behavior depending on the roles a user has.

Suppose theSuper role isgranted these capabilities:

• edit_posts

Then, suppose theDuper role isgranted these capabilities:

• publish_posts
• edit_products

Now, further supposeUser A has theSuper role because you want them to edit posts. However, you also wantUser A to be able to edit products so you assign them theDuper role. Suddenly,User A isgranted the following capabilities:

• edit_posts
• publish_posts
• edit_products

For whatever reason you don't ever want users with theSuper role to be able to publish posts. Now you have a problem. One way to solve this is to create a third role with just the caps that you want and give that single role toUser A. However, that becomes cumbersome on larger sites with many roles.

Instead, you could explicitlydeny the publish posts capability to theSuper role. When you do that,User A is onlygranted the following capabilities:

• edit_posts
• edit_products

And is denied the following capabilities:

• publish_posts

You can assign a user more than one role by going to that edit user screen in the admin and locating the "Roles" section. There will be a checkbox for every role.

You can also multiple roles to a user from the add new user screen.

On the "Users" screen in the admin, you can bulk add or remove single roles from multiple users.

In plugins and your theme template files, you might sometimes need to check if the currently logged in user has permission to do something. We do this by using the WordPress functioncurrent_user_can(). The basic format looks like this:

<?phpif (current_user_can('capability_name' ) )echo'This user can do something';?>

For a more practical situation, let's say you created a new capability calledread_pages. Well, you might want to hide the content within yourpage.php template by adding this:

<?phpif (current_user_can('read_pages' ) ):?><?phpthe_content();?><?phpendif;?>

Only users with a role that has theread_pages capability will be able to see the content.

Before beginning, I want to note that you really shouldn't do this. It's better to check against capabilities. However, for those times when you need to break the rules, you can do so like:

if (members_user_has_role($user_id,$role ) )// ...

Or, you can check against the current user:

if (members_current_user_has_role($role ) )// ...

Some plugins and themes might rely on the old user level system in WordPress. These were deprecated in WordPress version 2.1 and should not be used at all. WordPress still has minimal legacy support for these, but I highly suggest contacting your theme/plugin author if user levels are being used.

By default, the levels aren't shown. They still exist, but are tucked away behind the scenes. While not recommended, if you need to control who has what level (levels are just capabilities), add this to your plugin or your theme'sfunctions.php:

add_filter('members_remove_old_levels','__return_false' );

If you're a plugin developer with custom capabilities, beginning with version 2.0.0 of Members, you can register your capabilities with Members. Essentially, this allows users to see your capabilities in a nicely-formatted, human-readable form (e.g.,Publish Posts instead ofpublish_posts). This also means that it can be translated so that it's easier to understand for users who do not read English.

<?php// e.g. functions.phpadd_action('members_register_caps',function(){members_register_cap('your_cap_name', ['label' =>__('Your Capability Label','example-textdomain' ),'group' =>'example',    ]);});

Thegroup argument is not required, but will allow you to assign the capability to a cap group.

Members groups capabilities so that users can more easily find them when editing roles. If your plugin has multiple capabilities, you should consider creating a custom cap group.

<?php// e.g. functions.phpadd_action('members_register_cap_groups',function(){members_register_cap_group('your_group_name', ['label'    =>__('Your Group Label','example-textdomain' ),'caps'     => [],'icon'     =>'dashicons-admin-generic','priority' =>10,    ]);});

The arguments for the array are:

• label - An internationalized text label for your group.
• caps - An array of initial capabilities to add to your group.
• icon - The name of one of core WP'sdashicons or a custom class (would need to be styled by your plugin in this case).
• priority - The priority of your group compared to other groups.10 is the default.

Note that custom post types are automatically registered as groups with Members. So, if you want to do something custom with that, you simply need to unregister the group before registering your own.

members_unregister_cap_group("type-{$post_type}" );

This project is licensed under theGNU GPL, version 2 or later.

• Original work Copyright © 2009 - 2018,Justin Tadlock.
• Modified work Copyright © 2020,Fresh Systems Ltd.