The $capabilities argument in the `add_role()` function is incompatible with `user_can`

[eclev91]

Reproduce:

Add a role to WP using add_role(), and pass it custom capabilities using the third argument. Like:

<?php
$userCaps = [
        'read',
        'my_cap',
];
add_role('my_new_role', 'My New Role', $userCaps);

Create a user of said role. Then:

<?php
$user = new WP_User($id_of_created_user);
return user_can($user, 'my_cap'); // returns false, expected return true

If, alternatively, I create my role this way:

<?php
$userCaps = [
        'read',
        'my_cap',
];
$role = add_role('my_new_role', 'My New Role');
foreach($userCaps as $cap) {
        $role->add_cap($cap);
}

And repeat testing, it returns true as expected.

This has to do with how the caps are saved. The first way, when capabilities are retrieved in WP_User::has_cap(), they look like this:

<?php
array(4) {
  [0]=>
  "read",
  [1]=>
  "my_cap",
  ["my_new_role"]=>
  bool(true)
  ["exist"]=>
  bool(true)
}

And when done via add_cap, they look like this:

<?php
array(4) {
  ["read"]=>
  bool(true)
  ["my_cap"]=>
  bool(true)
  ["my_new_role"]=>
  bool(true)
  ["exist"]=>
  bool(true)
}

The subsequent empty array check is true for the first, and false for the second.

[eclev91]

The way around this is to format your capabilities when using add_role like so:

<?php
$userCaps = [
  'read' => true,
  'my_cap' => true,
];

I really feel like it should support a generic array with true being assumed.

[soulseekah]

The add_cap method has the following signature: add_cap( $cap, $grant = true )

Notice the 2nd argument. To add a capability you need two things: a capability name, and a grant status (true, false).

When adding capabilities using add_role, the third argument needs a way to pass both the capability name and the grant status. How does it do it? A key-value array.

As stated in the docblock:

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

and the Codex examples show this, too: ​https://codex.wordpress.org/Function_Reference/add_role#Example

You have to pass both these things. When you pass $userCaps = [ 'read', 'my_cap', ]; you are effectively passing in the following array: [ 0 => 'read', 1 => 'my_cap' ], which in turn tries to perform two calls: add_cap( 0, 'read' ) and add_cap( 1, 'my_cap' ), which is, indeed, incompatible with what you're trying to achieve.

This is not a bug, in my opinion.

[johnbillion]

Thanks for the report, but yes this isn't a bug and the documentation for both functions is correct.

[eclev91]

I actually agree, but think it might be worth reviewing as an enhancement. If $capabilities is passed a numerically-keyed array (or "not associative", or whatever), that it be assumed each cap should be assigned as "true".

Thoughts?

Semi-related, what's the use case for explicitly saying someone doesn't have a capability ("my_cap" => false)?

[soulseekah]

Interesting though. add_role doesn't come with any predefined capabilities that you would want to "disable". So theoretically this sugary syntax could be supported. Any thoughts?

[eclev91]

By "this sugary syntax", you mean passing an array of caps without associated booleans? Yeah, I think from a UX perspective it makes sense. Even though the nuts and bolts of how it's accomplished are different, when I add_cap, there's a mechanism that assumes I mean true (the default second arg). A consistent UX would allow for the same assumption to be made when assigning caps at role creation.