Changeset 63019 for trunk/phpstan.neon.dist

Timestamp:

08/05/2026 07:16:57 AM (2 months ago)

Author:

westonruter

Message:

Build/Test Tools: Raise the PHPStan rule level to 1.

Level 1 adds detection of possibly undefined variables, and of unknown magic methods and properties on classes with __call and __get. The 494 errors this surfaces in existing code are recorded in baselines rather than being fixed here, so that new code is held to level 1 straight away while the existing reports are worked through separately. No files under src are changed.

The tests/phpstan/baseline.php file is replaced by one baseline per error identifier under tests/phpstan/baselines, so that the remaining work on each kind of error is visible as a single file that should shrink to nothing and then be deleted. Every entry is scoped to the file which the error occurs in and carries an exact occurrence count, so that a new occurrence of an already baselined error is reported rather than absorbed. The consequence is that fixing a baselined error means regenerating its baseline in the same change, because the count no longer matches.

PHPStan's own --generate-baseline captures every error a run reports, with no way to restrict it to one identifier, so tests/phpstan/generate-baselines.php is added to write the files instead, exposed as composer phpstan:baselines and as npm run typecheck:php:baselines. A run also deletes any baseline whose identifier no longer reports anything, and rewrites the list of baselines in phpstan.neon.dist. The ignoreErrors in that file now has a comment explaining how it is distinct from a baseline: an entry there is a decision that the code is right as written, whereas a baseline entry is work still to be done. The constants that add_theme_support() defines are declared in the configuration so that the errors around them are resolved rather than recorded, and tests/phpstan/README.md is updated throughout.

Three problems in the static analysis GHA workflow are fixed as well. Fixing a baselined error makes PHPStan report an unmatched ignore, which surfaced only as an annotation reading like a complaint about a correct fix; the job now detects any ignore.* report and fails with an explanation of what to run. An analysis that did not finish passed as a green run, because the status of the pipeline was that of cs2pr rather than of PHPStan; that status is now recovered and a run that did not finish fails. The path filter deciding whether the workflow runs named only the old baseline file, so a pull request that merely regenerated the baselines would not have run the analysis that checks them.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11151.
Follow-up to r61699.

Props westonruter, sabernhardt, apermo, johnjamesjacoby, adamsilverstein, justlevine.
See #61175.
Fixes #64680.

File:

• trunk/phpstan.neon.dist (modified) (2 diffs)

trunk/phpstan.neon.dist

@@ -15 +15 @@
         - vendor/phpstan/phpstan-phpunit/extension.neon
 
-        # The baseline file includes preexisting errors in the codebase that should be ignored.
+        # Preexisting errors that should be ignored, one baseline per error identifier
+        # so that the remaining work on each is visible as a single shrinking file.
+        # Each is meant to reach zero and be deleted, taking its line below with it.
         # https://phpstan.org/user-guide/baseline
-        - tests/phpstan/baseline.php
+        #
+        # Regenerate with `composer phpstan:baselines`, which rewrites both the files
+        # and the list between the markers. Do not edit that list by hand.
+        # phpstan:baselines start
+        - tests/phpstan/baselines/empty.variable.neon
+        - tests/phpstan/baselines/isset.variable.neon
+        - tests/phpstan/baselines/variable.undefined.neon
+        # phpstan:baselines end
 
 parameters:
         # https://phpstan.org/user-guide/rule-levels
-        level: 0
+        level: 1
         reportUnmatchedIgnoredErrors: true
 
+        # The following ignored errors are not intended to be fixed, as distinct from the baselines
+        # included above.
+        #
+        # A baseline records work still to be done. Every entry in one is in scope to be fixed, and
+        # each file is meant to reach zero and then be deleted. An entry here is the opposite: a
+        # decision that the code is right as written and the report is not actionable, whether
+        # because PHPStan cannot see what makes the code safe, or because satisfying it would mean
+        # changing code that has no other reason to change.
+        #
+        # So prefer fixing an error, and baseline it when it cannot be fixed yet. Add it here only
+        # when it should never be fixed, and say why.
         ignoreErrors:
                 # Level 0:
@@ -41 +61 @@
                         path: src/wp-includes/canonical.php
                         count: 1
+
                 # Level 2:
                 # ValueError is PHP 8.0+; core throws it conditionally so the docblocks are correct for WP's 7.4+ range,