Do custom user roles have any default capabilities?

Question

When adding a new user role with add_role(), are there any capabilities attributed to the role (or allowed by the role) by default?

It is possible to create a role without defining any capabilities. There will simply be no capabilities set for this role in the database. However, you can explicitly deny capabilities by setting them to false upon creating the role.

$capabilities
(array) (Optional) List of capabilities, e.g. array( 'edit_posts' => true, 'delete_posts' => false );

I have seen examples of this, but I am left wondering why this would ever be necessary unless WordPress assumes that a newly created role has certain capabilities until otherwise excluded.

For example, are all roles assumed to have the read capability unless the capability is explicitly excluded? I can use get_role( $new_role )->capabilities; to get a list of capabilities which are explicitly set, but this does not answer my question about how WordPress handles new roles. If no capabilities are explicitly set for a new role then this will return empty.

Must I exclude all capabilities I don't not want a role to have or does WordPress presume all capabilities to be false until they are set as true?

Edit: This question was inspired by an example on the developer site which sets a capability to false when a role is created. I can't see why this would be necessary.

$result = add_role(
    'guest_author',
    __( 'Guest Author', 'testdomain' ),
    array(
        'read'         => true,  // true allows this capability
        'edit_posts'   => true,
        'delete_posts' => false, // Use false to explicitly deny
    )
);

Answer 1

I've found that the WordPress has_cap() function, which is relied on by functions like user_can() and current_user_can, explicitly returns false for empty capabilities.

Example: If a capability is passed as an argument using current_user_can(), this function will pass the capability to has_cap() and return the results:

    return call_user_func_array( array( $current_user, 'has_cap' ), $args

has_cap() will return false if the requested capability does not exist or the value is false:

foreach ( (array) $caps as $cap ) {
    if ( empty( $capabilities[ $cap ] ) )
        return false;
}

This is because the empty() function returns true in either case.

A variable is considered empty if it does not exist or if its value equals FALSE.

Unless I am mistaken about how these functions work, then it appears safe to say that no default capabilities are attributed to a new role unless explicitly set to true. It is not necessary to explicitly deny a capability when creating a new role with add_role() and I can't see any reason to do so. If a capability is not listed, the user will not have it.

Answer 2

With the default value (empty array), there is no capabilities added to the role (not even read) and they cannot acces the dashboard

then, you can just create the role with this code :

add_role("on_the_door", "User with no access");

you can use this plugin to see the capabilities of the roles :
https://wordpress.org/plugins/user-role-editor/

Answer 3

This is a misleading way to look at how wordpress capabilities work. In essence there is no structure that contains all the capabilities, and it all boils down to the developer implementing filters for the has_cap function. There is a core structure for core related capabilities, but this is truly a subset of what can be done.

There is one default to the capabilities system - Admins has all the capabilities and there is no other assumption about any other user.

So the discussion should be about specific capabilities, and not about some general capabilities concepts.

Now when focusing on core capabilities, the tradition is that whatever value in the capabilities storage evaluates to false means that the user do not have the capability, so empty storage should mean that a user has no core capability (no other as well, but those capabilities might not rely on the core capabilities structure).

But it is important to remember that capability is just an API, and code do not have to use the API, therefor when you ask specifically "will user with empty capabilities will have a read capability", it is very much depends on how the developer of the feature regard such capability. For example I can see how access to the dashboard might be unconditional, and being able to access your own profile being "on" by default. More extreme - almost no theme I know of implements a capability check before granting access to the content on the front end, therefor it is just meaningless to fiddle with a "read" style capability.