Documentation

DeprecatedParametersSniff extends AbstractFunctionParameterSniff
in package

WPCS

WordPressCodingStandards

uses MinimumWPVersionTrait

FinalYes

Check for usage of deprecated parameters in WP functions and suggest alternative based on the parameter passed.

This sniff will throw an error when usage of deprecated parameters is detected if the parameter was deprecated before the minimum supported WP version; a warning otherwise. By default, it is set to presume that a project will support the current WP version and up to three releases before.

Properties

$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|int, mixed>: Array of function, argument, and default value for deprecated argument.
$tokens : array<string|int, mixed>: The list of tokens in the current file being sniffed.
$default_minimum_wp_version : string: Default minimum supported WordPress version.

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.

$exclude

Exclude groups.


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

Example: 'switch_to_blog,user_meta'

$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.

$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.

$excluded_groups

Cache for the excluded groups information.


        protected
            array<string|int, mixed>
    $excluded_groups
     = array()

$group_name

The group name for this group of functions.


        protected
            string
    $group_name
     = 'wp_deprecated_parameters'

$groups

Cache for the group information.


        protected
            array<string|int, mixed>
    $groups
     = array()

$phpcsFile

The current file being sniffed.


        protected
            File
    $phpcsFile

$regex_pattern

Regex pattern with placeholder for the function names.


        protected
            string
    $regex_pattern
     = '`^(?:%s)$`i'

$target_functions

Array of function, argument, and default value for deprecated argument.


        protected
            array<string|int, mixed>
    $target_functions
     = array('_future_post_hook' => array(1 => array('name' => 'deprecated', 'value' => null, 'version' => '2.3.0')), '_load_remote_block_patterns' => array(1 => array('name' => 'deprecated', 'value' => null, 'version' => '5.9.0')), '_wp_post_revision_fields' => array(2 => array('name' => 'deprecated', 'value' => false, 'version' => '4.5.0')), 'add_option' => array(3 => array('name' => 'deprecated', 'value' => '', 'version' => '2.3.0')), 'comments_link' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '0.72'), 2 => array('name' => 'deprecated_2', 'value' => '', 'version' => '1.3.0')), 'convert_chars' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '0.71')), 'delete_plugins' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '4.0.0')), 'discover_pingback_server_uri' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '2.7.0')), 'get_blog_list' => array(3 => array('name' => 'deprecated', 'value' => '', 'version' => '3.0.0')), 'get_category_parents' => array(5 => array('name' => 'deprecated', 'value' => array(), 'version' => '4.8.0')), 'get_delete_post_link' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '3.0.0')), 'get_last_updated' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '3.0.0')), 'get_site_option' => array(3 => array('name' => 'deprecated', 'value' => true, 'version' => '4.4.0')), 'get_terms' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '4.5.0')), 'get_the_author' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '2.1.0')), 'get_user_option' => array(3 => array('name' => 'deprecated', 'value' => '', 'version' => '3.0.0')), 'get_wp_title_rss' => array(1 => array('name' => 'deprecated', 'value' => '&#8211;', 'version' => '4.4.0')), 'global_terms' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '6.1.0')), 'iframe_header' => array(2 => array('name' => 'deprecated', 'value' => false, 'version' => '4.2.0')), 'install_search_form' => array(1 => array('name' => 'deprecated', 'value' => true, 'version' => '4.6.0')), 'is_email' => array(2 => array('name' => 'deprecated', 'value' => false, 'version' => '3.0.0')), 'load_plugin_textdomain' => array(2 => array('name' => 'deprecated', 'value' => false, 'version' => '2.7.0')), 'newblog_notify_siteadmin' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '3.0.0')), 'permalink_single_rss' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '2.3.0')), 'redirect_this_site' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '3.0.0')), 'register_meta' => array(4 => array('name' => 'deprecated', 'value' => null, 'version' => '4.6.0')), 'safecss_filter_attr' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '2.8.1')), 'switch_to_blog' => array(2 => array('name' => 'deprecated', 'value' => null, 'version' => '3.5.0')), 'term_description' => array(2 => array('name' => 'deprecated', 'value' => null, 'version' => '4.9.2')), 'the_attachment_link' => array(3 => array('name' => 'deprecated', 'value' => false, 'version' => '2.5.0')), 'the_author' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '2.1.0'), 2 => array('name' => 'deprecated_echo', 'value' => true, 'version' => '1.5.0')), 'the_author_posts_link' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '2.1.0')), 'trackback_rdf' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '2.5.0')), 'trackback_url' => array(1 => array('name' => 'deprecated_echo', 'value' => true, 'version' => '2.5.0')), 'unregister_setting' => array(3 => array('name' => 'deprecated', 'value' => '', 'version' => '4.7.0')), 'update_blog_option' => array(4 => array('name' => 'deprecated', 'value' => null, 'version' => '3.1.0')), 'update_blog_status' => array(4 => array('name' => 'deprecated', 'value' => null, 'version' => '3.1.0')), 'update_posts_count' => array(1 => array('name' => 'deprecated', 'value' => '', 'version' => '3.0.0')), 'update_user_status' => array(4 => array('name' => 'deprecated', 'value' => null, 'version' => '3.0.2')), 'wp_count_terms' => array(2 => array('name' => 'deprecated', 'value' => '', 'version' => '5.6.0')), 'wp_create_thumbnail' => array(3 => array('name' => 'deprecated', 'value' => '', 'version' => '3.5.0')), 'wp_get_http_headers' => array(2 => array('name' => 'deprecated', 'value' => false, 'version' => '2.7.0')), 'wp_get_sidebars_widgets' => array(1 => array('name' => 'deprecated', 'value' => true, 'version' => '2.8.1')), 'wp_install' => array(5 => array('name' => 'deprecated', 'value' => '', 'version' => '2.6.0')), 'wp_login' => array(3 => array('name' => 'deprecated', 'value' => '', 'version' => '2.5.0')), 'wp_new_user_notification' => array(2 => array('name' => 'deprecated', 'value' => null, 'version' => '4.3.1')), 'wp_notify_postauthor' => array(2 => array('name' => 'deprecated', 'value' => null, 'version' => '3.8.0')), 'wp_title_rss' => array(1 => array('name' => 'deprecated', 'value' => '&#8211;', 'version' => '4.4.0')), 'wp_upload_bits' => array(2 => array('name' => 'deprecated', 'value' => null, 'version' => '2.0.0')), 'xfn_check' => array(3 => array('name' => 'deprecated', 'value' => '', 'version' => '2.5.0')))

The functions are ordered alphabetically. Last updated for WordPress 6.3.

Multidimensional array with parameter details. $target_functions = array( (string) Function name. => array( (int) Target parameter position, 1-based. => array( 'name' => (string|array) Parameter name or list of names if the parameter was renamed since the release of PHP 8.0. 'value' => (mixed) Expected default value for the deprecated parameter. Currently the default values: true, false, null, empty arrays and both empty and non-empty strings can be handled correctly by the process_parameters() method. When an additional default value is added, the relevant code in the process_parameters() method will need to be adjusted. 'version' => (int) The WordPress version when deprecated. ) ) );

$tokens

The list of tokens in the current file being sniffed.


        protected
            array<string|int, mixed>
    $tokens

$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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Return values

string

DeprecatedParametersSniff extends AbstractFunctionParameterSniff in package WPCS WordPressCodingStandards uses MinimumWPVersionTrait

Tags

Table of Contents

Properties

Methods

Properties

$exclude

Tags

$minimum_wp_version

Tags

$unittest_groups

Tags

$excluded_groups

Tags

$group_name

Tags

$groups

Tags

$phpcsFile

Tags

$regex_pattern

Tags

$target_functions

Tags

$tokens

Tags

$default_minimum_wp_version

Tags

Methods

check_for_matches()

Parameters

Tags

Return values

getGroups()

Return values

is_targetted_token()

Parameters

Tags

Return values

process()

Parameters

Tags

Return values

process_matched_token()

Parameters

Return values

process_no_parameters()

Parameters

Return values

process_parameters()

Parameters

Tags

process_token()

Parameters

Return values

register()

Return values

prepare_name_for_regex()

Parameters

Tags

Return values

set_minimum_wp_version()

Tags

setup_groups()

Parameters

Tags

Return values

wp_version_compare()

Parameters

Tags

Return values

normalize_version_number()

Parameters

Tags

Return values

DeprecatedParametersSniff extends AbstractFunctionParameterSniff
in package

WPCS

WordPressCodingStandards

uses MinimumWPVersionTrait