Changeset 62822 for trunk/src/wp-includes/class-wp-comment-query.php

Timestamp:

07/22/2026 04:52:41 AM (5 weeks ago)

Author:

westonruter

Message:

Code Quality: Improve comment API type coverage.

Add a Data_Array array-shape type describing the keys returned by WP_Comment::to_array(), and narrow the properties it covers: comment_approved and the two datetime fields become non-empty-string, and the values core uses for it and for comment_type are documented. comment_type itself stays a plain string, because comments created before 5.5.0 may store an empty string rather than 'comment', which is why get_comment_type() normalizes that case on read.

Declare the 21 post fields that WP_Comment::__get() proxies to the comment's post as @property-read, typed to match the corresponding WP_Post property. These were previously invisible to static analysis, IDE completion, and the generated documentation. Also correct WP_Comment::$children, previously a bare array, which is null until get_children() populates it, and type the comment arrays keyed by comment ID as array<int, WP_Comment>, since PHP coerces the numeric string comment_ID to an integer key on assignment.

Add conditional return types to WP_Comment::get_children(), get_comment(), get_comments(), and get_approved_comments(), and document every argument ::get_children() actually accepts, several of which were already in use but undocumented. Comment ID arrays are narrowed to non-negative-int[], and WP_Comment_Query::$comments is typed as null until a query is run.

Several latent issues surfaced by the analysis are fixed:

• WP_Comment::get_children() now returns a count or fields query directly rather than storing it in the children cache. That cache holds WP_Comment objects and is read back by add_child(), get_child(), and the 'flat' format, so writing an integer or a list of IDs into it left the object returning the wrong thing on a subsequent call.
• get_comment() now hands only numeric values to WP_Comment::get_instance(). Previously anything that was not a WP_Comment or some other object fell through to be cast to an integer ID, even if it wasn't numeric. Now null is returned in such cases.
• WP_Comment::get_instance() ignores a non-object read from the comment cache rather than passing it to the WP_Comment constructor, where get_object_vars() would raise a TypeError.
• WP_Comment::__isset() returns false, and WP_Comment::__get() returns null, when the comment's post no longer exists, instead of raising a TypeError and a warning respectively. __get() also returns null when the comment is not attached to a post at all; previously get_post( 0 ) fell back to the global $post, so the getter returned an unrelated post's field even though __isset() reported that same property as unset.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12606.
Follow-up to r34583, r62648, r62694, r62717.

Props westonruter, adamsilverstein.
See #64898.

File:

• trunk/src/wp-includes/class-wp-comment-query.php (modified) (6 diffs)

trunk/src/wp-includes/class-wp-comment-query.php

@@ -94 +94 @@
          * List of comments located by the query.
          *
+         * Null until a query has been run.
+         *
          * @since 4.0.0
-         * @var int[]|WP_Comment[]
+         * @var int[]|WP_Comment[]|null
+         * @phpstan-var non-negative-int[]|array<int, WP_Comment>|null
          */
         public $comments;
@@ -104 +107 @@
          * @since 4.4.0
          * @var int
+         * @phpstan-var non-negative-int
          */
         public $found_comments = 0;
@@ -112 +116 @@
          * @since 4.4.0
          * @var int
+         * @phpstan-var non-negative-int
          */
         public $max_num_pages = 0;
@@ -360 +365 @@
          *
          * @param string|array $query Array or URL query string of parameters.
-         * @return array|int List of comments, or number of comments when 'count' is passed as a query var.
+         * @return WP_Comment[]|int[]|int List of comments, or number of comments when 'count' is passed as a query var.
+         * @phpstan-return array<int, WP_Comment>|non-negative-int[]|non-negative-int
          */
         public function query( $query ) {
@@ -375 +381 @@
          *
          * @return int|int[]|WP_Comment[] List of comments or number of found comments if `$count` argument is true.
+         * @phpstan-return array<int, WP_Comment>|non-negative-int[]|non-negative-int
          */
         public function get_comments() {
@@ -542 +549 @@
          *
          * @return int|array A single count of comment IDs if a count query. An array of comment IDs if a full query.
+         * @phpstan-return non-negative-int|list<non-negative-int>
          */
         protected function get_comment_ids() {