Documentation

FileNameSniff extends Sniff
in package

WPCS

WordPressCodingStandards

uses IsUnitTestTrait

FinalYes

Ensures filenames do not contain underscores and where applicable are prefixed with `class-`.

Constants

THEME_EXCEPTIONS_REGEX = '` ^ # Anchor to the beginning of the string. (?: # Template prefixes which can have exceptions. (?:archive|category|content|embed|page|single|tag|taxonomy) -[^\.]+ # These need to be followed by a dash and some chars. | (?:application|audio|example|image|message|model|multipart|text|video) #Top-level mime-types (?:_[^\.]+)? # Optionally followed by an underscore and a sub-type. )\.(?:php|inc)$ # End in .php (or .inc for the test files) and anchor to the end of the string. `Dx': Regex for the theme specific exceptions.

Properties

$custom_test_classes : array<string|int, string>: Custom list of classes which test classes can extend.
$is_theme : bool: Whether the codebase being sniffed is a theme.
$strict_class_file_names : bool: Whether to apply strict class file name rules.
$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.
$hyphenation_exceptions : array<string|int, mixed>: Historical exceptions in WP core to the class name rule.
$known_test_classes : array<string, true>: List of PHPUnit and WP native classes which test classes can extend.
$unittest_hyphenation_exceptions : array<string|int, mixed>: Unit test version of the historical exceptions in WP core.

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.
check_filename_for_template_suffix() : void: Check non-class files in "wp-includes" with a "@subpackage Template" tag for a "-template" suffix.
check_filename_has_class_prefix() : void: Check files containing a class for the "class-" prefix and that the rest of the file name reflects the class name.
check_filename_is_hyphenated() : void: Generic check for lowercase hyphenated file names.
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.

THEME_EXCEPTIONS_REGEX

Regex for the theme specific exceptions.


    public
        string
    THEME_EXCEPTIONS_REGEX
    = '`
		^                    # Anchor to the beginning of the string.
		(?:
							 # Template prefixes which can have exceptions.
			(?:archive|category|content|embed|page|single|tag|taxonomy)
			-[^\.]+          # These need to be followed by a dash and some chars.
		|
			(?:application|audio|example|image|message|model|multipart|text|video) #Top-level mime-types
			(?:_[^\.]+)?     # Optionally followed by an underscore and a sub-type.
		)\.(?:php|inc)$      # End in .php (or .inc for the test files) and anchor to the end of the string.
	`Dx'

N.B. This regex currently does not allow for mimetype sublevel only file names, such as plain.php.

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

$is_theme

Whether the codebase being sniffed is a theme.


        public
            bool
    $is_theme
     = false

If true, it will allow for certain typical theme specific exceptions to the filename rules.

$strict_class_file_names

Whether to apply strict class file name rules.


        public
            bool
    $strict_class_file_names
     = true

If true, it demands that classes are prefixed with class- and that the rest of the file name reflects the class name.

$phpcsFile

The current file being sniffed.


        protected
            File
    $phpcsFile

$tokens

The list of tokens in the current file being sniffed.


        protected
            array<string|int, mixed>
    $tokens

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

$all_test_classes

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


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

$hyphenation_exceptions

Historical exceptions in WP core to the class name rule.


        private
            array<string|int, mixed>
    $hyphenation_exceptions
     = array('class.wp-dependencies.php' => true, 'class.wp-scripts.php' => true, 'class.wp-styles.php' => true, 'functions.wp-scripts.php' => true, 'functions.wp-styles.php' => true)

Note: these files were renamed to comply with the naming conventions in WP 6.1.0. This means we no longer need to make an exception for them in the check_filename_has_class_prefix() check, however, we do still need to make an exception in the check_filename_is_hyphenated() check.

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

$unittest_hyphenation_exceptions

Unit test version of the historical exceptions in WP core.


        private
            array<string|int, mixed>
    $unittest_hyphenation_exceptions
     = array('class.wp-dependencies.inc' => true, 'class.wp-scripts.inc' => true, 'class.wp-styles.inc' => true, 'functions.wp-scripts.inc' => true, 'functions.wp-styles.inc' => true)

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.

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.

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>

check_filename_for_template_suffix()

Check non-class files in "wp-includes" with a "@subpackage Template" tag for a "-template" suffix.


    protected
                    check_filename_for_template_suffix(int $stackPtr, string $file_name) : void

Parameters

$stackPtr : int: Stack pointer to the first PHP open tag in the file.
$file_name : string: The name of the current file.

check_filename_has_class_prefix()

Check files containing a class for the "class-" prefix and that the rest of the file name reflects the class name.


    protected
                    check_filename_has_class_prefix(int $class_ptr, string $file_name) : void

Parameters

$class_ptr : int: Stack pointer to the first T_CLASS in the file.
$file_name : string: The name of the current file.

check_filename_is_hyphenated()

Generic check for lowercase hyphenated file names.


    protected
                    check_filename_is_hyphenated(string $file_name) : void

Parameters

$file_name : string: The name of the current file.

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>

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.

Return values

bool —

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

FileNameSniff extends Sniff in package WPCS WordPressCodingStandards uses IsUnitTestTrait

Tags

Table of Contents

Constants

Properties

Methods

Constants

THEME_EXCEPTIONS_REGEX

Tags

Properties

$custom_test_classes

Tags

$is_theme

Tags

$strict_class_file_names

Tags

$phpcsFile

Tags

$tokens

Tags

$added_custom_test_classes

Tags

$all_test_classes

Tags

$hyphenation_exceptions

Tags

$known_test_classes

Tags

$unittest_hyphenation_exceptions

Tags

Methods

process()

Parameters

Tags

Return values

process_token()

Parameters

Return values

register()

Return values

check_filename_for_template_suffix()

Parameters

Tags

check_filename_has_class_prefix()

Parameters

Tags

check_filename_is_hyphenated()

Parameters

Tags

get_all_test_classes()

Tags

Return values

is_test_class()

Parameters

Tags

Return values

FileNameSniff extends Sniff
in package

WPCS

WordPressCodingStandards

uses IsUnitTestTrait