Release 3.1.0

.editorconfig

@@ -12,3 +12,9 @@
 
 	[*.md]
 	trim_trailing_whitespace = false
+
+	# Preserve the UTF-8 byte order mark in the BOM ruleset test fixtures, so that
+	# editors honouring EditorConfig do not silently strip it (which would
+	# invalidate the Generic.Files.ByteOrderMark ruleset test).
+	[*-bom.inc]
+	charset = utf-8-bom

.github/CONTRIBUTING.md

@@ -61,7 +61,7 @@ This package contains Composer scripts to quickly run the developer checks which
 
 After `composer install`, you can do:
 
-- `composer lint`: Lint PHP and XML files in against parse errors.
+- `composer lint`: Lint PHP files against parse errors.
 - `composer cs`: Check the code style and code quality of the codebase via PHPCS.
 - `composer test`: Run the unit tests for the VIPCS sniffs.
 - `composer test-coverage`: Run the unit tests for the VIPCS sniffs with coverage enabled.
@@ -91,6 +91,7 @@ When you introduce new `public` sniff properties, or your sniff extends a class
 ### Pre-requisites
 * VIP Coding Standards
 * WordPress-Coding-Standards
+* VariableAnalysis
 * PHPCSUtils 1.x
 * PHP_CodeSniffer 3.x
 * PHPUnit 4.x - 9.x
@@ -144,15 +145,18 @@ The easiest way to do this is to add a `phpunit.xml` file to the root of your VI
 
 Expected output:
 ```
-PHPUnit 9.6.15 by Sebastian Bergmann and contributors.
+Note: Tests are running in "CS" mode
 
-........................................                          40 / 40 (100%)
+PHPUnit 9.6.23 by Sebastian Bergmann and contributors.
 
-45 sniff test files generated 175 unique error codes; 0 were fixable (0%)
+Runtime:       PHP 8.4.10
+Configuration: phpunit.xml.dist
 
-Time: 150 ms, Memory: 20.00 MB
+.......................................                           39 / 39 (100%)
 
-OK (40 tests, 0 assertions)
+52 sniff test files generated 172 unique error codes; 0 were fixable (0%)
+
+Time: 00:00.862, Memory: 58.00 MB
 ```
 
 ### Unit Testing conventions

.github/workflows/basics.yml

@@ -22,51 +22,65 @@ jobs:
     name: 'Basic CS and QA checks'
     runs-on: ubuntu-latest
 
+    env:
+      XMLLINT_INDENT: '	' # This is a tab character.
+
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 7.0.1
 
       - name: Install PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
         with:
           php-version: 'latest'
           coverage: none
           tools: cs2pr
 
-      # Updating the lists can fail intermittently, typically after Microsoft has released a new package.
-      # This should not be blocking for this job, so ignore any errors from this step.
-      # Ref: https://github.com/dotnet/core/issues/4167
-      - name: Update the available packages list
-        continue-on-error: true
-        run: sudo apt-get update
-
-      - name: Install xmllint
-        run: sudo apt-get install --no-install-recommends -y libxml2-utils
-
-      # Show XML violations inline in the file diff.
-      # @link https://github.com/marketplace/actions/xmllint-problem-matcher
-      - name: Enable showing XML issues inline
-        uses: korelstar/xmllint-problem-matcher@v1
-
       # Validate the composer.json file.
       # @link https://getcomposer.org/doc/03-cli.md#validate
       - name: Validate Composer installation
         run: composer validate --no-check-all --strict
 
       - name: 'Composer: adjust dependencies'
-        # Using PHPCS `master` as an early detection system for bugs upstream.
-        run: composer require --no-update --no-scripts squizlabs/php_codesniffer:"dev-master" --no-interaction
+        # Using PHPCS `3.x` as an early detection system for bugs upstream.
+        run: composer require --no-update --no-scripts squizlabs/php_codesniffer:"3.x-dev" --no-interaction
 
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-php-dependencies-with-composer
       - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda" # 4.0.0
         with:
           # Bust the cache at least once a month - output format: YYYY-MM.
           custom-cache-suffix: $(date -u "+%Y-%m")
 
-      - name: 'Validate XML against schema and check code style'
-        run: ./bin/xml-lint
+      # Validate the XML file.
+      - name: Validate rulesets against schema
+        uses: phpcsstandards/xmllint-validate@5189514594c8d5f4cf21b7e5af50f54d697973d7 # v2.0.0
+        with:
+          pattern: "./*/ruleset.xml"
+          xsd-file: "vendor/squizlabs/php_codesniffer/phpcs.xsd"
+
+      # Check the code-style consistency of the XML file.
+      # Note: this needs xmllint, but that will be installed via the phpcsstandards/xmllint-validate action runner in the previous step.
+      - name: Check XML code style
+        run: |
+          diff -B --tabsize=4 ./WordPressVIPMinimum/ruleset.xml <(xmllint --format "./WordPressVIPMinimum/ruleset.xml")
+          diff -B --tabsize=4 ./WordPress-VIP-Go/ruleset.xml <(xmllint --format "./WordPress-VIP-Go/ruleset.xml")
+
+      # Validate dev tool related XML files.
+      - name: Validate Project PHPCS ruleset against schema
+        uses: phpcsstandards/xmllint-validate@5189514594c8d5f4cf21b7e5af50f54d697973d7 # v2.0.0
+        with:
+          pattern: ".phpcs.xml.dist"
+          xsd-file: "vendor/squizlabs/php_codesniffer/phpcs.xsd"
+
+      # Note: PHPUnit 9.3 introduced some new configuration options and deprecated the old versions of those.
+      # For cross-version compatibility, the validation is done against the PHPUnit 9.2 schema.
+      - name: "Validate PHPUnit config for use with PHPUnit 9"
+        uses: phpcsstandards/xmllint-validate@5189514594c8d5f4cf21b7e5af50f54d697973d7 # v2.0.0
+        with:
+          pattern: "phpunit.xml.dist"
+          xsd-file: "vendor/phpunit/phpunit/schema/9.2.xsd"
 
       # Check the code-style consistency of the PHP files.
       - name: Check PHP code style
@@ -90,10 +104,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 7.0.1
 
       - name: Install PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
         with:
           php-version: 'latest'
           coverage: none
@@ -103,7 +117,7 @@ jobs:
       # Dependencies need to be installed to make sure the PHPCS and PHPUnit classes are recognized.
       # @link https://github.com/marketplace/actions/install-php-dependencies-with-composer
       - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda" # 4.0.0
         with:
           # Bust the cache at least once a month - output format: YYYY-MM.
           custom-cache-suffix: $(date -u "+%Y-%m")

.github/workflows/quicktest.yml

@@ -26,9 +26,9 @@ jobs:
     strategy:
       matrix:
         include:
-          - php: '5.4'
+          - php: '7.4'
             dependencies: 'stable'
-          - php: '5.4'
+          - php: '7.4'
             dependencies: 'lowest'
 
           - php: 'latest'
@@ -40,21 +40,25 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 7.0.1
 
       - name: Set up PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
         with:
           php-version: ${{ matrix.php }}
           # With stable PHPCS dependencies, allow for PHP deprecation notices.
           # Unit tests shouldn't fail on those for stable releases where those issues won't get fixed anymore.
           ini-values: error_reporting=E_ALL & ~E_DEPRECATED, display_errors=On
           coverage: none
 
+      - name: Enable creation of `composer.lock` file
+        if: ${{ matrix.dependencies == 'lowest' }}
+        run: composer config --unset lock
+
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-php-dependencies-with-composer
       - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda" # 4.0.0
         with:
           # Bust the cache at least once a month - output format: YYYY-MM.
           custom-cache-suffix: $(date -u "+%Y-%m")

.github/workflows/test.yml

@@ -28,24 +28,24 @@ jobs:
 
     strategy:
       matrix:
-        php: ['5.4', 'latest', '8.4']
+        php: ['7.4', 'latest', '8.5']
 
     name: "Lint: PHP ${{ matrix.php }}"
-    continue-on-error: ${{ matrix.php == '8.4' }}
+    continue-on-error: ${{ matrix.php == '8.5' }}
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 7.0.1
 
       - name: Install PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
         with:
           php-version: ${{ matrix.php }}
           coverage: none
           tools: cs2pr
 
       - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda" # 4.0.0
         with:
           # Bust the cache at least once a month - output format: YYYY-MM.
           custom-cache-suffix: $(date -u "+%Y-%m")
@@ -64,50 +64,43 @@ jobs:
       # - php: The PHP versions to test against.
       # - dependencies: The PHPCS dependencies versions to test against.
       #   IMPORTANT: test runs shouldn't fail because of PHPCS being incompatible with a PHP version.
-      #   - PHPCS will run without errors on PHP 5.4 - 7.4 on any supported version.
-      #   - PHP 8.0 needs PHPCS 3.5.7+ to run without errors, and we require a higher minimum version.
-      #   - PHP 8.1 needs PHPCS 3.6.1+ to run without errors, but works best with 3.7.1+, and we require at least this minimum version.
-      #   - PHP 8.2 and 8.3 need PHPCS 3.8.0+ to run without errors (though the errors don't affect the tests).
+      #   - PHP 8.2, 8.3 and 8.4 need PHPCS 3.8.0+ to run without errors (though the errors don't affect the tests).
       matrix:
-        php: ['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3']
+        php: ['7.4', '8.0', '8.1', '8.2', '8.3', '8.4']
         dependencies: ['lowest', 'stable']
 
         include:
           # Test against dev versions of all dependencies with select PHP versions for early detection of issues.
-          - php: '5.4'
-            dependencies: 'dev'
-          - php: '7.0'
-            dependencies: 'dev'
           - php: '7.4'
             dependencies: 'dev'
-          - php: '8.3'
+          - php: '8.4'
             dependencies: 'dev'
 
           # Test against upcoming PHP version.
-          - php: '8.4'
+          - php: '8.5'
             dependencies: 'dev'
 
     name: "Test: PHP ${{ matrix.php }} - PHPCS ${{ matrix.dependencies }}"
 
-    continue-on-error: ${{ matrix.php == '8.4' }}
+    continue-on-error: ${{ matrix.php == '8.5' }}
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 7.0.1
 
       # With stable PHPCS dependencies, allow for PHP deprecation notices.
       # Unit tests don't need to fail on those for stable releases where those issues won't get fixed anymore.
       - name: Setup ini config
         id: set_ini
         run: |
           if [[ "${{ matrix.dependencies }}" != "dev" ]]; then
-            echo 'PHP_INI=error_reporting=E_ALL & ~E_DEPRECATED, display_errors=On' >> $GITHUB_OUTPUT
+            echo 'PHP_INI=error_reporting=E_ALL & ~E_DEPRECATED, display_errors=On' >> "$GITHUB_OUTPUT"
           else
-            echo 'PHP_INI=error_reporting=-1, display_errors=On' >> $GITHUB_OUTPUT
+            echo 'PHP_INI=error_reporting=-1, display_errors=On' >> "$GITHUB_OUTPUT"
           fi
 
       - name: Install PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
         with:
           php-version: ${{ matrix.php }}
           ini-values: ${{ steps.set_ini.outputs.PHP_INI }}
@@ -117,16 +110,20 @@ jobs:
         if: ${{ matrix.dependencies == 'dev' }}
         run: >
           composer require --no-update --no-scripts --no-interaction
-          squizlabs/php_codesniffer:"dev-master"
+          squizlabs/php_codesniffer:"3.x-dev"
           phpcsstandards/phpcsutils:"dev-develop"
           phpcsstandards/phpcsextra:"dev-develop"
           sirbrillig/phpcs-variable-analysis:"2.x"
           wp-coding-standards/wpcs:"dev-develop"
 
+      - name: Enable creation of `composer.lock` file
+        if: ${{ matrix.dependencies == 'lowest' }}
+        run: composer config --unset lock
+
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-php-dependencies-with-composer
       - name: Install Composer dependencies
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda" # 4.0.0
         with:
           # Bust the cache at least once a month - output format: YYYY-MM.
           custom-cache-suffix: $(date -u "+%Y-%m")

.gitignore

@@ -7,3 +7,4 @@ phpunit.xml
 phpcs.cache
 phpstan.neon
 .phpunit.result.cache
+ruleset-tests-report.json

.phpcs.xml.dist

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="VIP Coding Standards" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="VIP Coding Standards" xsi:noNamespaceSchemaLocation="https://schema.phpcodesniffer.com/phpcs.xsd">
 	<description>The custom ruleset for the VIP Coding Standards itself.</description>
 
 	<file>.</file>
@@ -21,6 +21,7 @@
 		<exclude name="WordPress.NamingConventions.ValidVariableName"/>
 		<exclude name="Universal.Arrays.DisallowShortArraySyntax"/>
 		<exclude name="WordPress.PHP.YodaConditions"/>
+		<exclude name="Generic.Functions.CallTimePassByReference"/>
 	</rule>
 
 	<rule ref="WordPress-Docs"/>
@@ -43,21 +44,32 @@
 	<rule ref="Generic.ControlStructures.DisallowYodaConditions"/>
 
 	<!-- Check code for cross-version PHP compatibility. -->
-	<config name="testVersion" value="5.4-"/>
+	<config name="testVersion" value="7.4-"/>
 	<rule ref="PHPCompatibility">
 		<!-- Exclude PHP constants back-filled by PHPCS. -->
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_finallyFound"/>
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_yieldFound"/>
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_ellipsisFound"/>
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_powFound"/>
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_pow_equalFound"/>
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_spaceshipFound"/>
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_coalesceFound"/>
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_coalesce_equalFound"/>
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_yield_fromFound"/>
-
-		<!-- Unclear how, but appears to be back-filled anyhow, could be that PHP did so before the token was in use. -->
-		<exclude name="PHPCompatibility.PHP.NewConstants.t_traitFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_finallyFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_yieldFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_ellipsisFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_powFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_pow_equalFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_spaceshipFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesceFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesce_equalFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_yield_fromFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_bad_characterFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_fnFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_attributeFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_matchFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_nullsafe_object_operatorFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_name_fully_qualifiedFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_name_qualifiedFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_name_relativeFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_readonlyFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_enumFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_public_setFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_protected_setFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_private_setFound"/>
+		<exclude name="PHPCompatibility.Constants.RemovedConstants.t_bad_characterFound"/>
 	</rule>
 
 </ruleset>