Merge pull request #731 from PHPCSStandards/develop

Release 1.2.0

Author: jrfnl

.github/GHPages/UpdateWebsite.php

@@ -268,7 +268,7 @@ private function replace(string $search, string $replace, string $subject, int $
     private function getContents(string $source): string
     {
         $contents = \file_get_contents($source);
-        if (!$contents) {
+        if (\is_string($contents) === false) {
             throw new RuntimeException(\sprintf('Failed to read doc file: %s', $source));
         }
 

.github/GHPages/update-docgen-config.php

@@ -44,7 +44,7 @@
         echo 'This is your own responsibility!' . \PHP_EOL, \PHP_EOL;
 
         $config = \file_get_contents($projectRoot . '/' . $destination);
-        if (!$config) {
+        if (\is_string($config) === false) {
             echo "ERROR: Failed to read phpDocumentor $destination configuration file.", \PHP_EOL;
             exit(1);
         }
@@ -59,7 +59,7 @@
         );
     } else {
         $config = \file_get_contents($projectRoot . '/' . $source);
-        if (!$config) {
+        if (\is_string($config) === false) {
             echo "ERROR: Failed to read phpDocumentor $source configuration template file.", \PHP_EOL;
             exit(1);
         }

.github/dependabot.yml

@@ -5,18 +5,6 @@
 
 version: 2
 updates:
-  - package-ecosystem: "composer"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    open-pull-requests-limit: 5 # Set to 0 to (temporarily) disable.
-    versioning-strategy: widen
-    commit-message:
-      prefix: "Composer:"
-      include: "scope"
-    labels:
-      - "Type: chores/QA"
-
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/basics.yml

@@ -27,6 +27,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
 
       - name: Install PHP
         uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # 2.35.5
@@ -44,9 +46,8 @@ jobs:
         run: |
           # The sniff stage doesn't run the unit tests, so no need for PHPUnit.
           composer remove --no-update --dev phpunit/phpunit --no-scripts
-          # Using PHPCS `3.x` as an early detection system for bugs upstream.
-          # This should be changed to 4.x, but we'll need to wait for PHPCSDevCS to be compatible with 4.x.
-          composer require --no-update squizlabs/php_codesniffer:"3.x-dev"
+          # Using PHPCS `4.x` as an early detection system for bugs upstream.
+          composer require --no-update squizlabs/php_codesniffer:"4.x-dev"
 
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-php-dependencies-with-composer

.github/workflows/quicktest.yml

@@ -38,11 +38,11 @@ jobs:
 
         include:
           - php: '7.2'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: '7.2'
             phpcs_version: '4.x-dev'
           - php: 'latest'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: 'latest'
             phpcs_version: '4.x-dev'
 
@@ -51,6 +51,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
 
       # On stable PHPCS versions, 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.
@@ -70,7 +72,7 @@ jobs:
           ini-values: ${{ steps.set_ini.outputs.PHP_INI }}
           coverage: none
 
-      # Remove PHPCSDevCS as it would (for now) prevent the tests from being able to run against PHPCS 4.x.
+      # Remove PHPCSDevCS as it would (for now) prevent the tests from being able to run against PHPCS "lowest".
       - name: 'Composer: remove PHPCSDevCS'
         run: composer remove --dev phpcsstandards/phpcsdevcs --no-update --no-interaction
 

.github/workflows/test.yml

@@ -39,6 +39,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
 
       - name: Install PHP
         uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # 2.35.5
@@ -85,30 +87,30 @@ jobs:
         #
         # The matrix is set up so as not to duplicate the builds which are run for code coverage.
         php: ['5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3']
-        phpcs_version: ['lowest', '3.x-dev', '4.0.0', '4.x-dev']
+        phpcs_version: ['lowest', '3.x-dev', '4.0.1', '4.x-dev']
         risky: [false]
         experimental: [false]
 
         exclude:
           - php: '5.5'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: '5.5'
             phpcs_version: '4.x-dev'
           - php: '5.6'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: '5.6'
             phpcs_version: '4.x-dev'
           - php: '7.0'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: '7.0'
             phpcs_version: '4.x-dev'
           - php: '7.1'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: '7.1'
             phpcs_version: '4.x-dev'
           # Also exclude the 7.2 builds as those are run in code coverage, no need to duplicate.
           - php: '7.2'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: '7.2'
             phpcs_version: '4.x-dev'
 
@@ -161,7 +163,7 @@ jobs:
             experimental: true
 
           - php: '8.4'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
             risky: true
             experimental: true
 
@@ -177,6 +179,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
 
       # On stable PHPCS versions, 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.
@@ -197,7 +201,7 @@ jobs:
           ini-values: ${{ steps.set_ini.outputs.PHP_INI }}
           coverage: none
 
-      # Remove PHPCSDevCS as it would (for now) prevent the tests from being able to run against PHPCS 4.x.
+      # Remove PHPCSDevCS as it would (for now) prevent the tests from being able to run against PHPCS "lowest".
       - name: 'Composer: remove PHPCSDevCS'
         run: composer remove --dev phpcsstandards/phpcsdevcs --no-update --no-interaction
 
@@ -295,15 +299,15 @@ jobs:
             phpcs_version: '4.x-dev'
             extensions: ':iconv' # Run one build with iconv disabled.
           - php: '8.4'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: '8.4'
             phpcs_version: '3.x-dev'
           - php: '8.4'
             phpcs_version: 'lowest'
           - php: '7.2'
             phpcs_version: '4.x-dev'
           - php: '7.2'
-            phpcs_version: '4.0.0'
+            phpcs_version: '4.0.1'
           - php: '5.4'
             phpcs_version: '3.x-dev'
           - php: '5.4'
@@ -314,6 +318,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
 
       # On stable PHPCS versions, 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.

.github/workflows/update-docs.yml

@@ -63,6 +63,7 @@ jobs:
           ref: ${{ steps.base_branch.outputs.BRANCH }}
           # fetch-depth is needed to allow for retrieving the last tag for a non-tag workflow run.
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Install PHP
         uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # 2.35.5
@@ -112,7 +113,7 @@ jobs:
       # Retention is normally 90 days, but this artifact is only for reviewing
       # and debugging the generated files for the website.
       - name: Upload the generated files
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: generated-files
           path: ./docs/

.github/workflows/update-phpcs-versionnr.yml

@@ -55,6 +55,7 @@ jobs:
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           ref: ${{ steps.branches.outputs.BASE }}
+          persist-credentials: false
 
       - name: Update the version constant in the test file (PHPCS 3)
         if: ${{ startsWith( steps.version.outputs.TAG, '3.' ) }}

CHANGELOG.md

@@ -10,6 +10,35 @@ This projects adheres to [Keep a CHANGELOG](https://keepachangelog.com/) and use
 _Nothing yet._
 
 
+## [1.2.0] - 2025-11-11
+
+### Added
+
+#### Utils
+
+* New [`PHPCSUtils\Utils\AttributeBlock`][`AttributeBlock`] class: Utility functions to examine attribute blocks. [#720], [#729]
+    For the purposes of these utilities, an "attribute block" is defined as being an attribute opener, an attribute closer and everything between. I.e. `#[MyAttribute(1, 2), AnotherAttribute]` is one attribute block.
+    Initial set of available methods:
+    - `getAttributes()` to retrieve information about each attribute being instantiated within a particular attribute block.
+    - `countAttributes()` to retrieve a count of the number of attribute instantiations with a particular attribute block.
+    - `appliesTo()` to find the stack pointer to the language construct an attribute block applies to.
+* New `PHPCSUtils\Utils\Constants::getAttributeOpeners()`, `PHPCSUtils\Utils\FunctionDeclarations::getAttributeOpeners()`, `PHPCSUtils\Utils\ObjectDeclarations::getAttributeOpeners()` and `PHPCSUtils\Utils\Variables::getAttributeOpeners()` utility methods. [#719]
+    These methods will each return an array with the stack pointers to the attribute openers for applicable attribute blocks.
+    This may be an empty array if no attributes apply to the constant/function/OO structure/property.
+
+### Changed
+
+#### Other
+
+* Dropped support for [PHP_CodeSniffer] < 3.13.5/<4.00. [#729]
+    Please ensure you run `composer update phpcsstandards/phpcsutils --with-dependencies` to benefit from this.
+* Various housekeeping.
+
+[#719]: https://github.com/PHPCSStandards/PHPCSUtils/pull/719
+[#720]: https://github.com/PHPCSStandards/PHPCSUtils/pull/720
+[#729]: https://github.com/PHPCSStandards/PHPCSUtils/pull/729
+
+
 ## [1.1.3] - 2025-10-16
 
 ### Changed
@@ -1293,6 +1322,7 @@ This initial alpha release contains the following utility classes:
 
 
 [Unreleased]:   https://github.com/PHPCSStandards/PHPCSUtils/compare/stable...HEAD
+[1.2.0]:        https://github.com/PHPCSStandards/PHPCSUtils/compare/1.1.3...1.2.0
 [1.1.3]:        https://github.com/PHPCSStandards/PHPCSUtils/compare/1.1.2...1.1.3
 [1.1.2]:        https://github.com/PHPCSStandards/PHPCSUtils/compare/1.1.1...1.1.2
 [1.1.1]:        https://github.com/PHPCSStandards/PHPCSUtils/compare/1.1.0...1.1.1
@@ -1329,6 +1359,7 @@ This initial alpha release contains the following utility classes:
 [`Collections`]:                   https://phpcsutils.com/phpdoc/classes/PHPCSUtils-Tokens-Collections.html
 [`TokenHelper`]:                   https://phpcsutils.com/phpdoc/classes/PHPCSUtils-Tokens-TokenHelper.html
 [`Arrays`]:                        https://phpcsutils.com/phpdoc/classes/PHPCSUtils-Utils-Arrays.html
+[`AttributeBlock`]:                https://phpcsutils.com/phpdoc/classes/PHPCSUtils-Utils-AttributeBlock.html
 [`Conditions`]:                    https://phpcsutils.com/phpdoc/classes/PHPCSUtils-Utils-Conditions.html
 [`Constants`]:                     https://phpcsutils.com/phpdoc/classes/PHPCSUtils-Utils-Constants.html
 [`Context`]:                       https://phpcsutils.com/phpdoc/classes/PHPCSUtils-Utils-Context.html

PHPCSUtils/BackCompat/BCFile.php

@@ -524,7 +524,7 @@ public static function getMethodParameters(File $phpcsFile, $stackPtr)
      *
      * Changelog for the PHPCS native function:
      * - Introduced in PHPCS 0.0.5.
-     * - The upstream method has received no significant updates since PHPCS 3.13.3.
+     * - The upstream method has received no significant updates since PHPCS 3.13.5.
      *
      * @see \PHP_CodeSniffer\Files\File::getMethodProperties()      Original source.
      * @see \PHPCSUtils\Utils\FunctionDeclarations::getProperties() PHPCSUtils native improved version.
@@ -765,7 +765,7 @@ public static function getMemberProperties(File $phpcsFile, $stackPtr)
      *
      * Changelog for the PHPCS native function:
      * - Introduced in PHPCS 1.3.0.
-     * - The upstream method has received no significant updates since PHPCS 3.13.3.
+     * - The upstream method has received no significant updates since PHPCS 3.13.5.
      *
      * @see \PHP_CodeSniffer\Files\File::getClassProperties()          Original source.
      * @see \PHPCSUtils\Utils\ObjectDeclarations::getClassProperties() PHPCSUtils native improved version.
@@ -793,7 +793,7 @@ public static function getClassProperties(File $phpcsFile, $stackPtr)
      *
      * Changelog for the PHPCS native function:
      * - Introduced in PHPCS 0.0.5.
-     * - The upstream method has received no significant updates since PHPCS 3.13.3.
+     * - The upstream method has received no significant updates since PHPCS 3.13.5.
      *
      * @see \PHP_CodeSniffer\Files\File::isReference() Original source.
      * @see \PHPCSUtils\Utils\Operators::isReference() PHPCSUtils native improved version.
@@ -819,7 +819,7 @@ public static function isReference(File $phpcsFile, $stackPtr)
      *
      * Changelog for the PHPCS native function:
      * - Introduced in PHPCS 0.0.5.
-     * - The upstream method has received no significant updates since PHPCS 3.13.3.
+     * - The upstream method has received no significant updates since PHPCS 3.13.5.
      *
      * @see \PHP_CodeSniffer\Files\File::getTokensAsString() Original source.
      * @see \PHPCSUtils\Utils\GetTokensAsString              Related set of functions.
@@ -848,7 +848,7 @@ public static function getTokensAsString(File $phpcsFile, $start, $length, $orig
      *
      * Changelog for the PHPCS native function:
      * - Introduced in PHPCS 2.1.0.
-     * - The upstream method has received no significant updates since PHPCS 3.13.3.
+     * - The upstream method has received no significant updates since PHPCS 3.13.5.
      *
      * @see \PHP_CodeSniffer\Files\File::findStartOfStatement() Original source.
      *
@@ -872,7 +872,7 @@ public static function findStartOfStatement(File $phpcsFile, $start, $ignore = n
      *
      * Changelog for the PHPCS native function:
      * - Introduced in PHPCS 2.1.0.
-     * - The upstream method has received no significant updates since PHPCS 3.13.3.
+     * - The upstream method has received no significant updates since PHPCS 3.13.5.
      *
      * @see \PHP_CodeSniffer\Files\File::findEndOfStatement() Original source.
      *
@@ -896,7 +896,7 @@ public static function findEndOfStatement(File $phpcsFile, $start, $ignore = nul
      *
      * Changelog for the PHPCS native function:
      * - Introduced in PHPCS 0.0.5.
-     * - The upstream method has received no significant updates since PHPCS 3.13.3.
+     * - The upstream method has received no significant updates since PHPCS 3.13.5.
      *
      * @see \PHP_CodeSniffer\Files\File::hasCondition()  Original source.
      * @see \PHPCSUtils\Utils\Conditions::hasCondition() PHPCSUtils native alternative.
@@ -921,7 +921,7 @@ public static function hasCondition(File $phpcsFile, $stackPtr, $types)
      *
      * Changelog for the PHPCS native function:
      * - Introduced in PHPCS 1.3.0.
-     * - The upstream method has received no significant updates since PHPCS 3.13.3.
+     * - The upstream method has received no significant updates since PHPCS 3.13.5.
      *
      * @see \PHP_CodeSniffer\Files\File::getCondition()  Original source.
      * @see \PHPCSUtils\Utils\Conditions::getCondition() More versatile alternative.