DeprecatedClassesSniff
extends AbstractClassRestrictionsSniff
in package
uses
MinimumWPVersionTrait
Restricts the use of deprecated WordPress classes and suggests alternatives.
This sniff will throw an error when usage of a deprecated class is detected if the class 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.
Tags
Table of Contents
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.
- $classname : string
- Temporary storage for retrieved class name.
- $excluded_groups : array<string|int, mixed>
- Cache for the excluded groups information.
- $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 class names.
- $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.
- $deprecated_classes : array<string|int, mixed>
- List of deprecated classes with alternative when available.
Methods
- check_for_matches() : int|void
- Verify if the current token is one of the targetted classes.
- getGroups() : array<string|int, mixed>
- Groups of classes to restrict.
- is_targetted_token() : bool
- Determine if we have a valid classname for the target token.
- process() : int|void
- Set sniff properties and hand off to child class for processing of the token.
- process_matched_token() : void
- Process a matched token.
- 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.
- get_namespaced_classname() : string
- See if the classname was found in a namespaced file and if so, add the namespace to the classname.
- prepare_name_for_regex() : string
- Prepare the class 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
$exclude
Exclude groups.
public
array<string|int, mixed>
$exclude
= array()
Example: 'switch_to_blog,user_meta'
Tags
$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
$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
$classname
Temporary storage for retrieved class name.
protected
string
$classname
$excluded_groups
Cache for the excluded groups information.
protected
array<string|int, mixed>
$excluded_groups
= array()
Tags
$groups
Cache for the group information.
protected
array<string|int, mixed>
$groups
= array()
Tags
$phpcsFile
The current file being sniffed.
protected
File
$phpcsFile
Tags
$regex_pattern
Regex pattern with placeholder for the class names.
protected
string
$regex_pattern
= '`^\\\\(?:%s)$`i'
$tokens
The list of tokens in the current file being sniffed.
protected
array<string|int, mixed>
$tokens
Tags
$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
$deprecated_classes
List of deprecated classes with alternative when available.
private
array<string|int, mixed>
$deprecated_classes
= array(
// WP 3.1.0.
'WP_User_Search' => array('alt' => 'WP_User_Query', 'version' => '3.1.0'),
// WP 3.7.0.
'WP_HTTP_Fsockopen' => array('alt' => 'WP_HTTP::request()', 'version' => '3.7.0'),
// WP 4.9.0.
'WP_Customize_New_Menu_Section' => array('version' => '4.9.0'),
'WP_Customize_New_Menu_Control' => array('version' => '4.9.0'),
// WP 5.3.0.
'WP_Privacy_Data_Export_Requests_Table' => array('alt' => 'WP_Privacy_Data_Export_Requests_List_Table', 'version' => '5.3.0'),
'WP_Privacy_Data_Removal_Requests_Table' => array('alt' => 'WP_Privacy_Data_Removal_Requests_List_Table', 'version' => '5.3.0'),
'Services_JSON' => array('alt' => 'The PHP native JSON extension', 'version' => '5.3.0'),
'Services_JSON_Error' => array('alt' => 'The PHP native JSON extension', 'version' => '5.3.0'),
// WP 6.4.0.
'WP_Http_Curl' => array('alt' => 'WP_Http', 'version' => '6.4.0'),
'WP_Http_Streams' => array('alt' => 'WP_Http', 'version' => '6.4.0'),
)
To be updated after every major release.
Version numbers should be fully qualified.
Methods
check_for_matches()
Verify if the current token is one of the targetted classes.
public
check_for_matches(int $stackPtr) : int|void
Parameters
- $stackPtr : int
-
The position of the current token in the stack.
Tags
Return values
int|void —Integer stack pointer to skip forward or void to continue normal file processing.
getGroups()
Groups of classes to restrict.
public
getGroups() : array<string|int, mixed>
Return values
array<string|int, mixed>is_targetted_token()
Determine if we have a valid classname for the target token.
public
is_targetted_token(int $stackPtr) : bool
Parameters
- $stackPtr : int
-
The position of the current token in the stack.
Tags
Return values
boolprocess()
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
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) : void
Parameters
- $stackPtr : int
-
The position of the current token in the stack.
- $group_name : string
-
The name of the group which was matched. Will always be 'deprecated_classes'.
- $matched_content : string
-
The token content (class name) which was matched in its original case.
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>get_namespaced_classname()
See if the classname was found in a namespaced file and if so, add the namespace to the classname.
protected
get_namespaced_classname(string $classname, int $search_from) : string
Parameters
- $classname : string
-
The full classname as found.
- $search_from : int
-
The token position to search up from.
Return values
string —Classname, potentially prefixed with the namespace.
prepare_name_for_regex()
Prepare the class name for use in a regular expression.
protected
prepare_name_for_regex(string $classname) : string
The getGroups() method allows for providing class names with a wildcard * to target a group of classes within a namespace. It also allows for providing class names as 'ordinary' names or prefixed with one or more namespaces. This prepare routine takes that into account while still safely escaping the class name for use in a regular expression.
Parameters
- $classname : string
-
Class name, potentially prefixed with namespaces.
Return values
string —Regex escaped class 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
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
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
Return values
boolnormalize_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.