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