Changeset 62642

Timestamp:

07/06/2026 03:47:16 PM (2 months ago)

Author:

westonruter

Message:

Build/Test Tools: Honor statement-level @global tags in PHPStan.

The GlobalDocBlockVisitor PHPStan extension introduced in [62292] only read @global tags from the enclosing function's docblock and skipped global statements outside any function/method. This meant that file-scope global statements (e.g. in admin templates included into another scope) required a redundant inline @var tag in addition to the @global tag for PHPStan to resolve the variable's type.

Now @global tags in a docblock attached directly to a global statement are honored as well. Statement-level tags take precedence over the enclosing function's tags for the same variable, and handwritten @var annotations continue to take precedence over synthetic ones. At higher PHPStan rule levels this resolves several hundred pre-existing errors, primarily in admin screen templates.

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

See #64898.

File:

• trunk/tests/phpstan/GlobalDocBlockVisitor.php (modified) (3 diffs)

trunk/tests/phpstan/GlobalDocBlockVisitor.php

@@ -26 +26 @@
  * visitor closes the gap so PHPStan can use the existing core annotations
  * without each `global` statement needing its own redundant `@var`.
+ *
+ * `@global` tags in a docblock attached directly to a `global` statement are
+ * honored as well, and take precedence over the enclosing function's tags.
+ * This makes `@global` sufficient for file-scope `global` statements (e.g. in
+ * templates included into another scope), which have no enclosing function
+ * docblock at all.
  *
  * Functions that do not document a global, or that import a global the
@@ -74 +80 @@
                 }
 
-                if ( ! ( $node instanceof Node\Stmt\Global_ ) || $this->stack === array() ) {
+                if ( ! ( $node instanceof Node\Stmt\Global_ ) ) {
                         return null;
                 }
 
-                $map = $this->stack[ count( $this->stack ) - 1 ];
+                $map = $this->stack !== array() ? $this->stack[ count( $this->stack ) - 1 ] : array();
+
+                $existing      = $node->getDocComment();
+                $existing_text = $existing !== null ? $existing->getText() : '';
+
+                /*
+                 * Also honor `@global` tags on the docblock attached directly to the
+                 * `global` statement itself. This covers file-scope statements (which
+                 * have no enclosing function docblock) and takes precedence over the
+                 * enclosing function's tags for the same variable.
+                 */
+                if ( $existing_text !== '' ) {
+                        $map = array_merge( $map, $this->parse_global_tags( $existing_text ) );
+                }
+
                 if ( $map === array() ) {
                         return null;
@@ -88 +108 @@
                  * the remaining variables in a multi-variable `global $a, $b;` statement.
                  */
-                $existing       = $node->getDocComment();
-                $existing_text  = $existing !== null ? $existing->getText() : '';
-                $already_typed  = array();
+                $already_typed = array();
                 if ( $existing_text !== '' && preg_match_all( '/@(?:phpstan-)?var\s+[^\n]*?\$(\w+)/', $existing_text, $existing_matches ) > 0 ) {
                         $already_typed = array_flip( $existing_matches[1] );