Commit 71f3b07848 for wordpress.org
commit 71f3b07848b3cc274b29f38a864dbdb52058db49
Author: westonruter <westonruter@git.wordpress.org>
Date: Tue Oct 27 03:23:56 2026 +0000
Docs: Add class-level PHPStan annotations.
Members that `WP_Theme` and `WP_Query` serve through their magic methods were unknown to static analysis, so every access to one was reported as an undefined or private property and recorded in the PHPStan baselines. These are now declared at the class level: the `WP_Theme` properties with `@property-read`, since they are public back-compat API that belongs in the developer docs, and the private `WP_Query` members that its `$compat_fields` and `$compat_methods` expose with PHPStan-only tags. Where a `WP_Theme` property comes from a method that can return `false`, its type includes `false`, which surfaces a few existing cases in `WP_Debug_Data` that pass such a value on as a string.
`WP_Block_List` declares the key and value types of the `Iterator` and `ArrayAccess` interfaces it implements, so that iterating over or indexing a block list yields `WP_Block` instances. The `WP_Widget::update_callback()` and `WP_Widget::form_callback()` methods are marked `@final`, as their documentation already says not to override them. The same note on `WP_Widget::display_callback()` is not enforced, since at least one popular plugin overrides it.
The annotations are adopted from the function map of the php-stubs/wordpress-stubs package.
Developed in https://github.com/WordPress/wordpress-develop/pull/13891.
Follow-up to r31151, r48159, r63020.
Props swissspidy, marian1, westonruter.
See #65817.
Built from https://develop.svn.wordpress.org/trunk@64794
git-svn-id: http://core.svn.wordpress.org/trunk@63944 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-includes/class-wp-block-list.php b/wp-includes/class-wp-block-list.php
index b56b3bd69d..3d577f5656 100644
--- a/wp-includes/class-wp-block-list.php
+++ b/wp-includes/class-wp-block-list.php
@@ -10,6 +10,9 @@
* Class representing a list of block instances.
*
* @since 5.5.0
+ *
+ * @phpstan-implements Iterator<int, WP_Block>
+ * @phpstan-implements ArrayAccess<int, WP_Block>
*/
#[AllowDynamicProperties]
class WP_Block_List implements Iterator, ArrayAccess, Countable {
@@ -105,7 +108,7 @@ class WP_Block_List implements Iterator, ArrayAccess, Countable {
*
* @link https://www.php.net/manual/en/arrayaccess.offsetset.php
*
- * @param int $offset Offset of block value to set.
+ * @param int|null $offset Offset of block value to set, or null to append.
* @param array|WP_Block $value Block value.
*/
#[ReturnTypeWillChange]
diff --git a/wp-includes/class-wp-query.php b/wp-includes/class-wp-query.php
index 01848af60e..88981421ff 100644
--- a/wp-includes/class-wp-query.php
+++ b/wp-includes/class-wp-query.php
@@ -14,6 +14,10 @@
*
* @since 1.5.0
* @since 4.5.0 Removed the `$comments_popup` property.
+ *
+ * @phpstan-property-read bool $query_vars_changed
+ * @phpstan-property-read false|(lowercase-string&non-falsy-string) $query_vars_hash
+ * @phpstan-method void init_query_flags()
*/
#[AllowDynamicProperties]
class WP_Query {
@@ -451,6 +455,7 @@ class WP_Query {
*
* @since 3.1.0
* @var bool|string
+ * @phpstan-var false|(lowercase-string&non-falsy-string)
*/
private $query_vars_hash = false;
diff --git a/wp-includes/class-wp-theme.php b/wp-includes/class-wp-theme.php
index 2d89320e83..109cfa8cdb 100644
--- a/wp-includes/class-wp-theme.php
+++ b/wp-includes/class-wp-theme.php
@@ -6,6 +6,21 @@
* @subpackage Theme
* @since 3.4.0
*
+ * @property-read string|false $name
+ * @property-read string|false $title
+ * @property-read string|false $version
+ * @property-read string|false $parent_theme
+ * @property-read string $template_dir
+ * @property-read string $stylesheet_dir
+ * @property-read string $template
+ * @property-read string $stylesheet
+ * @property-read string|false $screenshot
+ * @property-read string|false $description
+ * @property-read string|false $author
+ * @property-read string[]|false $tags
+ * @property-read string $theme_root
+ * @property-read string $theme_root_uri
+ *
* @phpstan-type Theme_Key 'Name'|'Version'|'Status'|'Title'|'Author'|'Author Name'|'Author URI'|'Description'|'Template'|'Stylesheet'|'Template Files'|'Stylesheet Files'|'Template Dir'|'Stylesheet Dir'|'Screenshot'|'Tags'|'Theme Root'|'Theme Root URI'|'Parent Theme'
*/
#[AllowDynamicProperties]
diff --git a/wp-includes/class-wp-widget.php b/wp-includes/class-wp-widget.php
index 7a1a8ae51d..f1d432c0d3 100644
--- a/wp-includes/class-wp-widget.php
+++ b/wp-includes/class-wp-widget.php
@@ -412,6 +412,8 @@ class WP_Widget {
* @global array $wp_registered_widgets
*
* @param int $deprecated Not used.
+ *
+ * @final
*/
public function update_callback( $deprecated = 1 ) {
global $wp_registered_widgets;
@@ -504,6 +506,8 @@ class WP_Widget {
* @type int $number Number increment used for multiples of the same widget.
* }
* @return string|null
+ *
+ * @final
*/
public function form_callback( $widget_args = 1 ) {
if ( is_numeric( $widget_args ) ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index d7007ae602..da001de5ee 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.2-beta1-64793';
+$wp_version = '7.2-beta1-64794';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.