Trigger a doing it wrong when checking a role name as a capability

[johnbillion]

Code which checks current_user_can( 'administrator' ) is essentially bypassing all the power of fine grained capability checking in the roles and capabilities API. Let's trigger a call to _doing_it_wrong() when a cap check is performed against any of the built-in roles, in order to persuade developers to use the capabilities API as it's intended.

There may be valid use cases for checking a user's role in this way. If there are, let's look at how to address those.

[fibonaccina]

@johnbillion I attached a proof of concept change in 38653.diff and unit tests. Let me know if you were thinking about a more involved check than this.

[fibonaccina]

Change in cap check and unit tests

[johnbillion]

Thanks for the patch, @fibonaccina! The check needs to continue to work as it has previously (without the return false) so code that is checking role names doesn't stop working but still triggers the doing it wrong notice.

[fibonaccina]

Patch refresh: allow cap check to continue after doing it wrong trigger

[fibonaccina]

@johnbillion Thanks for the feedback! I attached the updated diff. Please let me know in case something doesn't look right.

[johnbillion]

38653.2.diff​ is a slightly more comprehensive approach. However, I'm having second thoughts about adding this notice in. There's currently no clean alternative method for checking the current user's role.

[johnbillion]

Closing as maybelater as there's no great alternative method for checking a user's role (apart from looking at the roles property directly).