Documentation

I18nTextDomainFixerSniff extends AbstractFunctionParameterSniff
in package

FinalYes

Comprehensive I18n text domain fixer tool.

This sniff can:

  • Add missing text domains.
  • Replace text domains based on an array of old values to a new value.

Note: Without a user-defined configuration in a custom ruleset, this sniff will be ignored.

Tags
since
1.2.0

Table of Contents

Properties

$exclude  : array<string|int, mixed>
Exclude groups.
$new_text_domain  : string
New text domain.
$old_text_domain  : array<string|int, string>
Old text domain(s) to replace.
$supportedTokenizers  : array<string|int, mixed>
A list of tokenizers this sniff supports.
$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|string>>
The WP Internationalization related functions to target for the replacements.
$tokens  : array<string|int, mixed>
The list of tokens in the current file being sniffed.
$header_found  : bool
Whether the plugin/theme header has been seen and fixed yet.
$header_regex_template  : string
Regex template to match theme/plugin headers.
$is_valid  : bool
Whether a valid new text domain was found.
$plugin_header_regex  : string
Regex to match plugin headers.
$plugin_headers  : array<string, bool>
Possible headers for a plugin.
$tab_width  : int
The --tab-width CLI value that is being used.
$theme_header_regex  : string
Regex to match theme headers.
$theme_headers  : array<string, bool>
Possible headers for a theme.
$validated_textdomain  : string
The new text domain as validated.

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_comments()  : int|void
Process comments to find the plugin/theme headers.
process_matched_token()  : int|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()  : 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.
examine_comment_line()  : array<string|int, mixed>
Examine an individual token in a larger comment for plugin/theme headers.
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.

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.

$old_text_domain

Old text domain(s) to replace.

public array<string|int, string> $old_text_domain
Tags
since
1.2.0

$supportedTokenizers

A list of tokenizers this sniff supports.

public array<string|int, mixed> $supportedTokenizers = array('PHP', 'CSS')
Tags
since
1.2.0

$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 = 'i18nfixer'
Tags
since
1.2.0

$phpcsFile

The current file being sniffed.

protected File $phpcsFile
Tags
since
0.4.0

$target_functions

The WP Internationalization related functions to target for the replacements.

protected array<string, array<string, int|string>> $target_functions = array( 'load_textdomain' => array('position' => 1, 'name' => 'domain'), 'load_plugin_textdomain' => array('position' => 1, 'name' => 'domain'), 'load_muplugin_textdomain' => array('position' => 1, 'name' => 'domain'), 'load_theme_textdomain' => array('position' => 1, 'name' => 'domain'), 'load_child_theme_textdomain' => array('position' => 1, 'name' => 'domain'), 'load_script_textdomain' => array('position' => 2, 'name' => 'domain'), 'unload_textdomain' => array('position' => 1, 'name' => 'domain'), '__' => array('position' => 2, 'name' => 'domain'), '_e' => array('position' => 2, 'name' => 'domain'), '_x' => array('position' => 3, 'name' => 'domain'), '_ex' => array('position' => 3, 'name' => 'domain'), '_n' => array('position' => 4, 'name' => 'domain'), '_nx' => array('position' => 5, 'name' => 'domain'), '_n_noop' => array('position' => 3, 'name' => 'domain'), '_nx_noop' => array('position' => 4, 'name' => 'domain'), 'translate_nooped_plural' => array('position' => 3, 'name' => 'domain'), 'esc_html__' => array('position' => 2, 'name' => 'domain'), 'esc_html_e' => array('position' => 2, 'name' => 'domain'), 'esc_html_x' => array('position' => 3, 'name' => 'domain'), 'esc_attr__' => array('position' => 2, 'name' => 'domain'), 'esc_attr_e' => array('position' => 2, 'name' => 'domain'), 'esc_attr_x' => array('position' => 3, 'name' => 'domain'), 'is_textdomain_loaded' => array('position' => 1, 'name' => 'domain'), 'get_translations_for_domain' => array('position' => 1, 'name' => 'domain'), // Deprecated functions. '_c' => array('position' => 2, 'name' => 'domain'), '_nc' => array('position' => 4, 'name' => 'domain'), '__ngettext' => array('position' => 4, 'name' => 'domain'), '__ngettext_noop' => array('position' => 3, 'name' => 'domain'), 'translate_with_context' => array('position' => 2, 'name' => 'domain'), // Shouldn't be used by plugins/themes. 'translate' => array('position' => 2, 'name' => 'domain'), 'translate_with_gettext_context' => array('position' => 3, 'name' => 'domain'), // WP private functions. Shouldn't be used by plugins/themes. '_load_textdomain_just_in_time' => array('position' => 1, 'name' => 'domain'), '_get_path_to_translation_from_lang_dir' => array('position' => 1, 'name' => 'domain'), '_get_path_to_translation' => array('position' => 1, 'name' => 'domain'), )

Function name as key, array with target parameter and name as value.

Tags
since
1.2.0
since
3.0.0

The format of the value has changed from a numerically indexed array containing parameter positions to an array with the parameter position as the index and the parameter name as value.

$tokens

The list of tokens in the current file being sniffed.

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

$header_found

Whether the plugin/theme header has been seen and fixed yet.

private bool $header_found = false
Tags
since
1.2.0

$header_regex_template

Regex template to match theme/plugin headers.

private string $header_regex_template = '`^(?:\s*(?:(?:\*|//)\s*)?)?(%s)\s*:\s*([^\r\n]+)`'
Tags
since
1.2.0

$plugin_header_regex

Regex to match plugin headers.

private string $plugin_header_regex

Set from within the register() method.

Tags
since
1.2.0

$plugin_headers

Possible headers for a plugin.

private array<string, bool> $plugin_headers = array('Plugin Name' => true, 'Plugin URI' => false, 'Description' => false, 'Version' => false, 'Requires at least' => false, 'Requires PHP' => false, 'Author' => false, 'Author URI' => false, 'License' => false, 'License URI' => false, 'Text Domain' => false, 'Domain Path' => false, 'Network' => false, 'Update URI' => false)

Array key is the header name, the value indicated whether it is a required (true) or optional (false) header.

Tags
link
https://developer.wordpress.org/plugins/plugin-basics/header-requirements/
since
1.2.0

$tab_width

The --tab-width CLI value that is being used.

private int $tab_width = null
Tags
since
1.2.0

$theme_header_regex

Regex to match theme headers.

private string $theme_header_regex

Set from within the register() method.

Tags
since
1.2.0

$theme_headers

Possible headers for a theme.

private array<string, bool> $theme_headers = array('Theme Name' => true, 'Theme URI' => false, 'Author' => true, 'Author URI' => false, 'Description' => true, 'Version' => true, 'Requires at least' => true, 'Tested up to' => true, 'Requires PHP' => true, 'License' => true, 'License URI' => true, 'Text Domain' => true, 'Tags' => false, 'Domain Path' => false)

Array key is the header name, the value indicated whether it is a required (true) or optional (false) header.

Tags
link
https://developer.wordpress.org/themes/basics/main-stylesheet-style-css/
since
1.2.0

$validated_textdomain

The new text domain as validated.

private string $validated_textdomain = ''
Tags
since
1.2.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_comments()

Process comments to find the plugin/theme headers.

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

The position of the current token in the stack.

Tags
since
1.2.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) : 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.2.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
1.2.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.

Tags
since
1.2.0
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>
Tags
since
1.2.0
Return values
array<string|int, mixed>

examine_comment_line()

Examine an individual token in a larger comment for plugin/theme headers.

protected examine_comment_line(int $stackPtr, string $regex, array<string|int, mixed> $headers, array<string|int, mixed> $comment_details) : array<string|int, mixed>
Parameters
$stackPtr : int

The position of the current token in the stack.

$regex : string

The regex to use to examine the comment line.

$headers : array<string|int, mixed>

Valid headers for a plugin or theme.

$comment_details : array<string|int, mixed>

The information collected so far.

Tags
since
1.2.0
Return values
array<string|int, mixed> —

Adjusted $comment_details array

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.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results