Add sniff that will check that capabilities are used correctly.

The sniff will check if the functions that are accepting capabilities as the argument actually use capabilities and not roles. It was rewritten to include helper functions from PHPCSUtils, cleanup code, and add additional tests. The list of core functions that are using capabilities as a parameter was updated with changes up to WordPress 6.1.0, as well as the list of capabilities. The sniff is also compatible with PHP 8 (named arguments). Co-authored-by: Juliette <[email protected]> Co-authored-by: Ulrich Pogson <[email protected]> Co-authored-by: Kevin Haig <[email protected]> Co-authored-by: Gary Jones <[email protected]>
WordPress · Nov 26, 2022 · cb68657 · cb68657
1 parent c1c4b64
commit cb68657
Show file tree

Hide file tree

Showing 7 changed files with 817 additions and 0 deletions.
diff --git a/WordPress-Extra/ruleset.xml b/WordPress-Extra/ruleset.xml
@@ -84,6 +84,9 @@
 	<rule ref="WordPress.WP.DiscouragedConstants"/>
 	<rule ref="WordPress.WP.DiscouragedFunctions"/>
 
+	<!-- Verify that capabilities are being used correctly. -->
+	<rule ref="WordPress.WP.Capabilities"/>
+
 	<!-- Scripts & style should be enqueued.
 		 https://github.com/WordPress/WordPress-Coding-Standards/issues/35 -->
 	<rule ref="WordPress.WP.EnqueuedResources"/>

diff --git a/WordPress/Docs/WP/CapabilitiesStandard.xml b/WordPress/Docs/WP/CapabilitiesStandard.xml
@@ -0,0 +1,69 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Capabilities"
+    >
+    <standard>
+    <![CDATA[
+Capabilities passed should be valid capabilities (custom capabilities can be added in the ruleset).
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: a WP native or registered custom user capability is used.">
+        <![CDATA[
+if ( author_can( $post, <em>'manage_sites'</em> ) ) { }
+        ]]>
+        </code>
+        <code title="Invalid: unknown/unsupported user capability is used.">
+        <![CDATA[
+map_meta_cap( <em>'manage_site'</em>, $user->ID );
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+Always use user capabilities instead of roles.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: user capability is used.">
+        <![CDATA[
+add_options_page(
+    esc_html__( 'Options', 'textdomain' ),
+    esc_html__( 'Options', 'textdomain' ),
+    <em>'manage_options'</em>,
+    'options_page_slug',
+    'project_options_page_cb'
+);
+        ]]>
+        </code>
+        <code title="Invalid: user role is used instead of a capability.">
+        <![CDATA[
+add_posts_page(
+    __( 'Post visibility', 'textdomain' ),
+    __( 'Post visibility', 'textdomain' ),
+    <em>'author'</em>,
+    'project-posts-visibility',
+    'project_posts_visibility_cb'
+);
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+Don't use deprecated capabilities.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: a WP native or registered custom user capability is used.">
+        <![CDATA[
+if ( author_can( $post, <em>'read'</em> ) ) { }
+        ]]>
+        </code>
+        <code title="Invalid: deprecated user capability is used.">
+        <![CDATA[
+if ( author_can( $post, <em>'level_6'</em> ) ) { }
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>