diff --git a/src/wp-includes/class-wp-comment-query.php b/src/wp-includes/class-wp-comment-query.php index cfabfd7e6b964..f80864d31c8bc 100644 --- a/src/wp-includes/class-wp-comment-query.php +++ b/src/wp-includes/class-wp-comment-query.php @@ -93,8 +93,11 @@ class WP_Comment_Query { /** * 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|null */ public $comments; @@ -103,6 +106,7 @@ class WP_Comment_Query { * * @since 4.4.0 * @var int + * @phpstan-var non-negative-int */ public $found_comments = 0; @@ -111,6 +115,7 @@ class WP_Comment_Query { * * @since 4.4.0 * @var int + * @phpstan-var non-negative-int */ public $max_num_pages = 0; @@ -359,7 +364,8 @@ public function parse_query( $query = '' ) { * @since 4.2.0 Moved parsing to WP_Comment_Query::parse_query(). * * @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|non-negative-int[]|non-negative-int */ public function query( $query ) { $this->query_vars = wp_parse_args( $query ); @@ -374,6 +380,7 @@ public function query( $query ) { * @global wpdb $wpdb WordPress database abstraction object. * * @return int|int[]|WP_Comment[] List of comments or number of found comments if `$count` argument is true. + * @phpstan-return array|non-negative-int[]|non-negative-int */ public function get_comments() { global $wpdb; @@ -541,6 +548,7 @@ public function get_comments() { * @global wpdb $wpdb WordPress database abstraction object. * * @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 */ protected function get_comment_ids() { global $wpdb; diff --git a/src/wp-includes/class-wp-comment.php b/src/wp-includes/class-wp-comment.php index b1beea1e34883..f6b4d8d75f5e3 100644 --- a/src/wp-includes/class-wp-comment.php +++ b/src/wp-includes/class-wp-comment.php @@ -10,7 +10,52 @@ /** * Core class used to organize comments as instantiated objects with defined members. * + * The `@property-read` fields below are not stored on the comment. They are proxied to the + * comment's post by {@see WP_Comment::__get()}, and are null when the comment is not attached + * to a post or when that post no longer exists. + * * @since 4.4.0 + * + * @property-read numeric-string|''|null $post_author + * @property-read string|null $post_date + * @property-read string|null $post_date_gmt + * @property-read string|null $post_content + * @property-read string|null $post_title + * @property-read string|null $post_excerpt + * @property-read non-empty-string|null $post_status + * @property-read non-empty-string|null $comment_status + * @property-read non-empty-string|null $ping_status + * @property-read string|null $post_name + * @property-read string|null $to_ping + * @property-read string|null $pinged + * @property-read string|null $post_modified + * @property-read string|null $post_modified_gmt + * @property-read string|null $post_content_filtered + * @property-read non-negative-int|null $post_parent + * @property-read string|null $guid + * @property-read int|null $menu_order + * @property-read non-empty-string|null $post_type + * @property-read string|null $post_mime_type + * @property-read numeric-string|null $comment_count + * + * @phpstan-type Data_Array array{ + * comment_ID: numeric-string, + * comment_post_ID: numeric-string, + * comment_author: string, + * comment_author_email: string, + * comment_author_url: string, + * comment_author_IP: string, + * comment_date: non-empty-string, + * comment_date_gmt: non-empty-string, + * comment_content: string, + * comment_karma: numeric-string, + * comment_approved: non-empty-string, + * comment_agent: string, + * comment_type: string, + * comment_parent: numeric-string, + * user_id: numeric-string, + * ... + * } */ #[AllowDynamicProperties] final class WP_Comment { @@ -74,6 +119,7 @@ final class WP_Comment { * * @since 4.4.0 * @var string + * @phpstan-var non-empty-string */ public $comment_date = '0000-00-00 00:00:00'; @@ -82,6 +128,7 @@ final class WP_Comment { * * @since 4.4.0 * @var string + * @phpstan-var non-empty-string */ public $comment_date_gmt = '0000-00-00 00:00:00'; @@ -107,8 +154,12 @@ final class WP_Comment { /** * Comment approval status. * + * The values used in core are '0' (unapproved), '1' (approved), 'spam', 'trash', + * and 'post-trashed' (set for every comment on a post that is moved to the trash). + * * @since 4.4.0 * @var string + * @phpstan-var non-empty-string */ public $comment_approved = '1'; @@ -123,6 +174,13 @@ final class WP_Comment { /** * Comment type. * + * The values used in core are 'comment', 'pingback', 'trackback', and 'note'. Custom + * comment types are possible. + * + * Comments created before 5.5.0 may store an empty string rather than 'comment', so this + * cannot be relied upon to be non-empty. {@see get_comment_type()} normalizes that case + * when reading. + * * @since 4.4.0 * @since 5.5.0 Default value changed to `comment`. * @var string @@ -154,8 +212,16 @@ final class WP_Comment { /** * Comment children. * + * Mapping of comment ID to WP_Comment object, as populated by the default + * `hierarchical => 'threaded'` argument of get_children(). Note that if a + * caller passes a `hierarchical` value of 'flat' or `false` to + * get_children(), a sequentially-keyed array of WP_Comment objects (also + * including all descendants, in the 'flat' case) is stored here instead. + * + * Null until populated by {@see WP_Comment::get_children()}. + * * @since 4.4.0 - * @var array + * @var array|null */ protected $children; @@ -171,7 +237,8 @@ final class WP_Comment { * Post fields. * * @since 4.4.0 - * @var array + * @var string[] + * @phpstan-var list */ protected $post_fields = array( 'post_author', 'post_date', 'post_date_gmt', 'post_content', 'post_title', 'post_excerpt', 'post_status', 'comment_status', 'ping_status', 'post_name', 'to_ping', 'pinged', 'post_modified', 'post_modified_gmt', 'post_content_filtered', 'post_parent', 'guid', 'menu_order', 'post_type', 'post_mime_type', 'comment_count' ); @@ -183,6 +250,7 @@ final class WP_Comment { * @global wpdb $wpdb WordPress database abstraction object. * * @param int $id Comment ID. + * @phpstan-param int|numeric-string $id * @return WP_Comment|false Comment object, otherwise false. */ public static function get_instance( $id ) { @@ -195,7 +263,8 @@ public static function get_instance( $id ) { $_comment = wp_cache_get( $comment_id, 'comment' ); - if ( ! $_comment ) { + if ( ! is_object( $_comment ) ) { + /** @var object{ comment_ID: string, comment_post_ID: string, comment_author: string, comment_author_email: string, comment_author_url: string, comment_author_IP: string, comment_date: string, comment_date_gmt: string, comment_content: string, comment_karma: string, comment_approved: string, comment_agent: string, comment_type: string, comment_parent: string, user_id: string }|null $_comment */ $_comment = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_ID = %d LIMIT 1", $comment_id ) ); if ( ! $_comment ) { @@ -228,19 +297,28 @@ public function __construct( $comment ) { * * @since 4.4.0 * - * @return array Object as array. + * @return array Object as array. + * @phpstan-return Data_Array */ - public function to_array() { - return get_object_vars( $this ); + public function to_array(): array { + /** @var Data_Array $comment */ + $comment = get_object_vars( $this ); + return $comment; } /** * Gets the children of a comment. * * @since 4.4.0 + * @since 7.1.0 A `count` or `fields` query now returns its result directly rather than + * erroneously storing it in the comment's children cache. * * @param array $args { - * Array of arguments used to pass to get_comments() and determine format. + * Array of arguments used to pass to {@see get_comments()} and determine format. + * Any other argument accepted by {@see WP_Comment_Query::__construct()} may also be passed, and is + * forwarded to `get_comments()`. Note that `parent` is always overridden with this comment's ID. + * A `$count` or `$fields` query returns the direct children only, and does not populate the + * comment's cached children, since that cache holds `WP_Comment` objects. * * @type string $format Return value format. 'tree' for a hierarchical tree, 'flat' for a flattened array. * Default 'tree'. @@ -267,8 +345,42 @@ public function to_array() { * the value of $meta_key, and the array keys of * `$meta_query`. Also accepts false, an empty array, or * 'none' to disable `ORDER BY` clause. + * @type string $fields Which fields to return. Accepts 'ids' for comment IDs, or an + * empty string for full `WP_Comment` objects. Default empty. + * @type bool $count Whether to return a comment count rather than comments. + * Default false. + * @type string $type Limit results to comments of a given type, such as 'comment', + * 'pingback', 'trackback', or 'note'. Accepts 'all' for every + * type. Default empty. + * @type int $number Maximum number of comments to retrieve. Default empty (no limit). + * @type int $post_id Limit results to comments on a given post. Default 0. + * @type string $order How to order retrieved comments. Accepts 'ASC' or 'DESC'. + * Default 'DESC'. * } - * @return WP_Comment[] Array of `WP_Comment` objects. + * @return WP_Comment[]|int[]|int Array of `WP_Comment` objects, an array of comment IDs when + * `$fields` is 'ids', or the number of children when `$count` + * is true. + * + * @phpstan-param array{ + * format?: 'tree'|'flat', + * status?: 'hold'|'approve'|'all'|string, + * hierarchical?: 'threaded'|'flat'|false, + * orderby?: string|string[]|false, + * fields?: 'ids'|'', + * count?: bool, + * type?: string, + * number?: int, + * post_id?: int, + * order?: 'ASC'|'DESC', + * ... + * } $args + * @phpstan-return ( + * $args is array{ count: true, ... } ? non-negative-int : ( + * $args is array{ fields: 'ids', ... } ? non-negative-int[] : ( + * $args is array{ format: 'flat', ... } ? list : array + * ) + * ) + * ) */ public function get_children( $args = array() ) { $defaults = array( @@ -278,9 +390,29 @@ public function get_children( $args = array() ) { 'orderby' => '', ); + /** @var array{ format: 'tree'|'flat', status: string, hierarchical: 'threaded'|'flat'|false, orderby: string|string[]|false, fields?: 'ids'|'', count?: bool, type?: string, number?: int, post_id?: int, order?: 'ASC'|'DESC', ... } $_args */ $_args = wp_parse_args( $args, $defaults ); $_args['parent'] = $this->comment_ID; + /* + * A 'count' or 'ids' query returns an integer or a list of comment IDs rather than + * WP_Comment objects. Neither may be written to the children cache, which holds + * WP_Comment objects and is read back by add_child(), get_child(), and the 'flat' + * format below. Return the result directly and leave the cache untouched. The two + * branches must stay separate: each is narrowed independently, and `count` is only + * safe to overwrite in the 'ids' branch. + */ + if ( ! empty( $_args['count'] ) ) { + return get_comments( $_args ); + } elseif ( isset( $_args['fields'] ) && 'ids' === $_args['fields'] ) { + $_args['count'] = false; // For static analysis of the conditional return type. + return get_comments( $_args ); + } + + // Only WP_Comment objects are returned past this point. Stated positively for static analysis. + $_args['count'] = false; + $_args['fields'] = ''; + if ( is_null( $this->children ) ) { if ( $this->populated_children ) { $this->children = array(); @@ -315,8 +447,8 @@ public function get_children( $args = array() ) { * * @param WP_Comment $child Child comment. */ - public function add_child( WP_Comment $child ) { - $this->children[ $child->comment_ID ] = $child; + public function add_child( WP_Comment $child ): void { + $this->children[ (int) $child->comment_ID ] = $child; } /** @@ -341,7 +473,7 @@ public function get_child( $child_id ) { * * @param bool $set Whether the comment's children have already been populated. */ - public function populated_children( $set ) { + public function populated_children( $set ): void { $this->populated_children = (bool) $set; } @@ -351,14 +483,15 @@ public function populated_children( $set ) { * If `$name` matches a post field, the comment post will be loaded and the post's value checked. * * @since 4.4.0 + * @since 7.1.0 Returns false instead of causing a fatal error when the comment's post cannot be found. * * @param string $name Property to check if set. * @return bool Whether the property is set. */ public function __isset( $name ) { if ( in_array( $name, $this->post_fields, true ) && 0 !== (int) $this->comment_post_ID ) { - $post = get_post( $this->comment_post_ID ); - return property_exists( $post, $name ); + $post = get_post( (int) $this->comment_post_ID ); + return $post && property_exists( $post, $name ); } return false; @@ -370,14 +503,20 @@ public function __isset( $name ) { * If `$name` matches a post field, the comment post will be loaded and the post's value returned. * * @since 4.4.0 + * @since 7.1.0 Returns null instead of the global post's field when the comment is not attached to + * a post, and no longer raises a warning when the comment's post cannot be found. * * @param string $name Property name. * @return mixed */ public function __get( $name ) { - if ( in_array( $name, $this->post_fields, true ) ) { - $post = get_post( $this->comment_post_ID ); + if ( in_array( $name, $this->post_fields, true ) && 0 !== (int) $this->comment_post_ID ) { + $post = get_post( (int) $this->comment_post_ID ); + if ( ! $post ) { + return null; + } return $post->$name; } + return null; } } diff --git a/src/wp-includes/comment.php b/src/wp-includes/comment.php index 20303dc1e7e17..489bf9415600f 100644 --- a/src/wp-includes/comment.php +++ b/src/wp-includes/comment.php @@ -183,7 +183,15 @@ function check_comment( $author, $email, $url, $comment, $user_ip, $user_agent, * @type string $order How to order retrieved comments. Default 'ASC'. * } * @return WP_Comment[]|int[]|int The approved comments, or number of comments if `$count` - * argument is true. + * argument is true. An empty array is returned when `$post_id` + * is falsey, even when `$count` is true. + * @phpstan-return ( + * $post_id is 0 ? array{} : ( + * $args is array{ count: true, ... } ? non-negative-int : ( + * $args is array{ fields: 'ids', ... } ? non-negative-int[] : array + * ) + * ) + * ) */ function get_approved_comments( $post_id, $args = array() ) { if ( ! $post_id ) { @@ -209,6 +217,8 @@ function get_approved_comments( $post_id, $args = array() ) { * comment variable will be used, if it is set. * * @since 2.0.0 + * @since 7.1.0 Only numeric values are now treated as comment IDs; other unrecognized values + * return null instead of being cast to an integer ID. * * @global WP_Comment $comment Global comment object. * @@ -217,6 +227,12 @@ function get_approved_comments( $post_id, $args = array() ) { * correspond to a WP_Comment object, an associative array, or a numeric array, * respectively. Default OBJECT. * @return WP_Comment|array|null Depends on $output value. + * @phpstan-param 'OBJECT'|'ARRAY_A'|'ARRAY_N' $output + * @phpstan-return ( + * $output is 'ARRAY_A' ? non-empty-array|null : ( + * $output is 'ARRAY_N' ? non-empty-list|null : WP_Comment|null + * ) + * ) */ function get_comment( $comment = null, $output = OBJECT ) { if ( empty( $comment ) && isset( $GLOBALS['comment'] ) ) { @@ -227,8 +243,10 @@ function get_comment( $comment = null, $output = OBJECT ) { $_comment = $comment; } elseif ( is_object( $comment ) ) { $_comment = new WP_Comment( $comment ); + } elseif ( is_numeric( $comment ) ) { + $_comment = WP_Comment::get_instance( (int) $comment ); } else { - $_comment = WP_Comment::get_instance( $comment ); + $_comment = null; } if ( ! $_comment ) { @@ -267,6 +285,11 @@ function get_comment( $comment = null, $output = OBJECT ) { * @param string|array $args Optional. Array or string of arguments. See WP_Comment_Query::__construct() * for information on accepted arguments. Default empty string. * @return WP_Comment[]|int[]|int List of comments or number of found comments if `$count` argument is true. + * @phpstan-return ( + * $args is array{ count: true, ... } ? non-negative-int : ( + * $args is array{ fields: 'ids', ... } ? non-negative-int[] : array + * ) + * ) */ function get_comments( $args = '' ) { $query = new WP_Comment_Query(); @@ -519,6 +542,7 @@ function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) { * - true values are returned as '1' * - numbers are returned as strings * Arrays and objects retain their original type. + * @phpstan-param int|numeric-string $comment_id */ function get_comment_meta( $comment_id, $key = '', $single = false ) { return get_metadata( 'comment', $comment_id, $key, $single ); diff --git a/tests/phpunit/tests/comment.php b/tests/phpunit/tests/comment.php index 11e78140f1020..c84279e4f1835 100644 --- a/tests/phpunit/tests/comment.php +++ b/tests/phpunit/tests/comment.php @@ -1912,4 +1912,21 @@ public function test_get_comment_filter() { add_filter( 'get_comment', '__return_null' ); $this->assertNull( get_comment( $comment_id ), 'Expected get_comment() to return null when get_comment filter returns null.' ); } + + /** + * @ticket 64898 + * + * @covers ::get_comment + */ + public function test_get_comment_should_only_treat_numeric_values_as_comment_ids(): void { + $comment_id = self::factory()->comment->create( array( 'comment_post_ID' => self::$post_id ) ); + $this->assertIsInt( $comment_id ); + + $comment = get_comment( (string) $comment_id ); + $this->assertInstanceOf( WP_Comment::class, $comment, 'Expected a numeric string to be treated as a comment ID.' ); + $this->assertSame( (string) $comment_id, $comment->comment_ID, 'Expected the same comment.' ); + + $this->assertNull( get_comment( $comment_id . 'abc' ), 'Expected a malformed numeric string not to be cast to a comment ID.' ); + $this->assertNull( get_comment( true ), 'Expected true not to be cast to comment ID 1.' ); // @phpstan-ignore argument.type (Intentionally passing an invalid value.) + } } diff --git a/tests/phpunit/tests/comment/wpComment.php b/tests/phpunit/tests/comment/wpComment.php index 83a8bc8d0f1eb..1f8688d3aeaf9 100644 --- a/tests/phpunit/tests/comment/wpComment.php +++ b/tests/phpunit/tests/comment/wpComment.php @@ -62,4 +62,117 @@ public function test_get_instance_should_succeed_for_float_that_is_equal_to_post $this->assertSame( '1', $found->comment_ID ); } + + /** + * @ticket 64898 + * + * @covers WP_Comment::get_children + */ + public function test_get_children_should_return_count_without_storing_it_in_the_children_cache(): void { + $post_id = self::factory()->post->create(); + $parent = self::factory()->comment->create( array( 'comment_post_ID' => $post_id ) ); + $children = self::factory()->comment->create_many( + 2, + array( + 'comment_post_ID' => $post_id, + 'comment_parent' => $parent, + ) + ); + + $this->assertIsInt( $parent ); + $comment = get_comment( $parent ); + $this->assertInstanceOf( WP_Comment::class, $comment ); + + $count = $comment->get_children( array( 'count' => true ) ); + $this->assertSame( 2, $count, 'Expected the number of direct children.' ); + + $found = $comment->get_children(); + $this->assertContainsOnlyInstancesOf( 'WP_Comment', $found, 'Expected WP_Comment objects from a subsequent default query.' ); + + $found_ids = array(); + foreach ( $found as $child ) { + $found_ids[] = (int) $child->comment_ID; + } + $this->assertSameSets( $children, $found_ids, 'Expected the children cache to be unaffected by the count query.' ); + } + + /** + * @ticket 64898 + * + * @covers WP_Comment::get_children + */ + public function test_get_children_should_return_ids_without_storing_them_in_the_children_cache(): void { + $post_id = self::factory()->post->create(); + $parent = self::factory()->comment->create( array( 'comment_post_ID' => $post_id ) ); + $children = self::factory()->comment->create_many( + 2, + array( + 'comment_post_ID' => $post_id, + 'comment_parent' => $parent, + ) + ); + + $this->assertIsInt( $parent ); + $comment = get_comment( $parent ); + $this->assertInstanceOf( WP_Comment::class, $comment ); + + $ids = $comment->get_children( array( 'fields' => 'ids' ) ); + $this->assertSameSets( $children, $ids, 'Expected the IDs of the direct children.' ); + + $found = $comment->get_children(); + $this->assertContainsOnlyInstancesOf( 'WP_Comment', $found, 'Expected WP_Comment objects from a subsequent default query.' ); + + $found_ids = array(); + foreach ( $found as $child ) { + $found_ids[] = (int) $child->comment_ID; + } + $this->assertSameSets( $children, $found_ids, 'Expected the children cache to be unaffected by the IDs query.' ); + } + + /** + * @ticket 64898 + * + * @covers WP_Comment::__isset + * @covers WP_Comment::__get + */ + public function test_post_fields_should_be_null_when_the_comments_post_is_deleted(): void { + $post_id = self::factory()->post->create(); + $comment_id = self::factory()->comment->create( array( 'comment_post_ID' => $post_id ) ); + + $this->assertIsInt( $post_id ); + $this->assertIsInt( $comment_id ); + $comment = get_comment( $comment_id ); + $this->assertInstanceOf( WP_Comment::class, $comment ); + + wp_delete_post( $post_id, true ); + + $this->assertFalse( isset( $comment->post_title ), 'Expected __isset() to return false when the post is deleted.' ); + $this->assertNull( $comment->post_title, 'Expected __get() to return null when the post is deleted.' ); + } + + /** + * @ticket 64898 + * + * @covers WP_Comment::__isset + * @covers WP_Comment::__get + */ + public function test_post_fields_should_be_null_for_an_unattached_comment(): void { + $post_id = self::factory()->post->create(); + $comment_id = self::factory()->comment->create( array( 'comment_post_ID' => 0 ) ); + + $this->assertIsInt( $post_id ); + $this->assertIsInt( $comment_id ); + $comment = get_comment( $comment_id ); + $this->assertInstanceOf( WP_Comment::class, $comment ); + + $GLOBALS['post'] = get_post( $post_id ); + + $is_set = isset( $comment->post_title ); + $title = $comment->post_title; + + unset( $GLOBALS['post'] ); + + $this->assertFalse( $is_set, 'Expected __isset() to return false for an unattached comment.' ); + $this->assertNull( $title, 'Expected __get() not to read the field from the global post.' ); + } }