Documentation

ValidHookNameSniff extends AbstractFunctionParameterSniff
in package

Use lowercase letters in action and filter names. Separate words via underscores.

This sniff is only testing the hook invoke functions as when using 'add_action'/'add_filter' you can't influence the hook name.

Hook names invoked with do_action_deprecated() and apply_filters_deprecated() are ignored.

Tags
link
https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#naming-conventions
since
0.10.0
since
0.11.0

Extends the WordPressCS native AbstractFunctionParameterSniff class.

since
0.13.0

Class name changed: this class is now namespaced.

Table of Contents

Properties

$additionalWordDelimiters  : string
Additional word separators.
$exclude  : array<string|int, mixed>
Exclude groups.
$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.
$punctuation_regex  : string
Regular expression to test for correct punctuation of a hook name.
$regex_pattern  : string
Regex pattern with placeholder for the function names.
$target_functions  : array<string|int, mixed>
Functions this sniff is looking for. Should be defined in the child class.
$tokens  : array<string|int, mixed>
The list of tokens in the current file being sniffed.

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.
prepare_regex()  : string
Prepare the punctuation regular expression.
setup_groups()  : bool
Set up the regular expressions for each group.
transform()  : string
Transform an arbitrary string to lowercase and replace punctuation and spaces with underscores.
transform_complex_string()  : string
Transform a complex string which may contain variable extrapolation.

Properties

$additionalWordDelimiters

Additional word separators.

public string $additionalWordDelimiters = ''

This public variable allows providing additional word separators which will be allowed in hook names via a property in the phpcs.xml config file.

Example usage:

Provide several extra delimiters as one string:

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

$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 = 'restricted_parameters'

Intended to be overruled in the child class.

$phpcsFile

The current file being sniffed.

protected File $phpcsFile
Tags
since
0.4.0

$punctuation_regex

Regular expression to test for correct punctuation of a hook name.

protected string $punctuation_regex = '`[^\w%s]`'

The placeholder will be replaced by potentially provided additional word delimiters in the prepare_regex() method.

$target_functions

Functions this sniff is looking for. Should be defined in the child class.

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

The only requirement for this array is that the top level array keys are the names of the functions you're looking for. Other than that, the array can have arbitrary content depending on your needs.

$tokens

The list of tokens in the current file being sniffed.

protected array<string|int, mixed> $tokens
Tags
since
0.4.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>
Tags
since
0.11.0
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
0.11.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.

prepare_regex()

Prepare the punctuation regular expression.

protected prepare_regex() : string

Merges the existing regular expression with potentially provided extra word delimiters to allow. This is done 'late' and for each found token as otherwise inline phpcs:set directives would be ignored.

Return values
string

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.

transform()

Transform an arbitrary string to lowercase and replace punctuation and spaces with underscores.

protected transform(string $text_string, string $regex[, string $transform_type = 'full' ]) : string
Parameters
$text_string : string

The target string.

$regex : string

The punctuation regular expression to use.

$transform_type : string = 'full'

Whether to do a partial or complete transform. Valid values are: 'full', 'case', 'punctuation'.

Return values
string

transform_complex_string()

Transform a complex string which may contain variable extrapolation.

protected transform_complex_string(string $text_string, string $regex[, string $transform_type = 'full' ]) : string
Parameters
$text_string : string

The target string.

$regex : string

The punctuation regular expression to use.

$transform_type : string = 'full'

Whether to do a partial or complete transform. Valid values are: 'full', 'case', 'punctuation'.

Return values
string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results