| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Comment API: WP_Comment class 4 * 5 * @package WordPress 6 * @subpackage Comments 7 * @since 4.4.0 8 */ 9 10 /** 11 * Core class used to organize comments as instantiated objects with defined members. 12 * 13 * The `@property-read` fields below are not stored on the comment. They are proxied to the 14 * comment's post by {@see WP_Comment::__get()}, and are null when the comment is not attached 15 * to a post or when that post no longer exists. 16 * 17 * @since 4.4.0 18 * 19 * @property-read numeric-string|''|null $post_author 20 * @property-read string|null $post_date 21 * @property-read string|null $post_date_gmt 22 * @property-read string|null $post_content 23 * @property-read string|null $post_title 24 * @property-read string|null $post_excerpt 25 * @property-read non-empty-string|null $post_status 26 * @property-read non-empty-string|null $comment_status 27 * @property-read non-empty-string|null $ping_status 28 * @property-read string|null $post_name 29 * @property-read string|null $to_ping 30 * @property-read string|null $pinged 31 * @property-read string|null $post_modified 32 * @property-read string|null $post_modified_gmt 33 * @property-read string|null $post_content_filtered 34 * @property-read non-negative-int|null $post_parent 35 * @property-read string|null $guid 36 * @property-read int|null $menu_order 37 * @property-read non-empty-string|null $post_type 38 * @property-read string|null $post_mime_type 39 * @property-read numeric-string|null $comment_count 40 * 41 * @phpstan-type Data_Array array{ 42 * comment_ID: numeric-string, 43 * comment_post_ID: numeric-string, 44 * comment_author: string, 45 * comment_author_email: string, 46 * comment_author_url: string, 47 * comment_author_IP: string, 48 * comment_date: non-empty-string, 49 * comment_date_gmt: non-empty-string, 50 * comment_content: string, 51 * comment_karma: numeric-string, 52 * comment_approved: non-empty-string, 53 * comment_agent: string, 54 * comment_type: string, 55 * comment_parent: numeric-string, 56 * user_id: numeric-string, 57 * ... 58 * } 59 */ 60 #[AllowDynamicProperties] 61 final class WP_Comment { 62 63 /** 64 * Comment ID. 65 * 66 * A numeric string, for compatibility reasons. 67 * 68 * @since 4.4.0 69 * @var string 70 * @phpstan-var numeric-string 71 */ 72 public $comment_ID; 73 74 /** 75 * ID of the post the comment is associated with. 76 * 77 * A numeric string, for compatibility reasons. 78 * 79 * @since 4.4.0 80 * @var string 81 * @phpstan-var numeric-string 82 */ 83 public $comment_post_ID = '0'; 84 85 /** 86 * Comment author name. 87 * 88 * @since 4.4.0 89 * @var string 90 */ 91 public $comment_author = ''; 92 93 /** 94 * Comment author email address. 95 * 96 * @since 4.4.0 97 * @var string 98 */ 99 public $comment_author_email = ''; 100 101 /** 102 * Comment author URL. 103 * 104 * @since 4.4.0 105 * @var string 106 */ 107 public $comment_author_url = ''; 108 109 /** 110 * Comment author IP address (IPv4 format). 111 * 112 * @since 4.4.0 113 * @var string 114 */ 115 public $comment_author_IP = ''; 116 117 /** 118 * Comment date in YYYY-MM-DD HH:MM:SS format. 119 * 120 * @since 4.4.0 121 * @var string 122 * @phpstan-var non-empty-string 123 */ 124 public $comment_date = '0000-00-00 00:00:00'; 125 126 /** 127 * Comment GMT date in YYYY-MM-DD HH::MM:SS format. 128 * 129 * @since 4.4.0 130 * @var string 131 * @phpstan-var non-empty-string 132 */ 133 public $comment_date_gmt = '0000-00-00 00:00:00'; 134 135 /** 136 * Comment content. 137 * 138 * @since 4.4.0 139 * @var string 140 */ 141 public $comment_content; 142 143 /** 144 * Comment karma count. 145 * 146 * A numeric string, for compatibility reasons. 147 * 148 * @since 4.4.0 149 * @var string 150 * @phpstan-var numeric-string 151 */ 152 public $comment_karma = '0'; 153 154 /** 155 * Comment approval status. 156 * 157 * The values used in core are '0' (unapproved), '1' (approved), 'spam', 'trash', 158 * and 'post-trashed' (set for every comment on a post that is moved to the trash). 159 * 160 * @since 4.4.0 161 * @var string 162 * @phpstan-var non-empty-string 163 */ 164 public $comment_approved = '1'; 165 166 /** 167 * Comment author HTTP user agent. 168 * 169 * @since 4.4.0 170 * @var string 171 */ 172 public $comment_agent = ''; 173 174 /** 175 * Comment type. 176 * 177 * The values used in core are 'comment', 'pingback', 'trackback', and 'note'. Custom 178 * comment types are possible. 179 * 180 * Comments created before 5.5.0 may store an empty string rather than 'comment', so this 181 * cannot be relied upon to be non-empty. {@see get_comment_type()} normalizes that case 182 * when reading. 183 * 184 * @since 4.4.0 185 * @since 5.5.0 Default value changed to `comment`. 186 * @var string 187 */ 188 public $comment_type = 'comment'; 189 190 /** 191 * Parent comment ID. 192 * 193 * A numeric string, for compatibility reasons. 194 * 195 * @since 4.4.0 196 * @var string 197 * @phpstan-var numeric-string 198 */ 199 public $comment_parent = '0'; 200 201 /** 202 * Comment author ID. 203 * 204 * A numeric string, for compatibility reasons. 205 * 206 * @since 4.4.0 207 * @var string 208 * @phpstan-var numeric-string 209 */ 210 public $user_id = '0'; 211 212 /** 213 * Comment children. 214 * 215 * Mapping of comment ID to WP_Comment object, as populated by the default 216 * `hierarchical => 'threaded'` argument of get_children(). Note that if a 217 * caller passes a `hierarchical` value of 'flat' or `false` to 218 * get_children(), a sequentially-keyed array of WP_Comment objects (also 219 * including all descendants, in the 'flat' case) is stored here instead. 220 * 221 * Null until populated by {@see WP_Comment::get_children()}. 222 * 223 * @since 4.4.0 224 * @var array<int, WP_Comment>|null 225 */ 226 protected $children; 227 228 /** 229 * Whether children have been populated for this comment object. 230 * 231 * @since 4.4.0 232 * @var bool 233 */ 234 protected $populated_children = false; 235 236 /** 237 * Post fields. 238 * 239 * @since 4.4.0 240 * @var string[] 241 * @phpstan-var list<non-empty-string> 242 */ 243 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' ); 244 245 /** 246 * Retrieves a WP_Comment instance. 247 * 248 * @since 4.4.0 249 * @since 7.2.0 Cache values that are not usable as a comment object are now treated as a cache miss and replaced. 250 * 251 * @global wpdb $wpdb WordPress database abstraction object. 252 * 253 * @param int $id Comment ID. 254 * @phpstan-param int|numeric-string $id 255 * @return WP_Comment|false Comment object, otherwise false. 256 */ 257 public static function get_instance( $id ) { 258 global $wpdb; 259 260 $comment_id = (int) $id; 261 if ( ! $comment_id ) { 262 return false; 263 } 264 265 $_comment = wp_cache_get( $comment_id, 'comment' ); 266 267 // A cached value that is not usable as a comment is treated as a cache miss. 268 if ( ! is_object( $_comment ) || ! isset( $_comment->comment_ID ) ) { 269 /** @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 */ 270 $_comment = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_ID = %d LIMIT 1", $comment_id ) ); 271 272 if ( ! $_comment ) { 273 return false; 274 } 275 276 // Not wp_cache_add(), since an unusable cached value may still be present and must be replaced. 277 wp_cache_set( $_comment->comment_ID, $_comment, 'comment' ); 278 } 279 280 return new WP_Comment( $_comment ); 281 } 282 283 /** 284 * Constructor. 285 * 286 * Populates properties with object vars. 287 * 288 * @since 4.4.0 289 * 290 * @param object $comment Comment object. 291 */ 292 public function __construct( $comment ) { 293 foreach ( get_object_vars( $comment ) as $key => $value ) { 294 $this->$key = $value; 295 } 296 } 297 298 /** 299 * Converts object to array. 300 * 301 * @since 4.4.0 302 * 303 * @return array<string, mixed> Object as array. 304 * @phpstan-return Data_Array 305 */ 306 public function to_array(): array { 307 /** @var Data_Array $comment */ 308 $comment = get_object_vars( $this ); 309 return $comment; 310 } 311 312 /** 313 * Gets the children of a comment. 314 * 315 * @since 4.4.0 316 * @since 7.1.0 A `count` or `fields` query now returns its result directly rather than 317 * erroneously storing it in the comment's children cache. 318 * 319 * @param array $args { 320 * Array of arguments used to pass to {@see get_comments()} and determine format. 321 * Any other argument accepted by {@see WP_Comment_Query::__construct()} may also be passed, and is 322 * forwarded to `get_comments()`. Note that `parent` is always overridden with this comment's ID. 323 * A `$count` or `$fields` query returns the direct children only, and does not populate the 324 * comment's cached children, since that cache holds `WP_Comment` objects. 325 * 326 * @type string $format Return value format. 'tree' for a hierarchical tree, 'flat' for a flattened array. 327 * Default 'tree'. 328 * @type string $status Comment status to limit results by. Accepts 'hold' (`comment_status=0`), 329 * 'approve' (`comment_status=1`), 'all', or a custom comment status. 330 * Default 'all'. 331 * @type string $hierarchical Whether to include comment descendants in the results. 332 * 'threaded' returns a tree, with each comment's children 333 * stored in a `children` property on the `WP_Comment` object. 334 * 'flat' returns a flat array of found comments plus their children. 335 * Pass `false` to leave out descendants. 336 * The parameter is ignored (forced to `false`) when `$fields` is 'ids' or 'counts'. 337 * Accepts 'threaded', 'flat', or false. Default: 'threaded'. 338 * @type string|array $orderby Comment status or array of statuses. To use 'meta_value' 339 * or 'meta_value_num', `$meta_key` must also be defined. 340 * To sort by a specific `$meta_query` clause, use that 341 * clause's array key. Accepts 'comment_agent', 342 * 'comment_approved', 'comment_author', 343 * 'comment_author_email', 'comment_author_IP', 344 * 'comment_author_url', 'comment_content', 'comment_date', 345 * 'comment_date_gmt', 'comment_ID', 'comment_karma', 346 * 'comment_parent', 'comment_post_ID', 'comment_type', 347 * 'user_id', 'comment__in', 'meta_value', 'meta_value_num', 348 * the value of $meta_key, and the array keys of 349 * `$meta_query`. Also accepts false, an empty array, or 350 * 'none' to disable `ORDER BY` clause. 351 * @type string $fields Which fields to return. Accepts 'ids' for comment IDs, or an 352 * empty string for full `WP_Comment` objects. Default empty. 353 * @type bool $count Whether to return a comment count rather than comments. 354 * Default false. 355 * @type string $type Limit results to comments of a given type, such as 'comment', 356 * 'pingback', 'trackback', or 'note'. Accepts 'all' for every 357 * type. Default empty. 358 * @type int $number Maximum number of comments to retrieve. Default empty (no limit). 359 * @type int $post_id Limit results to comments on a given post. Default 0. 360 * @type string $order How to order retrieved comments. Accepts 'ASC' or 'DESC'. 361 * Default 'DESC'. 362 * } 363 * @return WP_Comment[]|int[]|int Array of `WP_Comment` objects, an array of comment IDs when 364 * `$fields` is 'ids', or the number of children when `$count` 365 * is true. 366 * 367 * @phpstan-param array{ 368 * format?: 'tree'|'flat', 369 * status?: 'hold'|'approve'|'all'|string, 370 * hierarchical?: 'threaded'|'flat'|false, 371 * orderby?: string|string[]|false, 372 * fields?: 'ids'|'', 373 * count?: bool, 374 * type?: string, 375 * number?: int, 376 * post_id?: int, 377 * order?: 'ASC'|'DESC', 378 * ... 379 * } $args 380 * @phpstan-return ( 381 * $args is array{ count: true, ... } ? non-negative-int : ( 382 * $args is array{ fields: 'ids', ... } ? non-negative-int[] : ( 383 * $args is array{ format: 'flat', ... } ? list<WP_Comment> : array<int, WP_Comment> 384 * ) 385 * ) 386 * ) 387 */ 388 public function get_children( $args = array() ) { 389 $defaults = array( 390 'format' => 'tree', 391 'status' => 'all', 392 'hierarchical' => 'threaded', 393 'orderby' => '', 394 ); 395 396 /** @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 */ 397 $_args = wp_parse_args( $args, $defaults ); 398 $_args['parent'] = $this->comment_ID; 399 400 /* 401 * A 'count' or 'ids' query returns an integer or a list of comment IDs rather than 402 * WP_Comment objects. Neither may be written to the children cache, which holds 403 * WP_Comment objects and is read back by add_child(), get_child(), and the 'flat' 404 * format below. Return the result directly and leave the cache untouched. The two 405 * branches must stay separate: each is narrowed independently, and `count` is only 406 * safe to overwrite in the 'ids' branch. 407 */ 408 if ( ! empty( $_args['count'] ) ) { 409 return get_comments( $_args ); 410 } elseif ( isset( $_args['fields'] ) && 'ids' === $_args['fields'] ) { 411 $_args['count'] = false; // For static analysis of the conditional return type. 412 return get_comments( $_args ); 413 } 414 415 // Only WP_Comment objects are returned past this point. Stated positively for static analysis. 416 $_args['count'] = false; 417 $_args['fields'] = ''; 418 419 if ( is_null( $this->children ) ) { 420 if ( $this->populated_children ) { 421 $this->children = array(); 422 } else { 423 $this->children = get_comments( $_args ); 424 } 425 } 426 427 if ( 'flat' === $_args['format'] ) { 428 $children = array(); 429 foreach ( $this->children as $child ) { 430 $child_args = $_args; 431 $child_args['format'] = 'flat'; 432 // get_children() resets this value automatically. 433 unset( $child_args['parent'] ); 434 435 $children = array_merge( $children, array( $child ), $child->get_children( $child_args ) ); 436 } 437 } else { 438 $children = $this->children; 439 } 440 441 return $children; 442 } 443 444 /** 445 * Adds a child to the comment. 446 * 447 * Used by `WP_Comment_Query` when bulk-filling descendants. 448 * 449 * @since 4.4.0 450 * 451 * @param WP_Comment $child Child comment. 452 */ 453 public function add_child( WP_Comment $child ): void { 454 $this->children[ (int) $child->comment_ID ] = $child; 455 } 456 457 /** 458 * Gets a child comment by ID. 459 * 460 * @since 4.4.0 461 * 462 * @param int $child_id ID of the child. 463 * @return WP_Comment|false Returns the comment object if found, otherwise false. 464 */ 465 public function get_child( $child_id ) { 466 return $this->children[ $child_id ] ?? false; 467 } 468 469 /** 470 * Sets the 'populated_children' flag. 471 * 472 * This flag is important for ensuring that calling `get_children()` on a childless comment will not trigger 473 * unneeded database queries. 474 * 475 * @since 4.4.0 476 * 477 * @param bool $set Whether the comment's children have already been populated. 478 */ 479 public function populated_children( $set ): void { 480 $this->populated_children = (bool) $set; 481 } 482 483 /** 484 * Determines whether a non-public property is set. 485 * 486 * If `$name` matches a post field, the comment post will be loaded and the post's value checked. 487 * 488 * @since 4.4.0 489 * @since 7.1.0 Returns false instead of causing a fatal error when the comment's post cannot be found. 490 * 491 * @param string $name Property to check if set. 492 * @return bool Whether the property is set. 493 */ 494 public function __isset( $name ) { 495 if ( in_array( $name, $this->post_fields, true ) && 0 !== (int) $this->comment_post_ID ) { 496 $post = get_post( (int) $this->comment_post_ID ); 497 return $post && property_exists( $post, $name ); 498 } 499 500 return false; 501 } 502 503 /** 504 * Magic getter. 505 * 506 * If `$name` matches a post field, the comment post will be loaded and the post's value returned. 507 * 508 * @since 4.4.0 509 * @since 7.1.0 Returns null instead of the global post's field when the comment is not attached to 510 * a post, and no longer raises a warning when the comment's post cannot be found. 511 * 512 * @param string $name Property name. 513 * @return mixed 514 */ 515 public function __get( $name ) { 516 if ( in_array( $name, $this->post_fields, true ) && 0 !== (int) $this->comment_post_ID ) { 517 $post = get_post( (int) $this->comment_post_ID ); 518 if ( ! $post ) { 519 return null; 520 } 521 return $post->$name; 522 } 523 return null; 524 } 525 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Sat Aug 29 08:20:24 2026 | Cross-referenced by PHPXref |