Documentation

GlobalVariablesOverrideSniff extends Sniff
in package
uses IsUnitTestTrait

FinalYes

Warns about overwriting WordPress native global variables.

Tags
since
0.3.0
since
0.4.0

This class now extends the WordPressCS native Sniff class.

since
0.12.0

The $wp_globals property has been moved to the Sniff class.

since
0.13.0

Class name changed: this class is now namespaced.

since
1.0.0

This sniff has been moved from the Variables category to the WP category and renamed from GlobalVariables to GlobalVariablesOverride.

since
1.1.0

The sniff now also detects variables being overriden in the global namespace.

since
2.2.0

The sniff now also detects variable assignments via the list() construct.

uses
IsUnitTestTrait::$custom_test_classes

Table of Contents

Properties

$custom_test_classes  : array<string|int, string>
Custom list of classes which test classes can extend.
$treat_files_as_scoped  : bool
Whether to treat all files as if they were included from within a function.
$override_allowed  : array<string, true>
Allow select variables from the WPGlobalVariablesHelper::$wp_globals array to be overwritten.
$phpcsFile  : File
The current file being sniffed.
$tokens  : array<string|int, mixed>
The list of tokens in the current file being sniffed.
$added_custom_test_classes  : array<string|int, string>
Cache of previously added custom test classes.
$all_test_classes  : array<string, bool>
Combined list of WP/PHPUnit native and custom test classes.
$known_test_classes  : array<string, true>
List of PHPUnit and WP native classes which test classes can extend.

Methods

process()  : int|void
Set sniff properties and hand off to child class for processing of the 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.
add_error()  : void
Add the error.
get_all_test_classes()  : array<string, bool>
Retrieve a list of all registered test classes, both WP/PHPUnit native as well as custom.
is_test_class()  : bool
Check if a class token is part of a unit test suite.
process_global_statement()  : void
Check that global variables imported into a function scope using a global statement are not being overruled.
process_list_assignment()  : int|void
Check that global variables declared via a list construct are prefixed.
process_variable_assignment()  : void
Check that defined global variables are prefixed.

Properties

$custom_test_classes

Custom list of classes which test classes can extend.

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

This property allows end-users to add to the build-in $known_test_classes via their custom PHPCS ruleset. This property will need to be set for each sniff which uses this trait.

Currently this property is used by the WordPress.WP.GlobalVariablesOverride, WordPress.NamingConventions.PrefixAllGlobals and the WordPress.Files.Filename sniffs.

Example usage:

<rule ref="WordPress.[Subset].[Sniffname]">
 <properties>
  <property name="custom_test_classes" type="array">
    <element value="My_Plugin_First_Test_Class"/>
    <element value="My_Plugin_Second_Test_Class"/>
  </property>
 </properties>
</rule>

Note: it is strongly recommended to exclude your test directories for select error codes of those particular sniffs instead of relying on this property/trait.

Tags
since
0.11.0
since
3.0.0

Moved from the Sniff class to this dedicated Trait. Renamed from $custom_test_class_whitelist to $custom_test_classes.

used-by
FileNameSniff
used-by
PrefixAllGlobalsSniff
used-by
GlobalVariablesOverrideSniff

$treat_files_as_scoped

Whether to treat all files as if they were included from within a function.

public bool $treat_files_as_scoped = false

This is mostly useful for projects containing views which are being included from within a function in another file, like themes.

Note: enabling this is discouraged as there is no guarantee that the file will never be included from the global scope.

Tags
since
1.1.0

$override_allowed

Allow select variables from the WPGlobalVariablesHelper::$wp_globals array to be overwritten.

protected array<string, true> $override_allowed = array('content_width' => true, 'wp_cockneyreplace' => true)

A few select variables in WP Core are intended to be overwritten by themes/plugins. This sniff should not throw an error for those.

Key is variable name, value irrelevant.

Tags
since
2.2.0

$phpcsFile

The current file being sniffed.

protected File $phpcsFile
Tags
since
0.4.0

$tokens

The list of tokens in the current file being sniffed.

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

$added_custom_test_classes

Cache of previously added custom test classes.

private array<string|int, string> $added_custom_test_classes = array()

Prevents having to do the same merges over and over again.

Tags
since
3.0.0

$all_test_classes

Combined list of WP/PHPUnit native and custom test classes.

private array<string, bool> $all_test_classes = array()
Tags
since
3.0.0

$known_test_classes

List of PHPUnit and WP native classes which test classes can extend.

private array<string, true> $known_test_classes = array( // Base test cases. 'WP_UnitTestCase' => true, 'WP_UnitTestCase_Base' => true, 'PHPUnit_Adapter_TestCase' => true, // Domain specific base test cases. 'WP_Ajax_UnitTestCase' => true, 'WP_Canonical_UnitTestCase' => true, 'WP_Font_Face_UnitTestCase' => true, 'WP_Test_REST_Controller_Testcase' => true, 'WP_Test_REST_Post_Type_Controller_Testcase' => true, 'WP_Test_REST_TestCase' => true, 'WP_Test_XML_TestCase' => true, 'WP_XMLRPC_UnitTestCase' => true, // PHPUnit native test cases. 'PHPUnit_Framework_TestCase' => true, 'PHPUnit\Framework\TestCase' => true, // PHPUnit native TestCase class when imported via use statement. 'TestCase' => true, )

{internal These are the test cases provided in the /tests/phpunit/includes/ directory of WP Core.}

Key is class name, value irrelevant.

Tags
since
0.11.0
since
3.0.0
  • Moved from the Sniff class to this dedicated Trait.
  • Renamed from $test_class_whitelist to $known_test_classes.
  • Visibility changed from protected to private.

Methods

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_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
0.3.0
since
1.1.0

Split the token specific logic off into separate methods.

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
0.3.0
since
1.1.0

Added class tokens for improved test classes skipping.

Return values
array<string|int, mixed>

add_error()

Add the error.

protected add_error(int $stackPtr[, array<string|int, mixed> $data = array() ]) : void
Parameters
$stackPtr : int

The position of the token to throw the error for.

$data : array<string|int, mixed> = array()

Optional. Array containing one entry holding the name of the variable being overruled. Defaults to the 'content' of the $stackPtr token.

Tags
since
1.1.0

get_all_test_classes()

Retrieve a list of all registered test classes, both WP/PHPUnit native as well as custom.

protected final get_all_test_classes() : array<string, bool>
Tags
since
3.0.0
Return values
array<string, bool>

is_test_class()

Check if a class token is part of a unit test suite.

protected final is_test_class(File $phpcsFile, int $stackPtr) : bool

Unit test classes are identified as such:

  • Class which either extends one of the known test cases, such as WP_UnitTestCase or PHPUnit_Framework_TestCase or extends a custom unit test class as listed in the custom_test_classes property.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the token to be examined. This should be a class, anonymous class or trait token.

Tags
since
0.12.0

Split off from the is_token_in_test_method() method.

since
1.0.0

Improved recognition of namespaced class names.

since
3.0.0
  • Moved from the Sniff class to this dedicated Trait.
  • The $phpcsFile parameter was added.
Return values
bool —

True if the class is a unit test class, false otherwise.

process_global_statement()

Check that global variables imported into a function scope using a global statement are not being overruled.

protected process_global_statement(int $stackPtr, bool $in_function_scope) : void
Parameters
$stackPtr : int

The position of the current token in the stack.

$in_function_scope : bool

Whether the global statement is within a scoped function/closure.

Tags
since
1.1.0

Logic was previously contained in the process_token() method.

process_list_assignment()

Check that global variables declared via a list construct are prefixed.

protected process_list_assignment(int $stackPtr) : int|void
Parameters
$stackPtr : int

The position of the current token in the stack.

Tags
since
2.2.0
Return values
int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

process_variable_assignment()

Check that defined global variables are prefixed.

protected process_variable_assignment(int $stackPtr[, bool $in_list = false ]) : void
Parameters
$stackPtr : int

The position of the current token in the stack.

$in_list : bool = false

Whether or not this is a variable in a list assignment. Defaults to false.

Tags
since
1.1.0

Logic was previously contained in the process_token() method.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results