Documentation

I18nSniff extends AbstractFunctionParameterSniff
in package

FinalYes

Makes sure WP internationalization functions are used properly.

Tags
link
https://make.wordpress.org/core/handbook/best-practices/internationalization/
link
https://developer.wordpress.org/plugins/internationalization/
since
0.10.0
since
0.11.0
  • Now also checks for translators comments.
  • Now has the ability to handle text domain set via the command-line as a comma-delimited list. phpcs --runtime-set text_domain my-slug,default
since
0.13.0

Class name changed: this class is now namespaced.

since
1.0.0

This class now extends the WordPressCS native AbstractFunctionRestrictionSniff class. The parent exclude property is, however, disabled as it would disable the whole sniff.

since
3.0.0

This class now extends the WordPressCS native AbstractFunctionParameterSniff class. The parent exclude property is still disabled.

Table of Contents

Constants

SPRINTF_PLACEHOLDER_REGEX  = '/(?: (?<!%) # Don\'t match a literal % (%%). ( % # Start of placeholder. (?:[0-9]+\$)? # Optional ordering of the placeholders. [+-]? # Optional sign specifier. (?: (?:0|\'.)? # Optional padding specifier - excluding the space. -? # Optional alignment specifier. [0-9]* # Optional width specifier. (?:\.(?:[ 0]|\'.)?[0-9]+)? # Optional precision specifier with optional padding character. | # Only recognize the space as padding in combination with a width specifier. (?:[ ])? # Optional space padding specifier. -? # Optional alignment specifier. [0-9]+ # Width specifier. (?:\.(?:[ 0]|\'.)?[0-9]+)? # Optional precision specifier with optional padding character. ) [bcdeEfFgGhHosuxX] # Type specifier. ) )/x'
These Regexes were originally copied from https://www.php.net/function.sprintf#93552 and adjusted for better precision and updated specs.
UNORDERED_SPRINTF_PLACEHOLDER_REGEX  = '/(?: (?<!%) # Don\'t match a literal % (%%). % # Start of placeholder. [+-]? # Optional sign specifier. (?: (?:0|\'.)? # Optional padding specifier - excluding the space. -? # Optional alignment specifier. [0-9]* # Optional width specifier. (?:\.(?:[ 0]|\'.)?[0-9]+)? # Optional precision specifier with optional padding character. | # Only recognize the space as padding in combination with a width specifier. (?:[ ])? # Optional space padding specifier. -? # Optional alignment specifier. [0-9]+ # Width specifier. (?:\.(?:[ 0]|\'.)?[0-9]+)? # Optional precision specifier with optional padding character. ) [bcdeEfFgGhHosuxX] # Type specifier. )/x'
"Unordered" means there's no position specifier: '%s', not '%2$s'.

Properties

$exclude  : array<string|int, mixed>
Exclude groups.
$text_domain  : array<string|int, string>
Text domain.
$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.
$i18n_functions  : array<string, string>
The I18N functions in use in WP.
$phpcsFile  : File
The current file being sniffed.
$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.
$parameter_specs  : array<string, array<string|int, mixed>>
Parameter specifications for the functions in each group.
$text_domain_contains_default  : bool
Whether or not the `default` text domain is one of the allowed text domains.
$text_domain_is_default  : bool
Whether or not the `default` text domain is the only allowed text domain.

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()  : void
Process a matched token.
process_no_parameters()  : void
Process the function if no parameters were found.
process_parameters()  : void
Process the parameters of a matched function.
process_token()  : 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.
setup_groups()  : bool
Set up the regular expressions for each group.
check_argument_count()  : void
Verify that there are no superfluous function arguments.
check_argument_is_string_literal()  : bool
Check if an arbitrary function call parameter is a text string literal suitable for use in the translation functions.
check_for_translator_comment()  : void
Check for the presence of a translators comment if one of the text strings contains a placeholder.
check_placeholders_in_string()  : void
Check the placeholders used in translatable text for common problems.
check_string_has_no_html_wrapper()  : void
Ensure that a translatable text string is not wrapped in HTML code.
check_string_has_translatable_content()  : bool
Check if a parameter which is supposed to hold translatable text actually has translatable text.
check_textdomain_matches()  : void
Check the correct text domain is being used.
compare_single_and_plural_arguments()  : void
Check for inconsistencies in the placeholders between single and plural form of the translatable text string.
is_translators_comment()  : bool
Check if a (collated) comment string starts with 'translators:'.

Constants

SPRINTF_PLACEHOLDER_REGEX

These Regexes were originally copied from https://www.php.net/function.sprintf#93552 and adjusted for better precision and updated specs.

public mixed SPRINTF_PLACEHOLDER_REGEX = '/(?: (?<!%) # Don\'t match a literal % (%%). ( % # Start of placeholder. (?:[0-9]+\$)? # Optional ordering of the placeholders. [+-]? # Optional sign specifier. (?: (?:0|\'.)? # Optional padding specifier - excluding the space. -? # Optional alignment specifier. [0-9]* # Optional width specifier. (?:\.(?:[ 0]|\'.)?[0-9]+)? # Optional precision specifier with optional padding character. | # Only recognize the space as padding in combination with a width specifier. (?:[ ])? # Optional space padding specifier. -? # Optional alignment specifier. [0-9]+ # Width specifier. (?:\.(?:[ 0]|\'.)?[0-9]+)? # Optional precision specifier with optional padding character. ) [bcdeEfFgGhHosuxX] # Type specifier. ) )/x'

UNORDERED_SPRINTF_PLACEHOLDER_REGEX

"Unordered" means there's no position specifier: '%s', not '%2$s'.

public mixed UNORDERED_SPRINTF_PLACEHOLDER_REGEX = '/(?: (?<!%) # Don\'t match a literal % (%%). % # Start of placeholder. [+-]? # Optional sign specifier. (?: (?:0|\'.)? # Optional padding specifier - excluding the space. -? # Optional alignment specifier. [0-9]* # Optional width specifier. (?:\.(?:[ 0]|\'.)?[0-9]+)? # Optional precision specifier with optional padding character. | # Only recognize the space as padding in combination with a width specifier. (?:[ ])? # Optional space padding specifier. -? # Optional alignment specifier. [0-9]+ # Width specifier. (?:\.(?:[ 0]|\'.)?[0-9]+)? # Optional precision specifier with optional padding character. ) [bcdeEfFgGhHosuxX] # Type specifier. )/x'

Properties

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

$text_domain

Text domain.

public array<string|int, string> $text_domain

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

$i18n_functions

The I18N functions in use in WP.

protected array<string, string> $i18n_functions = array('translate' => 'simple', '__' => 'simple', 'esc_attr__' => 'simple', 'esc_html__' => 'simple', '_e' => 'simple', 'esc_attr_e' => 'simple', 'esc_html_e' => 'simple', 'translate_with_gettext_context' => 'context', '_x' => 'context', '_ex' => 'context', 'esc_attr_x' => 'context', 'esc_html_x' => 'context', '_n' => 'number', '_nx' => 'number_context', '_n_noop' => 'noopnumber', '_nx_noop' => 'noopnumber_context')

Key is function name, value is the function type.

Tags
since
0.10.0
since
0.11.0

Changed visibility from public to protected.

$phpcsFile

The current file being sniffed.

protected File $phpcsFile
Tags
since
0.4.0

$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

$parameter_specs

Parameter specifications for the functions in each group.

private array<string, array<string|int, mixed>> $parameter_specs = array('simple' => array(1 => 'text', 2 => 'domain'), 'context' => array(1 => 'text', 2 => 'context', 3 => 'domain'), 'number' => array(1 => 'single', 2 => 'plural', 3 => 'number', 4 => 'domain'), 'number_context' => array(1 => 'single', 2 => 'plural', 3 => 'number', 4 => 'context', 5 => 'domain'), 'noopnumber' => array(1 => 'singular', 2 => 'plural', 3 => 'domain'), 'noopnumber_context' => array(1 => 'singular', 2 => 'plural', 3 => 'context', 4 => 'domain'))

Array of the parameter positions and names.

Tags
since
3.0.0

$text_domain_contains_default

Whether or not the `default` text domain is one of the allowed text domains.

private bool $text_domain_contains_default = false
Tags
since
0.14.0

$text_domain_is_default

Whether or not the `default` text domain is the only allowed text domain.

private bool $text_domain_is_default = false
Tags
since
0.14.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>

Example: groups => array( 'lambda' => array( 'type' => 'error' | 'warning', 'message' => 'Use anonymous functions instead please!', 'functions' => array( 'file_get_contents', 'create_function' ), ) )

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) : 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.

Tags
since
1.0.0

Logic split off from the process_token() method.

process_no_parameters()

Process the function if no parameters were found.

public process_no_parameters(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.

$matched_content : string

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

Tags
since
3.0.0

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) : void
Parameters
$stackPtr : int

The position of the current token in the stack.

Tags
since
1.0.0

Defers to the abstractFunctionRestriction sniff for determining whether something is a function call. The logic after that has been split off to the process_matched_token() method.

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.

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.

check_argument_count()

Verify that there are no superfluous function arguments.

private check_argument_count(int $stackPtr, string $matched_content, array<string|int, mixed> $parameters, int $expected_count) : void
Parameters
$stackPtr : int

The position of the current token in the stack.

$matched_content : string

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

$parameters : array<string|int, mixed>

The parameters array.

$expected_count : int

The expected number of passed arguments.

Tags
since
3.0.0

Check moved from the process_matched_token() method to this method.

check_argument_is_string_literal()

Check if an arbitrary function call parameter is a text string literal suitable for use in the translation functions.

private check_argument_is_string_literal(int $stackPtr, string $matched_content, string $param_name, array<string|int, mixed>|false $param_info) : bool

Will also check and warn about missing parameters.

Parameters
$stackPtr : int

The position of the current token in the stack.

$matched_content : string

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

$param_name : string

The name of the parameter being examined.

$param_info : array<string|int, mixed>|false

Parameter info array for an individual parameter, as received from the PassedParemeters class.

Tags
since
3.0.0

Most of the logic in this method used to be contained in the, now removed, check_argument_tokens() method.

Return values
bool —

Whether or not the argument is a string literal.

check_for_translator_comment()

Check for the presence of a translators comment if one of the text strings contains a placeholder.

private check_for_translator_comment(int $stackPtr, string $matched_content, array<string|int, mixed> $parameters) : void
Parameters
$stackPtr : int

The position of the gettext call token in the stack.

$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
  • The parameter names and expected format for the $parameters parameter has changed.
  • The method visibility has been changed from protected to private.

check_placeholders_in_string()

Check the placeholders used in translatable text for common problems.

private check_placeholders_in_string(string $matched_content, string $param_name, array<string|int, mixed>|false $param_info) : void
Parameters
$matched_content : string

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

$param_name : string

The name of the parameter being examined.

$param_info : array<string|int, mixed>|false

Parameter info array for an individual parameter, as received from the PassedParemeters class.

Tags
since
3.0.0

The logic in this method used to be contained in the, now removed, check_text() method.

check_string_has_no_html_wrapper()

Ensure that a translatable text string is not wrapped in HTML code.

private check_string_has_no_html_wrapper(string $matched_content, string $param_name, array<string|int, mixed>|false $param_info) : void

If the text is wrapped in HTML, the HTML should be moved out of the translatable text string.

Parameters
$matched_content : string

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

$param_name : string

The name of the parameter being examined.

$param_info : array<string|int, mixed>|false

Parameter info array for an individual parameter, as received from the PassedParemeters class.

Tags
since
3.0.0

The logic in this method used to be contained in the, now removed, check_text() method.

check_string_has_translatable_content()

Check if a parameter which is supposed to hold translatable text actually has translatable text.

private check_string_has_translatable_content(string $matched_content, string $param_name, array<string|int, mixed>|false $param_info) : bool
Parameters
$matched_content : string

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

$param_name : string

The name of the parameter being examined.

$param_info : array<string|int, mixed>|false

Parameter info array for an individual parameter, as received from the PassedParemeters class.

Tags
since
3.0.0

The logic in this method used to be contained in the, now removed, check_text() method.

Return values
bool —

Whether or not the text string has translatable content.

check_textdomain_matches()

Check the correct text domain is being used.

private check_textdomain_matches(string $matched_content, string $param_name, array<string|int, mixed>|false $param_info) : void
Parameters
$matched_content : string

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

$param_name : string

The name of the parameter being examined.

$param_info : array<string|int, mixed>|false

Parameter info array for an individual parameter, as received from the PassedParemeters class.

Tags
since
3.0.0

The logic in this method used to be contained in the, now removed, check_argument_tokens() method.

compare_single_and_plural_arguments()

Check for inconsistencies in the placeholders between single and plural form of the translatable text string.

private compare_single_and_plural_arguments(int $stackPtr, array<string|int, mixed> $param_info_single, array<string|int, mixed> $param_info_plural) : void
Parameters
$stackPtr : int

The position of the function call token in the stack.

$param_info_single : array<string|int, mixed>

Parameter info array for the $single parameter, as received from the PassedParemeters class.

$param_info_plural : array<string|int, mixed>

Parameter info array for the $plural parameter, as received from the PassedParemeters class.

Tags
since
3.0.0
  • The parameter names and expected format for the $param_info_single and the $param_info_plural parameters has changed.
  • The method visibility has been changed from protected to private.

is_translators_comment()

Check if a (collated) comment string starts with 'translators:'.

private is_translators_comment(string $content) : bool
Parameters
$content : string

Comment string content.

Tags
since
0.11.0
Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results