Release PHPCSExtra 1.1.1

.gitattributes

@@ -12,6 +12,7 @@
 .remarkrc                export-ignore
 .yamllint.yml            export-ignore
 phpcs.xml.dist           export-ignore
+phpstan.neon.dist        export-ignore
 phpunit.xml.dist         export-ignore
 phpunit-bootstrap.php    export-ignore
 /.github/                export-ignore

.github/workflows/basics.yml

@@ -95,6 +95,33 @@ jobs:
       - name: Check sniff feature completeness
         run: composer check-complete
 
+  phpstan:
+    name: "PHPStan"
+    runs-on: "ubuntu-latest"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '7.4'
+          coverage: none
+          tools: phpstan
+
+      # Install dependencies and handle caching in one go.
+      # Dependencies need to be installed to make sure the PHPCS and PHPUnit classes are recognized.
+      # @link https://github.com/marketplace/actions/install-composer-dependencies
+      - name: Install Composer dependencies
+        uses: "ramsey/composer-install@v2"
+        with:
+          # Bust the cache at least once a month - output format: YYYY-MM.
+          custom-cache-suffix: $(date -u "+%Y-%m")
+
+      - name: Run PHPStan
+        run: phpstan analyse
+
   remark:
     name: 'QA Markdown'
     runs-on: ubuntu-latest

.gitignore

@@ -5,3 +5,4 @@ vendor/
 /phpcs.xml
 /phpunit.xml
 /.phpunit.result.cache
+phpstan.neon

CHANGELOG.md

@@ -14,6 +14,24 @@ This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses
 
 _Nothing yet._
 
+## [1.1.1] - 2023-08-26
+
+### Changed
+
+#### Modernize
+
+* `Modernize.FunctionCalls.Dirname`: the sniff will now respect a potentially set [`php_version` configuration option][php_version-config] and only report on modernizations which are possible on the configured `php_version`. [#261]
+    If the `php_version` is not set, the sniff will continue to report on all modernization options.
+
+#### Other
+
+* Various documentation improvements. Props in part to [@szepeviktor].
+* Improved defensive coding in select places.
+* Various housekeeping.
+
+[#261]: https://github.com/PHPCSStandards/PHPCSExtra/pull/261
+
+
 ## [1.1.0] - 2023-07-19
 
 ### Added
@@ -488,6 +506,7 @@ This initial alpha release contains the following sniffs:
 [php_version-config]:    https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-php-version
 
 [Unreleased]: https://github.com/PHPCSStandards/PHPCSExtra/compare/stable...HEAD
+[1.1.1]: https://github.com/PHPCSStandards/PHPCSExtra/compare/1.1.0...1.1.1
 [1.1.0]: https://github.com/PHPCSStandards/PHPCSExtra/compare/1.0.4...1.1.0
 [1.0.4]: https://github.com/PHPCSStandards/PHPCSExtra/compare/1.0.3...1.0.4
 [1.0.3]: https://github.com/PHPCSStandards/PHPCSExtra/compare/1.0.2...1.0.3
@@ -498,6 +517,7 @@ This initial alpha release contains the following sniffs:
 [1.0.0-alpha3]: https://github.com/PHPCSStandards/PHPCSExtra/compare/1.0.0-alpha2...1.0.0-alpha3
 [1.0.0-alpha2]: https://github.com/PHPCSStandards/PHPCSExtra/compare/1.0.0-alpha1...1.0.0-alpha2
 
-[@anomiex]:   https://github.com/anomiex
-[@derickr]:   https://github.com/derickr
-[@GaryJones]: https://github.com/GaryJones
+[@anomiex]:     https://github.com/anomiex
+[@derickr]:     https://github.com/derickr
+[@GaryJones]:   https://github.com/GaryJones
+[@szepeviktor]: https://github.com/szepeviktor

Modernize/Sniffs/FunctionCalls/DirnameSniff.php

@@ -13,6 +13,7 @@
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Sniffs\Sniff;
 use PHP_CodeSniffer\Util\Tokens;
+use PHPCSUtils\BackCompat\Helper;
 use PHPCSUtils\Tokens\Collections;
 use PHPCSUtils\Utils\Context;
 use PHPCSUtils\Utils\PassedParameters;
@@ -25,12 +26,21 @@
 final class DirnameSniff implements Sniff
 {
 
+    /**
+     * PHP version as configured or 0 if unknown.
+     *
+     * @since 1.1.1
+     *
+     * @var int
+     */
+    private $phpVersion;
+
     /**
      * Registers the tokens that this sniff wants to listen for.
      *
      * @since 1.0.0
      *
-     * @return int|string[]
+     * @return array<int|string>
      */
     public function register()
     {
@@ -50,6 +60,21 @@ public function register()
      */
     public function process(File $phpcsFile, $stackPtr)
     {
+        if (isset($this->phpVersion) === false || \defined('PHP_CODESNIFFER_IN_TESTS')) {
+            // Set default value to prevent this code from running every time the sniff is triggered.
+            $this->phpVersion = 0;
+
+            $phpVersion = Helper::getConfigData('php_version');
+            if ($phpVersion !== null) {
+                $this->phpVersion = (int) $phpVersion;
+            }
+        }
+
+        if ($this->phpVersion !== 0 && $this->phpVersion < 50300) {
+            // PHP version too low, nothing to do.
+            return;
+        }
+
         $tokens = $phpcsFile->getTokens();
 
         if (\strtolower($tokens[$stackPtr]['content']) !== 'dirname') {
@@ -125,6 +150,8 @@ public function process(File $phpcsFile, $stackPtr)
          * PHP 5.3+: Detect use of dirname(__FILE__).
          */
         if (\strtoupper($pathParam['clean']) === '__FILE__') {
+            $levelsValue = false;
+
             // Determine if the issue is auto-fixable.
             $hasComment = $phpcsFile->findNext(Tokens::$commentTokens, ($opener + 1), $closer);
             $fixable    = ($hasComment === false);
@@ -182,6 +209,11 @@ public function process(File $phpcsFile, $stackPtr)
         /*
          * PHP 7.0+: Detect use of nested calls to dirname().
          */
+        if ($this->phpVersion !== 0 && $this->phpVersion < 70000) {
+            // No need to check for this issue if the PHP version would not allow for it anyway.
+            return;
+        }
+
         if (\preg_match('`^\s*\\\\?dirname\s*\(`i', $pathParam['clean']) !== 1) {
             return;
         }
@@ -218,7 +250,12 @@ public function process(File $phpcsFile, $stackPtr)
          */
 
         // Step 1: Are there comments ? If so, not auto-fixable as we don't want to remove comments.
-        $fixable = true;
+        $fixable          = true;
+        $outerLevelsValue = false;
+        $innerParameters  = [];
+        $innerLevelsParam = false;
+        $innerLevelsValue = false;
+
         for ($i = ($opener + 1); $i < $closer; $i++) {
             if (isset(Tokens::$commentTokens[$tokens[$i]['code']])) {
                 $fixable = false;
@@ -320,9 +357,9 @@ public function process(File $phpcsFile, $stackPtr)
      *
      * @since 1.0.0
      *
-     * @param \PHP_CodeSniffer\Files\File $phpcsFile   The file being scanned.
-     * @param array|false                 $levelsParam The information about the parameter as retrieved
-     *                                                 via PassedParameters::getParameterFromStack().
+     * @param \PHP_CodeSniffer\Files\File     $phpcsFile   The file being scanned.
+     * @param array<string, int|string>|false $levelsParam The information about the parameter as retrieved
+     *                                                     via PassedParameters::getParameterFromStack().
      *
      * @return int|false Integer levels value or FALSE if the levels value couldn't be determined.
      */

Modernize/Tests/FunctionCalls/DirnameUnitTest.2.inc

@@ -0,0 +1,10 @@
+<?php
+
+/*
+ * This test file is run with php_version set to a value of 50000.
+ *
+ * Neither of the fixes the sniff offers will be applied as the PHP version is too low.
+ */
+
+$path = dirname(__FILE__);
+$path = dirname(dirname(__DIR__));

Modernize/Tests/FunctionCalls/DirnameUnitTest.2.inc.fixed

@@ -0,0 +1,10 @@
+<?php
+
+/*
+ * This test file is run with php_version set to a value of 50000.
+ *
+ * Neither of the fixes the sniff offers will be applied as the PHP version is too low.
+ */
+
+$path = dirname(__FILE__);
+$path = dirname(dirname(__DIR__));

Modernize/Tests/FunctionCalls/DirnameUnitTest.3.inc

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * This test file is run with php_version set to a value of 50300.
+ *
+ * The `FileConstant` error code should trigger, but the `Nested` error code
+ * should be ignored as the PHP version is too low.
+ */
+
+$path = dirname(__FILE__);
+$path = dirname(dirname(__DIR__));

Modernize/Tests/FunctionCalls/DirnameUnitTest.3.inc.fixed

@@ -0,0 +1,11 @@
+<?php
+
+/*
+ * This test file is run with php_version set to a value of 50300.
+ *
+ * The `FileConstant` error code should trigger, but the `Nested` error code
+ * should be ignored as the PHP version is too low.
+ */
+
+$path = __DIR__;
+$path = dirname(dirname(__DIR__));

Modernize/Tests/FunctionCalls/DirnameUnitTest.4.inc

@@ -0,0 +1,10 @@
+<?php
+
+/*
+ * This test file is run with php_version set to a value of 70000.
+ *
+ * Both of the fixes the sniff offers will be applied as the PHP version allows for it.
+ */
+
+$path = dirname(__FILE__);
+$path = dirname(dirname(__DIR__));

Modernize/Tests/FunctionCalls/DirnameUnitTest.4.inc.fixed

@@ -0,0 +1,10 @@
+<?php
+
+/*
+ * This test file is run with php_version set to a value of 70000.
+ *
+ * Both of the fixes the sniff offers will be applied as the PHP version allows for it.
+ */
+
+$path = __DIR__;
+$path = dirname(__DIR__, 2);

Modernize/Tests/FunctionCalls/DirnameUnitTest.5.inc

@@ -0,0 +1,7 @@
+<?php
+
+/*
+ * This test file is only here to reset the value of the php_version configuration option.
+ */
+
+dirname($path);