Add sniff that will check that capabilities are used correctly.

[dingo-d]

The sniff will check if the functions that are accepting capabilities as the argument actually use capabilities (as described in the support article) and not roles.

The sniff was rewritten from the original one in #1364 to include helper functions from PHPCSUtils. The list of core functions that are using capabilities as a parameter was updated with changes up to WordPress 6.1.0. The list of capabilities was updated as well. The sniff is also compatible with PHP 8 (named arguments).

Original PRs:
#1364
WPTT/WPThemeReview#36

Ref:
https://make.wordpress.org/themes/handbook/review/required/#10-classic-themes
https://developer.wordpress.org/plugins/users/roles-and-capabilities/
https://developer.wordpress.org/plugins/security/checking-user-capabilities/

Closes: #1364

[jrfnl]

One remark: as part of working with @dingo-d on this sniff, I updated the list of known capabilities with anything I could find in Core. I would very much like to invite someone to very critically review that list as there is a risk that I may have added non-officially supported capabilities.

[jrfnl]

Looking great! Just some final touches and then we can get this merged (after ? years... ) 🎉

[dingo-d]

Blocked by: #2114. Once that PR is merged I will rebase and the tests should be passing (tests are passing because the fix was applied here, but it shouldn't be committed in this PR).

[jrfnl]

Thanks @dingo-d for working on this and making all those changes!

Went through it one last time with a fine toothcomb:

• Ran PHPCS with --generator=text to see the CLI docs output.
• Ran PHPCS against the test files to verify the error messages and codes.
• Re-ran PHPCS against the test files with a custom ruleset with the <config name="minimum_supported_wp_version" value="2.9"/> directive set.
• Re-ran PHPCS against the test files using the CLI --runtime-set minimum_supported_wp_version 2.9 arg.
• Ran the tests.

These final remarks are mostly just small peanuts, dotting the i's and crossing the t's. The logic of the sniff is sound and doesn't need any changes anymore, the tests are good and comprehensive, the docs are clear. We're nearly there.

[jrfnl]

I would very much like to invite someone to very critically review that list as there is a risk that I may have added non-officially supported capabilities.

The review of the capabilities list is IMO not a blocker for merging, but would still be very welcome!

@sandeshjangam Would this ☝🏻 be something you'd be interested in helping us with ?

---

Other than the above remark from earlier on, everything looks to have been addressed.

Still saw three inconsistencies, so I've fixed those in a new commit (so you all can see easily what I changed). Feel free to squash on (or before) merge.

Approved (at long last). 🎉

[GaryJones]

✅

[dingo-d]

I agree with the added changes 👍🏼

[jrfnl]

Rebased without changes and squashed the extra commit into the original. Will merge once the build has passed.