From e686ff0c461aa7458f0c5691213abdd8a077fe76 Mon Sep 17 00:00:00 2001 From: Mukesh Panchal Date: Wed, 4 Nov 2026 13:47:09 +0530 Subject: [PATCH 1/2] Docs: Remove `@var` tags from `define()` constant docblocks. A `@var` tag documents a variable or a property. Above a `define()` call it has no variable to describe, so PHPStan reports `varTag.noVariable`. PHPStan already infers each constant's type from its value. Most `define()` docblocks in core have no `@var` tag: 174 have none and 17 have one. The `CUSTOM_TAGS` tag was also wrong. It documented `array[]|false`, but the constant is a boolean flag, and core only checks `! CUSTOM_TAGS`. Its description now says to define the constant as `true` to use the custom tag globals. This change removes eight `@var` tags and the matching `varTag.noVariable` baseline entries. There is no runtime change. See #65817. Co-Authored-By: Claude Opus 5.5 --- src/wp-admin/install.php | 1 - src/wp-admin/profile.php | 1 - src/wp-admin/upgrade.php | 1 - src/wp-cron.php | 2 -- src/wp-includes/kses.php | 4 +-- src/wp-includes/rest-api.php | 3 -- src/xmlrpc.php | 2 -- .../phpstan/baselines/varTag.noVariable.neon | 35 ------------------- 8 files changed, 1 insertion(+), 48 deletions(-) diff --git a/src/wp-admin/install.php b/src/wp-admin/install.php index 85ae31b68b5ae..4a6a57c4be30b 100644 --- a/src/wp-admin/install.php +++ b/src/wp-admin/install.php @@ -27,7 +27,6 @@ * We are installing WordPress. * * @since 1.5.1 - * @var bool */ define( 'WP_INSTALLING', true ); diff --git a/src/wp-admin/profile.php b/src/wp-admin/profile.php index 18fb60069ba75..e7afba6631c6c 100644 --- a/src/wp-admin/profile.php +++ b/src/wp-admin/profile.php @@ -10,7 +10,6 @@ * This is a profile page. * * @since 2.5.0 - * @var bool */ define( 'IS_PROFILE_PAGE', true ); diff --git a/src/wp-admin/upgrade.php b/src/wp-admin/upgrade.php index 69a7b7693b44e..da84dc4466ccc 100644 --- a/src/wp-admin/upgrade.php +++ b/src/wp-admin/upgrade.php @@ -10,7 +10,6 @@ * We are upgrading WordPress. * * @since 1.5.1 - * @var bool */ define( 'WP_INSTALLING', true ); diff --git a/src/wp-cron.php b/src/wp-cron.php index 417dcce375849..92dfb67b92db1 100644 --- a/src/wp-cron.php +++ b/src/wp-cron.php @@ -36,8 +36,6 @@ /** * Tell WordPress the cron task is running. - * - * @var bool */ define( 'DOING_CRON', true ); diff --git a/src/wp-includes/kses.php b/src/wp-includes/kses.php index aee33b474a4d6..f98ebc37b52c1 100644 --- a/src/wp-includes/kses.php +++ b/src/wp-includes/kses.php @@ -36,7 +36,7 @@ * Using `CUSTOM_TAGS` is not recommended and should be considered deprecated. The * {@see 'wp_kses_allowed_html'} filter is more powerful and supplies context. * - * When using this constant, make sure to set all of these globals to arrays: + * To use custom tags, define this constant as `true` and set all of these globals to arrays: * * - `$allowedposttags` * - `$allowedtags` @@ -45,8 +45,6 @@ * * @see wp_kses_allowed_html() * @since 1.2.0 - * - * @var array[]|false Array of default allowable HTML tags, or false to use the defaults. */ if ( ! defined( 'CUSTOM_TAGS' ) ) { define( 'CUSTOM_TAGS', false ); diff --git a/src/wp-includes/rest-api.php b/src/wp-includes/rest-api.php index f40021f4d06cd..f1c445e4c58ea 100644 --- a/src/wp-includes/rest-api.php +++ b/src/wp-includes/rest-api.php @@ -9,8 +9,6 @@ /** * Version number for our API. - * - * @var string */ define( 'REST_API_VERSION', '2.0' ); @@ -481,7 +479,6 @@ function rest_api_loaded() { * Whether this is a REST Request. * * @since 4.4.0 - * @var bool */ define( 'REST_REQUEST', true ); diff --git a/src/xmlrpc.php b/src/xmlrpc.php index ae73f687a2daa..bbf170d1126f4 100644 --- a/src/xmlrpc.php +++ b/src/xmlrpc.php @@ -7,8 +7,6 @@ /** * Whether this is an XML-RPC Request. - * - * @var bool */ define( 'XMLRPC_REQUEST', true ); diff --git a/tests/phpstan/baselines/varTag.noVariable.neon b/tests/phpstan/baselines/varTag.noVariable.neon index 36e0f9fed1382..e834bc62d69a9 100644 --- a/tests/phpstan/baselines/varTag.noVariable.neon +++ b/tests/phpstan/baselines/varTag.noVariable.neon @@ -18,43 +18,8 @@ parameters: ignoreErrors: - - - message: '#^PHPDoc tag @var does not specify variable name\.$#' - identifier: varTag.noVariable - count: 1 - path: ../../../src/wp-admin/install.php - - - message: '#^PHPDoc tag @var does not specify variable name\.$#' - identifier: varTag.noVariable - count: 1 - path: ../../../src/wp-admin/profile.php - - - message: '#^PHPDoc tag @var does not specify variable name\.$#' - identifier: varTag.noVariable - count: 1 - path: ../../../src/wp-admin/upgrade.php - - - message: '#^PHPDoc tag @var does not specify variable name\.$#' - identifier: varTag.noVariable - count: 1 - path: ../../../src/wp-cron.php - message: '#^PHPDoc tag @var above assignment does not specify variable name\.$#' identifier: varTag.noVariable count: 9 path: ../../../src/wp-includes/class-wp-query.php - - - message: '#^PHPDoc tag @var does not specify variable name\.$#' - identifier: varTag.noVariable - count: 1 - path: ../../../src/wp-includes/kses.php - - - message: '#^PHPDoc tag @var does not specify variable name\.$#' - identifier: varTag.noVariable - count: 2 - path: ../../../src/wp-includes/rest-api.php - - - message: '#^PHPDoc tag @var does not specify variable name\.$#' - identifier: varTag.noVariable - count: 1 - path: ../../../src/xmlrpc.php From a04f71a729ac3cd0e4b04703698555770f9b1b7f Mon Sep 17 00:00:00 2001 From: Mukesh Panchal Date: Wed, 4 Nov 2026 13:47:50 +0530 Subject: [PATCH 2/2] Code Quality: Remove inline `@var` tags above `WP_Query` property assignments. `WP_Query` had nine `/** @var Type */` tags above assignments to `$this->posts`, `$this->post`, `$this->comments` and `$this->comment`. PHPStan reports each one as `varTag.noVariable`. A `@var` tag can only name a local variable, so PHPStan ignores these tags and cannot use them. Naming the property, as in `@var WP_Post[] $this->posts`, makes PHPStan read the type as `$this` and report new errors. The property docblocks already document these types. This change removes the nine tags, deletes the now empty `varTag.noVariable` baseline, and removes its `includes` line from `phpstan.neon.dist`. There is no runtime change. See #65817. Co-Authored-By: Claude Opus 5.5 --- phpstan.neon.dist | 1 - src/wp-includes/class-wp-query.php | 9 ------- .../phpstan/baselines/varTag.noVariable.neon | 25 ------------------- 3 files changed, 35 deletions(-) delete mode 100644 tests/phpstan/baselines/varTag.noVariable.neon diff --git a/phpstan.neon.dist b/phpstan.neon.dist index 655bb9bbc807c..40445fdd271a6 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -54,7 +54,6 @@ includes: - tests/phpstan/baselines/property.private.neon - tests/phpstan/baselines/return.type.neon - tests/phpstan/baselines/return.unusedType.neon - - tests/phpstan/baselines/varTag.noVariable.neon - tests/phpstan/baselines/variable.undefined.neon # phpstan:baselines end diff --git a/src/wp-includes/class-wp-query.php b/src/wp-includes/class-wp-query.php index 88981421ff937..9e3b66f4fe387 100644 --- a/src/wp-includes/class-wp-query.php +++ b/src/wp-includes/class-wp-query.php @@ -2904,7 +2904,6 @@ public function get_posts() { _prime_comment_caches( $comment_ids ); // Convert to WP_Comment. - /** @var WP_Comment[] */ $this->comments = array_map( 'get_comment', $comment_ids ); $this->comment_count = count( $this->comments ); @@ -3310,7 +3309,6 @@ public function get_posts() { return $post_parents; } else { _prime_post_caches( $post_ids, $query_vars['update_post_term_cache'], $query_vars['update_post_meta_cache'] ); - /** @var WP_Post[] */ $this->posts = array_map( 'get_post', $post_ids ); } } @@ -3320,7 +3318,6 @@ public function get_posts() { if ( 'ids' === $query_vars['fields'] ) { $this->posts ??= $wpdb->get_col( $this->request ); - /** @var int[] */ $this->posts = array_map( 'intval', $this->posts ); $this->post_count = count( $this->posts ); $this->set_found_posts( $query_vars, $limits ); @@ -3451,7 +3448,6 @@ public function get_posts() { // Convert to WP_Post objects. if ( $this->posts ) { - /** @var WP_Post[] */ $this->posts = array_map( 'get_post', $this->posts ); } @@ -3571,7 +3567,6 @@ public function get_posts() { _prime_comment_caches( $comment_ids ); // Convert to WP_Comment. - /** @var WP_Comment[] */ $this->comments = array_map( 'get_comment', $comment_ids ); $this->comment_count = count( $this->comments ); } @@ -3645,7 +3640,6 @@ public function get_posts() { if ( $this->posts ) { $this->post_count = count( $this->posts ); - /** @var WP_Post[] */ $this->posts = array_map( 'get_post', $this->posts ); if ( $query_vars['cache_results'] ) { @@ -3657,7 +3651,6 @@ public function get_posts() { } } - /** @var WP_Post */ $this->post = reset( $this->posts ); } else { $this->post_count = 0; @@ -3747,7 +3740,6 @@ public function next_post() { ++$this->current_post; - /** @var WP_Post */ $this->post = $this->posts[ $this->current_post ]; return $this->post; } @@ -3894,7 +3886,6 @@ public function rewind_posts() { public function next_comment() { ++$this->current_comment; - /** @var WP_Comment */ $this->comment = $this->comments[ $this->current_comment ]; return $this->comment; } diff --git a/tests/phpstan/baselines/varTag.noVariable.neon b/tests/phpstan/baselines/varTag.noVariable.neon deleted file mode 100644 index e834bc62d69a9..0000000000000 --- a/tests/phpstan/baselines/varTag.noVariable.neon +++ /dev/null @@ -1,25 +0,0 @@ -# PHPStan baseline for the `varTag.noVariable` errors in WordPress core. -# -# https://phpstan.org/error-identifiers/varTag.noVariable -# -# Each entry is scoped to a single file and carries an exact occurrence count, -# so that a new instance is reported as a new error rather than being absorbed -# silently. Fixing an occurrence therefore means decrementing or removing its -# entry here as part of the same change. -# -# The goal is to empty this file and delete it, along with the `includes` entry -# for it in phpstan.neon.dist. -# -# Generated by `composer phpstan:baselines`. Do not edit by hand; regenerate with -# -# composer phpstan:baselines -- --identifier=varTag.noVariable -# -# which reruns the analysis with this file suppressed so the errors surface again. - -parameters: - ignoreErrors: - - - message: '#^PHPDoc tag @var above assignment does not specify variable name\.$#' - identifier: varTag.noVariable - count: 9 - path: ../../../src/wp-includes/class-wp-query.php