search

freshsystems / wp-permission-manager

A a user role management plugin for WordPress that puts you in full control of your site's permissions.
GNU General Public License v2.0
8 stars 2 forks source link
capabilities members permissions roles wordpress

readme

👥 Permission Manager

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 popular justintadlock/members plugin, before it's codebase was hijacked and turned into a sales pitch for a premium plugin by it's new maintainers.

Screenshot

Plugin Features

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

Installation

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

If you're not using 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 in v4.0.0.

Roadmap

v2.2.1 ✅

v3.0.0 ✅

v4.0.0

Documentation

Role management

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.

Editing/Adding Roles

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 the edit_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.

Grant, deny, or neither?

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

Note: When assigning multiple roles to a single user that have a conflicting capability (e.g., granted publish_posts and denied published_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 the last role given to the user, which can mean for extremely inconsistent behavior depending on the roles a user has.

How denied capabilities work

Suppose the Super role is granted these capabilities:

Then, suppose the Duper role is granted these capabilities:

Now, further suppose User A has the Super role because you want them to edit posts. However, you also want User A to be able to edit products so you assign them the Duper role. Suddenly, User A is granted the following capabilities:

For whatever reason you don't ever want users with the Super 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 to User A. However, that becomes cumbersome on larger sites with many roles.

Instead, you could explicitly deny the publish posts capability to the Super role. When you do that, User A is only granted the following capabilities:

And is denied the following capabilities:

Multiple user roles

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.

Checking if the current user has a capability

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 function current_user_can(). The basic format looks like this:

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

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

<?php if ( current_user_can( 'read_pages ' ) ): ?>
    <?php the_content(); ?>
<?php endif; ?>

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

Checking if a user has a role

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 ) ) // ...

Need the old user levels system?

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's functions.php:

add_filter( 'members_remove_old_levels', '__return_false' );

Registering capabilities

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 of publish_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.php

add_action( 'members_register_caps', function()
{
    members_register_cap( 'your_cap_name', [
        'label' => __( 'Your Capability Label', 'example-textdomain' ),
        'group' => 'example',
    ]);
});

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

Registering cap groups

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

add_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:

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

Copyright and License

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