WIP: PHPCS 4.x changes

.github/workflows/quicktest.yml

@@ -65,13 +65,25 @@ jobs:
         if: ${{ matrix.dependencies == 'stable' }}
         run: composer lint
 
-      - name: Run the unit tests without code coverage
-        if: ${{ github.repository_owner != 'WordPress' || github.ref_name != 'develop' }}
-        run: composer run-tests
+      - name: Grab PHPCS version
+        id: phpcs_version
+        run: echo "VERSION=$(vendor/bin/phpcs --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')" >> "$GITHUB_OUTPUT"
 
-      - name: Run the unit tests with code coverage
-        if: ${{ github.repository_owner == 'WordPress' && github.ref_name == 'develop' }}
-        run: composer coverage
+      - name: Run the unit tests without code coverage (PHPCS 3.x)
+        if: ${{ (github.repository_owner != 'WordPress' || github.ref_name != 'develop') && startsWith( steps.phpcs_version.outputs.VERSION, '3.' ) }}
+        run: composer run-tests-phpcs3
+
+      - name: Run the unit tests without code coverage (PHPCS 4.x)
+        if: ${{ (github.repository_owner != 'WordPress' || github.ref_name != 'develop') && startsWith( steps.phpcs_version.outputs.VERSION, '4.' ) }}
+        run: composer run-tests-phpcs4
+
+      - name: Run the unit tests with code coverage (PHPCS 3.x)
+        if: ${{ github.repository_owner == 'WordPress' && github.ref_name == 'develop' && startsWith( steps.phpcs_version.outputs.VERSION, '3.' ) }}
+        run: composer coverage-phpcs3
+
+      - name: Run the unit tests with code coverage (PHPCS 4.x)
+        if: ${{ github.repository_owner == 'WordPress' && github.ref_name == 'develop' && startsWith( steps.phpcs_version.outputs.VERSION, '4.' ) }}
+        run: composer coverage-phpcs4
 
       - name: Send coverage report to Codecov
         if: ${{ success() && github.repository_owner == 'WordPress' && github.ref_name == 'develop' }}

.github/workflows/unit-tests.yml

@@ -15,7 +15,8 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  PHPCS_DEV: '3.x-dev'
+  PHPCS_3_DEV: '3.x-dev'
+  PHPCS_4_DEV: '4.x-dev'
   UTILS_DEV: 'dev-develop'
   EXTRA_DEV: 'dev-develop'
 
@@ -52,25 +53,38 @@ jobs:
 
           # Test against dev versions of all dependencies with select PHP versions for early detection of issues.
           - php: '7.2'
-            dependencies: 'dev'
+            dependencies: 'phpcs-3-dev'
+            extensions: ''
+            coverage: false
+          - php: '7.2'
+            dependencies: 'phpcs-4-dev'
             extensions: ''
             coverage: false
           - php: '8.1'
-            dependencies: 'dev'
+            dependencies: 'phpcs-3-dev'
+            extensions: ''
+            coverage: false
+          - php: '8.1'
+            dependencies: 'phpcs-4-dev'
+            extensions: ''
+            coverage: false
+          - php: '8.4'
+            dependencies: 'phpcs-3-dev'
             extensions: ''
             coverage: false
           - php: '8.4'
-            dependencies: 'dev'
+            dependencies: 'phpcs-4-dev'
             extensions: ''
             coverage: false
 
+
           # Add extra build to test against PHPCS 4.
           #- php: '7.4'
           #  dependencies: '4.0.x-dev as 3.99.99'
 
     name: PHP ${{ matrix.php }} on PHPCS ${{ matrix.dependencies }}
 
-    continue-on-error: ${{ matrix.php == '8.5' }}
+    continue-on-error: ${{ matrix.php == '8.5' || matrix.dependencies == 'phpcs-4-dev' }}
 
     steps:
       - name: Checkout repository
@@ -83,7 +97,7 @@ jobs:
       - name: Setup ini config
         id: set_ini
         run: |
-          if [ "${{ matrix.dependencies }}" != "dev" ]; then
+          if [ "${{ matrix.dependencies }}" != "phpcs-3-dev" ] && [ "${{ matrix.dependencies }}" != "phpcs-4-dev" ]; then
             echo 'PHP_INI=error_reporting=E_ALL & ~E_DEPRECATED, display_errors=On, display_startup_errors=On' >> "$GITHUB_OUTPUT"
           else
             echo 'PHP_INI=error_reporting=-1, display_errors=On, display_startup_errors=On' >> "$GITHUB_OUTPUT"
@@ -97,11 +111,15 @@ jobs:
           coverage: ${{ matrix.coverage && 'xdebug' || 'none' }}
           tools: cs2pr
 
+      # Remove PHPCompatibility as it would (for now) prevent the tests from being able to run against PHPCS 4.x.
+      - name: 'Composer: remove PHPCompatibility'
+        run: composer remove --dev phpcompatibility/php-compatibility --no-update --no-interaction
+
       - name: "Composer: set PHPCS dependencies for tests (dev)"
-        if: ${{ matrix.dependencies == 'dev' }}
+        if: ${{ matrix.dependencies == 'phpcs-3-dev' || matrix.dependencies == 'phpcs-4-dev' }}
         run: >
           composer require --no-update --no-scripts --no-interaction
-          squizlabs/php_codesniffer:"${{ env.PHPCS_DEV }}"
+          squizlabs/php_codesniffer:"${{ matrix.dependencies == 'phpcs-3-dev' && env.PHPCS_3_DEV || env.PHPCS_4_DEV }}"
           phpcsstandards/phpcsutils:"${{ env.UTILS_DEV }}"
           phpcsstandards/phpcsextra:"${{ env.EXTRA_DEV }}"
 
@@ -127,13 +145,25 @@ jobs:
         if: ${{ matrix.dependencies == 'stable' }}
         run: composer lint -- --checkstyle | cs2pr
 
-      - name: Run the unit tests without code coverage
-        if: ${{ matrix.coverage == false || github.repository_owner != 'WordPress' }}
-        run: composer run-tests
+      - name: Grab PHPCS version
+        id: phpcs_version
+        run: echo "VERSION=$(vendor/bin/phpcs --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')" >> "$GITHUB_OUTPUT"
+
+      - name: Run the unit tests without code coverage (PHPCS 3.x)
+        if: ${{ startsWith( steps.phpcs_version.outputs.VERSION, '3.' ) && (matrix.coverage == false || github.repository_owner != 'WordPress') }}
+        run: composer run-tests-phpcs3
+
+      - name: Run the unit tests without code coverage (PHPCS 4.x)
+        if: ${{ startsWith( steps.phpcs_version.outputs.VERSION, '4.' ) && (matrix.coverage == false || github.repository_owner != 'WordPress') }}
+        run: composer run-tests-phpcs4
+
+      - name: Run the unit tests with code coverage (PHPCS 3.x)
+        if: ${{ startsWith( steps.phpcs_version.outputs.VERSION, '3.' ) && matrix.coverage == true && github.repository_owner == 'WordPress' }}
+        run: composer coverage-phpcs3
 
-      - name: Run the unit tests with code coverage
-        if: ${{ matrix.coverage == true && github.repository_owner == 'WordPress' }}
-        run: composer coverage
+      - name: Run the unit tests with code coverage (PHPCS 4.x)
+        if: ${{ startsWith( steps.phpcs_version.outputs.VERSION, '4.' ) && matrix.coverage == true && github.repository_owner == 'WordPress' }}
+        run: composer coverage-phpcs4
 
       - name: Send coverage report to Codecov
         if: ${{ success() && matrix.coverage == true && github.repository_owner == 'WordPress' }}

README.md

@@ -247,6 +247,8 @@ At this moment, WordPressCS offer the following tools:
     - `old_text_domain`: an array with one or more (old) text domain names which need to be replaced;
     - `new_text_domain`: the correct (new) text domain as a string.
 
+    **Note**: When using PHP_CodeSniffer 4.0+, this sniff will fix the text domain everywhere for plugins, but it will **not** fix the text domain in the CSS file header for themes, as PHP_CodeSniffer 4.0+ does not support scanning CSS files. Manual intervention will be required to update the `Text Domain` header in the theme's CSS file.
+
 
 ## Contributing
 

Tests/bootstrap.php

@@ -57,6 +57,16 @@
 	die( 1 );
 }
 
+// Alias the PHPCS 3.x test case to the PHPCS 4.x name.
+if ( class_exists( 'PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest' ) === true
+	&& class_exists( 'PHP_CodeSniffer\Tests\Standards\AbstractSniffTestCase' ) === false
+) {
+	class_alias(
+		'PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest',
+		'PHP_CodeSniffer\Tests\Standards\AbstractSniffTestCase'
+	);
+}
+
 /*
  * Set the PHPCS_IGNORE_TEST environment variable to ignore tests from other standards.
  */

WordPress/AbstractClassRestrictionsSniff.php

@@ -10,6 +10,7 @@
 namespace WordPressCS\WordPress;
 
 use PHP_CodeSniffer\Util\Tokens;
+use PHPCSUtils\BackCompat\Helper;
 use PHPCSUtils\Tokens\Collections;
 use PHPCSUtils\Utils\GetTokensAsString;
 use PHPCSUtils\Utils\Namespaces;
@@ -145,13 +146,20 @@ public function is_targetted_token( $stackPtr ) {
 
 		if ( \T_DOUBLE_COLON === $token['code'] ) {
 			$nameEnd = $this->phpcsFile->findPrevious( Tokens::$emptyTokens, ( $stackPtr - 1 ), null, true );
-			if ( \T_STRING !== $this->tokens[ $nameEnd ]['code'] ) {
+			if ( isset( Collections::nameTokens()[ $this->tokens[ $nameEnd ]['code'] ] ) === false ) {
 				// Hierarchy keyword or object stored in variable.
 				return false;
 			}
 
-			$nameStart = ( $this->phpcsFile->findPrevious( Collections::namespacedNameTokens(), ( $nameEnd - 1 ), null, true ) + 1 );
-			$classname = GetTokensAsString::noEmpties( $this->phpcsFile, $nameStart, $nameEnd );
+			$classname = $this->tokens[ $nameEnd ]['content'];
+			$nameStart = $nameEnd;
+
+			if ( \version_compare( Helper::getVersion(), '3.99.99', '<=' ) === true ) {
+				// For PHPCS 3.x, a namespaced class name is split over multiple tokens so it is necessary to combine then to get the class name.
+				$nameStart = ( $this->phpcsFile->findPrevious( Collections::namespacedNameTokens(), ( $nameEnd - 1 ), null, true ) + 1 );
+				$classname = GetTokensAsString::noEmpties( $this->phpcsFile, $nameStart, $nameEnd );
+			}
+
 			$classname = $this->get_namespaced_classname( $classname, ( $nameStart - 1 ) );
 		}
 

WordPress/AbstractFunctionParameterSniff.php

@@ -62,7 +62,8 @@ public function getGroups() {
 	 * @param int    $stackPtr        The position of the current token in the stack.
 	 * @param string $group_name      The name of the group which was matched.
 	 * @param string $matched_content The token content (function name) which was matched
-	 *                                in lowercase.
+	 *                                in lowercase. For T_NAME_FULLY_QUALIFIED tokens,
+	 *                                the leading backslash is removed.
 	 *
 	 * @return int|void Integer stack pointer to skip forward or void to continue
 	 *                  normal file processing.

WordPress/AbstractFunctionRestrictionsSniff.php

@@ -125,6 +125,7 @@ public function register() {
 
 		return array(
 			\T_STRING,
+			\T_NAME_FULLY_QUALIFIED,
 		);
 	}
 
@@ -201,10 +202,16 @@ public function process_token( $stackPtr ) {
 			return;
 		}
 
-		// Preliminary check. If the content of the T_STRING is not one of the functions we're
+		$content = $this->tokens[ $stackPtr ]['content'];
+
+		if ( \T_NAME_FULLY_QUALIFIED === $this->tokens[ $stackPtr ]['code'] ) {
+			$content = \ltrim( $content, '\\' );
+		}
+
+		// Preliminary check. If the content of the name token is not one of the functions we're
 		// looking for, we can bow out before doing the heavy lifting of checking whether
 		// this is a function call.
-		if ( preg_match( $this->prelim_check_regex, $this->tokens[ $stackPtr ]['content'] ) !== 1 ) {
+		if ( preg_match( $this->prelim_check_regex, $content ) !== 1 ) {
 			return;
 		}
 
@@ -286,7 +293,13 @@ public function is_targetted_token( $stackPtr ) {
 	 *                  normal file processing.
 	 */
 	public function check_for_matches( $stackPtr ) {
-		$token_content = strtolower( $this->tokens[ $stackPtr ]['content'] );
+		$content = $this->tokens[ $stackPtr ]['content'];
+
+		if ( \T_NAME_FULLY_QUALIFIED === $this->tokens[ $stackPtr ]['code'] ) {
+			$content = \ltrim( $content, '\\' );
+		}
+
+		$token_content = strtolower( $content );
 		$skip_to       = array();
 
 		foreach ( $this->groups as $groupName => $group ) {
@@ -319,7 +332,8 @@ public function check_for_matches( $stackPtr ) {
 	 * @param int    $stackPtr        The position of the current token in the stack.
 	 * @param string $group_name      The name of the group which was matched.
 	 * @param string $matched_content The token content (function name) which was matched
-	 *                                in lowercase.
+	 *                                in lowercase. For T_NAME_FULLY_QUALIFIED tokens,
+	 *                                the leading backslash is removed.
 	 *
 	 * @return int|void Integer stack pointer to skip forward or void to continue
 	 *                  normal file processing.

WordPress/Helpers/ArrayWalkingFunctionsHelper.php

@@ -71,7 +71,7 @@ public static function get_functions() {
 	 * @return bool
 	 */
 	public static function is_array_walking_function( $functionName ) {
-		return isset( self::$arrayWalkingFunctions[ strtolower( $functionName ) ] );
+		return isset( self::$arrayWalkingFunctions[ strtolower( ltrim( $functionName, '\\' ) ) ] );
 	}
 
 	/**
@@ -94,6 +94,11 @@ public static function get_callback_parameter( File $phpcsFile, $stackPtr ) {
 		}
 
 		$functionName = strtolower( $tokens[ $stackPtr ]['content'] );
+
+		if ( \T_NAME_FULLY_QUALIFIED === $tokens[ $stackPtr ]['code'] ) {
+			$functionName = ltrim( $functionName, '\\' );
+		}
+
 		if ( isset( self::$arrayWalkingFunctions[ $functionName ] ) === false ) {
 			return false;
 		}

WordPress/Helpers/ConstantsHelper.php

@@ -34,15 +34,16 @@
 final class ConstantsHelper {
 
 	/**
-	 * Determine whether an arbitrary T_STRING token is the use of a global constant.
+	 * Determine whether an arbitrary T_STRING or T_NAME_FULLY_QUALIFIED token is the use of a
+	 * global constant.
 	 *
 	 * @since 1.0.0
 	 * @since 3.0.0 - Moved from the Sniff class to this class.
 	 *              - The method was changed to be `static`.
 	 *              - The `$phpcsFile` parameter was added.
 	 *
 	 * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
-	 * @param int                         $stackPtr  The position of the T_STRING token.
+	 * @param int                         $stackPtr  The position of the T_STRING or T_NAME_FULLY_QUALIFIED token.
 	 *
 	 * @return bool
 	 */
@@ -55,7 +56,9 @@ public static function is_use_of_global_constant( File $phpcsFile, $stackPtr ) {
 		}
 
 		// Is this one of the tokens this function handles ?
-		if ( \T_STRING !== $tokens[ $stackPtr ]['code'] ) {
+		if ( \T_STRING !== $tokens[ $stackPtr ]['code']
+			&& \T_NAME_FULLY_QUALIFIED !== $tokens[ $stackPtr ]['code']
+		) {
 			return false;
 		}
 
@@ -79,6 +82,7 @@ public static function is_use_of_global_constant( File $phpcsFile, $stackPtr ) {
 			\T_INSTANCEOF => true,
 			\T_INSTEADOF  => true,
 			\T_GOTO       => true,
+			\T_AS         => true,
 		);
 		$tokens_to_ignore += Tokens::$ooScopeTokens;
 		$tokens_to_ignore += Collections::objectOperators();
@@ -90,6 +94,14 @@ public static function is_use_of_global_constant( File $phpcsFile, $stackPtr ) {
 			return false;
 		}
 
+		// If the token is a fully qualified name, ensure it does not include a namespace path.
+		if ( \T_NAME_FULLY_QUALIFIED === $tokens[ $stackPtr ]['code'] ) {
+			$trimmed = \ltrim( $tokens[ $stackPtr ]['content'], '\\' );
+			if ( \strpos( $trimmed, '\\' ) !== false ) {
+				return false;
+			}
+		}
+
 		if ( ContextHelper::is_token_namespaced( $phpcsFile, $stackPtr ) === true ) {
 			// Namespaced constant of the same name.
 			return false;