Documentation

CapabilitiesSniff extends AbstractFunctionParameterSniff
in package
uses MinimumWPVersionTrait

FinalYes

Check that capabilities are used correctly.

User capabilities should be used, not roles or deprecated capabilities.

Tags
since
3.0.0
uses
MinimumWPVersionTrait::$minimum_wp_version

Table of Contents

Properties

$custom_capabilities  : array<string|int, mixed>
List of custom capabilities.
$exclude  : array<string|int, mixed>
Exclude groups.
$minimum_wp_version  : string
Minimum supported WordPress version.
$unittest_groups  : array<string|int, mixed>
Groups of function data to check against.
$excluded_groups  : array<string|int, mixed>
Cache for the excluded groups information.
$group_name  : string
The group name for this group of functions.
$groups  : array<string|int, mixed>
Cache for the group information.
$phpcsFile  : File
The current file being sniffed.
$regex_pattern  : string
Regex pattern with placeholder for the function names.
$target_functions  : array<string, array<string|int, mixed>>
List of functions that accept roles and capabilities as an argument.
$tokens  : array<string|int, mixed>
The list of tokens in the current file being sniffed.
$core_capabilities  : array<string, true>
List of known primitive and meta core capabilities.
$core_roles  : array<string, true>
List of core roles which should not to be used directly.
$default_minimum_wp_version  : string
Default minimum supported WordPress version.
$deprecated_capabilities  : array<string, string>
List of deprecated core capabilities.

Methods

check_for_matches()  : int|void
Verify if the current token is one of the targetted functions.
getGroups()  : array<string|int, mixed>
Groups of functions to restrict.
is_targetted_token()  : bool
Verify is the current token is a function call.
process()  : int|void
Set sniff properties and hand off to child class for processing of the token.
process_matched_token()  : int|void
Process a matched token.
process_no_parameters()  : int|void
Process the function if no parameters were found.
process_parameters()  : void
Process the parameters of a matched function.
process_token()  : int|void
Processes this test, when one of its tokens is encountered.
register()  : array<string|int, mixed>
Returns an array of tokens this test wants to listen for.
prepare_name_for_regex()  : string
Prepare the function name for use in a regular expression.
set_minimum_wp_version()  : void
Overrule the minimum supported WordPress version with a command-line/config value.
setup_groups()  : bool
Set up the regular expressions for each group.
wp_version_compare()  : bool
Compares two version numbers.
normalize_version_number()  : string
Normalize a version number.

Properties

$custom_capabilities

List of custom capabilities.

public array<string|int, mixed> $custom_capabilities = array()
Tags
since
3.0.0

$exclude

Exclude groups.

public array<string|int, mixed> $exclude = array()

Example: 'switch_to_blog,user_meta'

Tags
since
0.3.0
since
1.0.0

This property now expects to be passed an array. Previously a comma-delimited string was expected.

$minimum_wp_version

Minimum supported WordPress version.

public string $minimum_wp_version

Currently used by the WordPress.Security.PreparedSQLPlaceholders, WordPress.WP.AlternativeFunctions, WordPress.WP.Capabilities, WordPress.WP.DeprecatedClasses, WordPress.WP.DeprecatedFunctions, WordPress.WP.DeprecatedParameter and the WordPress.WP.DeprecatedParameterValues sniff.

These sniffs will adapt their behaviour based on the minimum supported WP version indicated. By default, it is set to presume that a project will support the current WP version and up to three releases before.

This property allows changing the minimum supported WP version used by these sniffs by setting a property in a custom phpcs.xml ruleset. This property will need to be set for each sniff which uses it.

Example usage:

Alternatively, the value can be passed in one go for all sniffs using it via the command line or by setting a <config> value in a custom phpcs.xml ruleset.

CL: phpcs --runtime-set minimum_wp_version 5.7 Ruleset: <config name="minimum_wp_version" value="6.0"/>

WordPress version.

Tags
since
0.14.0

Previously the individual sniffs each contained this property.

since
3.0.0
  • Moved from the Sniff class to this dedicated Trait.
  • The property has been renamed from $minimum_supported_version to $minimum_wp_version.
  • The CLI option has been renamed from minimum_supported_wp_version to minimum_wp_version.
used-by
PreparedSQLPlaceholdersSniff
used-by
AlternativeFunctionsSniff
used-by
CapabilitiesSniff
used-by
DeprecatedClassesSniff
used-by
DeprecatedFunctionsSniff
used-by
DeprecatedParametersSniff
used-by
DeprecatedParameterValuesSniff

$unittest_groups

Groups of function data to check against.

public static array<string|int, mixed> $unittest_groups = array()

Don't use this in extended classes, override getGroups() instead. This is only used for Unit tests.

Tags
since
0.10.0

$group_name

The group name for this group of functions.

protected string $group_name = 'caps_not_roles'
Tags
since
3.0.0

$phpcsFile

The current file being sniffed.

protected File $phpcsFile
Tags
since
0.4.0

$target_functions

List of functions that accept roles and capabilities as an argument.

protected array<string, array<string|int, mixed>> $target_functions = array('add_comments_page' => array('position' => 3, 'name' => 'capability'), 'add_dashboard_page' => array('position' => 3, 'name' => 'capability'), 'add_links_page' => array('position' => 3, 'name' => 'capability'), 'add_management_page' => array('position' => 3, 'name' => 'capability'), 'add_media_page' => array('position' => 3, 'name' => 'capability'), 'add_menu_page' => array('position' => 3, 'name' => 'capability'), 'add_object_page' => array( // Deprecated since WP 4.5.0. 'position' => 3, 'name' => 'capability', ), 'add_options_page' => array('position' => 3, 'name' => 'capability'), 'add_pages_page' => array('position' => 3, 'name' => 'capability'), 'add_plugins_page' => array('position' => 3, 'name' => 'capability'), 'add_posts_page' => array('position' => 3, 'name' => 'capability'), 'add_submenu_page' => array('position' => 4, 'name' => 'capability'), 'add_theme_page' => array('position' => 3, 'name' => 'capability'), 'add_users_page' => array('position' => 3, 'name' => 'capability'), 'add_utility_page' => array( // Deprecated since WP 4.5.0. 'position' => 3, 'name' => 'capability', ), 'author_can' => array('position' => 2, 'name' => 'capability'), 'current_user_can' => array('position' => 1, 'name' => 'capability'), 'current_user_can_for_blog' => array('position' => 2, 'name' => 'capability'), 'map_meta_cap' => array('position' => 1, 'name' => 'cap'), 'user_can' => array('position' => 2, 'name' => 'capability'))

The functions are defined in wp-admin/includes/plugin.php and /wp-includes/capabilities.php. The list is sorted alphabetically.

The key is the name of a function we're targetting, the value is an array containing the 1-based parameter position of the "capability" parameter within the function, as well as the name of the parameter as declared in the function. If the parameter name has been renamed since the release of PHP 8.0, the parameter can be set as an array.

Tags
since
3.0.0

$tokens

The list of tokens in the current file being sniffed.

protected array<string|int, mixed> $tokens
Tags
since
0.4.0

$core_capabilities

List of known primitive and meta core capabilities.

private array<string, true> $core_capabilities = array( 'activate_plugin' => true, 'activate_plugins' => true, 'add_comment_meta' => true, 'add_post_meta' => true, 'add_term_meta' => true, 'add_user_meta' => true, 'add_users' => true, 'assign_categories' => true, 'assign_post_tags' => true, 'assign_term' => true, 'create_app_password' => true, 'create_sites' => true, 'create_users' => true, 'customize' => true, 'deactivate_plugin' => true, 'deactivate_plugins' => true, 'delete_app_password' => true, 'delete_app_passwords' => true, 'delete_block' => true, // Only seen in tests. 'delete_blocks' => true, // Alias for 'delete_posts', but supported. 'delete_categories' => true, 'delete_comment_meta' => true, 'delete_others_blocks' => true, // Alias for 'delete_others_posts', but supported. 'delete_others_pages' => true, 'delete_others_posts' => true, 'delete_page' => true, // Alias, but supported. 'delete_pages' => true, 'delete_plugins' => true, 'delete_post_tags' => true, 'delete_post' => true, // Alias, but supported. 'delete_post_meta' => true, 'delete_posts' => true, 'delete_private_blocks' => true, // Alias for 'delete_private_posts', but supported. 'delete_private_pages' => true, 'delete_private_posts' => true, 'delete_published_blocks' => true, // Alias for 'delete_published_posts', but supported. 'delete_published_pages' => true, 'delete_published_posts' => true, 'delete_site' => true, 'delete_sites' => true, 'delete_term' => true, 'delete_term_meta' => true, 'delete_themes' => true, 'delete_user' => true, // Alias for 'delete_users', but supported. 'delete_user_meta' => true, 'delete_users' => true, 'edit_app_password' => true, 'edit_categories' => true, 'edit_block' => true, // Only seen in tests. 'edit_blocks' => true, // Alias for 'edit_posts', but supported. 'edit_comment' => true, // Alias, but supported. 'edit_comment_meta' => true, 'edit_css' => true, 'edit_dashboard' => true, 'edit_files' => true, 'edit_others_blocks' => true, // Alias for 'edit_others_posts', but supported. 'edit_others_pages' => true, 'edit_others_posts' => true, 'edit_page' => true, // Alias, but supported. 'edit_pages' => true, 'edit_plugins' => true, 'edit_post_tags' => true, 'edit_post' => true, // Alias, but supported. 'edit_post_meta' => true, 'edit_posts' => true, 'edit_private_blocks' => true, // Alias for 'edit_private_posts', but supported. 'edit_private_pages' => true, 'edit_private_posts' => true, 'edit_published_blocks' => true, // Alias for 'edit_published_posts', but supported. 'edit_published_pages' => true, 'edit_published_posts' => true, 'edit_term' => true, 'edit_term_meta' => true, 'edit_theme_options' => true, 'edit_themes' => true, 'edit_user' => true, // Alias for 'edit_users', but supported. 'edit_user_meta' => true, 'edit_users' => true, 'erase_others_personal_data' => true, 'export' => true, 'export_others_personal_data' => true, 'import' => true, 'install_languages' => true, 'install_plugins' => true, 'install_themes' => true, 'list_app_passwords' => true, 'list_users' => true, 'manage_categories' => true, 'manage_links' => true, 'manage_network' => true, 'manage_network_options' => true, 'manage_network_plugins' => true, 'manage_network_themes' => true, 'manage_network_users' => true, 'manage_options' => true, 'manage_post_tags' => true, 'manage_privacy_options' => true, 'manage_sites' => true, 'moderate_comments' => true, 'publish_blocks' => true, // Alias for 'publish_posts', but supported. 'publish_pages' => true, 'publish_post' => true, // Alias, but supported. 'publish_posts' => true, 'promote_user' => true, 'promote_users' => true, 'read' => true, 'read_block' => true, // Only seen in tests. 'read_post' => true, // Alias, but supported. 'read_page' => true, // Alias, but supported. 'read_app_password' => true, 'read_private_blocks' => true, // Alias for 'read_private_posts', but supported. 'read_private_pages' => true, 'read_private_posts' => true, 'remove_user' => true, // Alias for 'remove_users', but supported. 'remove_users' => true, 'resume_plugin' => true, // Alias for 'resume_plugins', but supported. 'resume_plugins' => true, 'resume_theme' => true, // Alias for 'resume_themes', but supported. 'resume_themes' => true, 'setup_network' => true, 'switch_themes' => true, 'unfiltered_html' => true, 'unfiltered_upload' => true, 'update_core' => true, 'update_https' => true, 'update_languages' => true, 'update_plugins' => true, 'update_php' => true, 'update_themes' => true, 'upgrade_network' => true, 'upload_files' => true, 'upload_plugins' => true, 'upload_themes' => true, 'view_site_health_checks' => true, )

Sources:

List is sorted alphabetically.

All capabilities available in core.

Tags
since
3.0.0

$core_roles

List of core roles which should not to be used directly.

private array<string, true> $core_roles = array('super_admin' => true, 'administrator' => true, 'editor' => true, 'author' => true, 'contributor' => true, 'subscriber' => true)

Key is role available in WP Core, value irrelevant.

Tags
since
3.0.0

$default_minimum_wp_version

Default minimum supported WordPress version.

private string $default_minimum_wp_version = '6.2'

By default, the minimum_wp_version presumes that a project will support the current WP version and up to three releases before.

}

WordPress version.

Tags
since
3.0.0

$deprecated_capabilities

List of deprecated core capabilities.

private array<string, string> $deprecated_capabilities = array('level_10' => '3.0.0', 'level_9' => '3.0.0', 'level_8' => '3.0.0', 'level_7' => '3.0.0', 'level_6' => '3.0.0', 'level_5' => '3.0.0', 'level_4' => '3.0.0', 'level_3' => '3.0.0', 'level_2' => '3.0.0', 'level_1' => '3.0.0', 'level_0' => '3.0.0')

User Levels were deprecated in version 3.0.

All deprecated capabilities in core.

Tags
link
https://github.com/WordPress/wordpress-develop/blob/master/tests/phpunit/tests/user/capabilities.php
since
3.0.0

Methods

check_for_matches()

Verify if the current token is one of the targetted functions.

public check_for_matches(int $stackPtr) : int|void
Parameters
$stackPtr : int

The position of the current token in the stack.

Tags
since
0.11.0

Split out from the process() method.

Return values
int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

getGroups()

Groups of functions to restrict.

public getGroups() : array<string|int, mixed>
Return values
array<string|int, mixed>

is_targetted_token()

Verify is the current token is a function call.

public is_targetted_token(int $stackPtr) : bool
Parameters
$stackPtr : int

The position of the current token in the stack.

Tags
since
0.11.0

Split out from the process() method.

Return values
bool

process()

Set sniff properties and hand off to child class for processing of the token.

public process(File $phpcsFile, int $stackPtr) : int|void
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the current token in the stack passed in $tokens.

Tags
since
0.11.0
Return values
int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

process_matched_token()

Process a matched token.

public process_matched_token(int $stackPtr, string $group_name, string $matched_content) : int|void
Parameters
$stackPtr : int

The position of the current token in the stack.

$group_name : string

The name of the group which was matched.

$matched_content : string

The token content (function name) which was matched in lowercase.

Return values
int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

process_no_parameters()

Process the function if no parameters were found.

public process_no_parameters(int $stackPtr, string $group_name, string $matched_content) : int|void

Defaults to doing nothing. Can be overloaded in child classes to handle functions were parameters are expected, but none found.

Parameters
$stackPtr : int

The position of the current token in the stack.

$group_name : string

The name of the group which was matched.

$matched_content : string

The token content (function name) which was matched in lowercase.

Return values
int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

process_parameters()

Process the parameters of a matched function.

public process_parameters(int $stackPtr, string $group_name, string $matched_content, array<string|int, mixed> $parameters) : void
Parameters
$stackPtr : int

The position of the current token in the stack.

$group_name : string

The name of the group which was matched.

$matched_content : string

The token content (function name) which was matched in lowercase.

$parameters : array<string|int, mixed>

Array with information about the parameters.

Tags
since
3.0.0

process_token()

Processes this test, when one of its tokens is encountered.

public process_token(int $stackPtr) : int|void
Parameters
$stackPtr : int

The position of the current token in the stack.

Return values
int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

register()

Returns an array of tokens this test wants to listen for.

public register() : array<string|int, mixed>
Return values
array<string|int, mixed>

prepare_name_for_regex()

Prepare the function name for use in a regular expression.

protected prepare_name_for_regex(string $function_name) : string

The getGroups() method allows for providing function names with a wildcard * to target a group of functions. This prepare routine takes that into account while still safely escaping the function name for use in a regular expression.

Parameters
$function_name : string

Function name.

Tags
since
0.10.0
Return values
string —

Regex escaped function name.

set_minimum_wp_version()

Overrule the minimum supported WordPress version with a command-line/config value.

protected final set_minimum_wp_version() : void

Handle setting the minimum supported WP version in one go for all sniffs which expect it via the command line or via a <config> variable in a ruleset. The config variable overrules the default $minimum_wp_version and/or a $minimum_wp_version set for individual sniffs through the ruleset.

Tags
since
0.14.0
since
3.0.0
  • Moved from the Sniff class to this dedicated Trait.
  • Renamed from get_wp_version_from_cl() to set_minimum_wp_version().

setup_groups()

Set up the regular expressions for each group.

protected setup_groups(string $key) : bool
Parameters
$key : string

The group array index key where the input for the regular expression can be found.

Tags
since
0.10.0
Return values
bool —

True if the groups were setup. False if not.

wp_version_compare()

Compares two version numbers.

protected final wp_version_compare(string $version1, string $version2, string $operator) : bool
Parameters
$version1 : string

First version number.

$version2 : string

Second version number.

$operator : string

Comparison operator.

Tags
since
3.0.0
Return values
bool

normalize_version_number()

Normalize a version number.

private normalize_version_number(string $version) : string

Ensures that a version number is comparable via the PHP version_compare() function by making sure it complies with the minimum "PHP-standardized" version number requirements.

Presumes the input is a numeric version number string. The behaviour with other input is undefined.

Parameters
$version : string

Version number.

Tags
since
3.0.0
Return values
string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results