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. The list of capabilities was updated as well. 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 25, 2022 · e7ffcad · e7ffcad
1 parent 9544c7e
commit e7ffcad
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>