[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   * @since 4.4.0
  14   */
  15  #[AllowDynamicProperties]
  16  final class WP_Comment {
  17  
  18      /**
  19       * Comment ID.
  20       *
  21       * A numeric string, for compatibility reasons.
  22       *
  23       * @since 4.4.0
  24       * @var string
  25       * @phpstan-var numeric-string
  26       */
  27      public $comment_ID;
  28  
  29      /**
  30       * ID of the post the comment is associated with.
  31       *
  32       * A numeric string, for compatibility reasons.
  33       *
  34       * @since 4.4.0
  35       * @var string
  36       * @phpstan-var numeric-string
  37       */
  38      public $comment_post_ID = '0';
  39  
  40      /**
  41       * Comment author name.
  42       *
  43       * @since 4.4.0
  44       * @var string
  45       */
  46      public $comment_author = '';
  47  
  48      /**
  49       * Comment author email address.
  50       *
  51       * @since 4.4.0
  52       * @var string
  53       */
  54      public $comment_author_email = '';
  55  
  56      /**
  57       * Comment author URL.
  58       *
  59       * @since 4.4.0
  60       * @var string
  61       */
  62      public $comment_author_url = '';
  63  
  64      /**
  65       * Comment author IP address (IPv4 format).
  66       *
  67       * @since 4.4.0
  68       * @var string
  69       */
  70      public $comment_author_IP = '';
  71  
  72      /**
  73       * Comment date in YYYY-MM-DD HH:MM:SS format.
  74       *
  75       * @since 4.4.0
  76       * @var string
  77       */
  78      public $comment_date = '0000-00-00 00:00:00';
  79  
  80      /**
  81       * Comment GMT date in YYYY-MM-DD HH::MM:SS format.
  82       *
  83       * @since 4.4.0
  84       * @var string
  85       */
  86      public $comment_date_gmt = '0000-00-00 00:00:00';
  87  
  88      /**
  89       * Comment content.
  90       *
  91       * @since 4.4.0
  92       * @var string
  93       */
  94      public $comment_content;
  95  
  96      /**
  97       * Comment karma count.
  98       *
  99       * A numeric string, for compatibility reasons.
 100       *
 101       * @since 4.4.0
 102       * @var string
 103       * @phpstan-var numeric-string
 104       */
 105      public $comment_karma = '0';
 106  
 107      /**
 108       * Comment approval status.
 109       *
 110       * @since 4.4.0
 111       * @var string
 112       */
 113      public $comment_approved = '1';
 114  
 115      /**
 116       * Comment author HTTP user agent.
 117       *
 118       * @since 4.4.0
 119       * @var string
 120       */
 121      public $comment_agent = '';
 122  
 123      /**
 124       * Comment type.
 125       *
 126       * @since 4.4.0
 127       * @since 5.5.0 Default value changed to `comment`.
 128       * @var string
 129       */
 130      public $comment_type = 'comment';
 131  
 132      /**
 133       * Parent comment ID.
 134       *
 135       * A numeric string, for compatibility reasons.
 136       *
 137       * @since 4.4.0
 138       * @var string
 139       * @phpstan-var numeric-string
 140       */
 141      public $comment_parent = '0';
 142  
 143      /**
 144       * Comment author ID.
 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 $user_id = '0';
 153  
 154      /**
 155       * Comment children.
 156       *
 157       * @since 4.4.0
 158       * @var array
 159       */
 160      protected $children;
 161  
 162      /**
 163       * Whether children have been populated for this comment object.
 164       *
 165       * @since 4.4.0
 166       * @var bool
 167       */
 168      protected $populated_children = false;
 169  
 170      /**
 171       * Post fields.
 172       *
 173       * @since 4.4.0
 174       * @var array
 175       */
 176      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' );
 177  
 178      /**
 179       * Retrieves a WP_Comment instance.
 180       *
 181       * @since 4.4.0
 182       *
 183       * @global wpdb $wpdb WordPress database abstraction object.
 184       *
 185       * @param int $id Comment ID.
 186       * @return WP_Comment|false Comment object, otherwise false.
 187       */
 188  	public static function get_instance( $id ) {
 189          global $wpdb;
 190  
 191          $comment_id = (int) $id;
 192          if ( ! $comment_id ) {
 193              return false;
 194          }
 195  
 196          $_comment = wp_cache_get( $comment_id, 'comment' );
 197  
 198          if ( ! $_comment ) {
 199              $_comment = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_ID = %d LIMIT 1", $comment_id ) );
 200  
 201              if ( ! $_comment ) {
 202                  return false;
 203              }
 204  
 205              wp_cache_add( $_comment->comment_ID, $_comment, 'comment' );
 206          }
 207  
 208          return new WP_Comment( $_comment );
 209      }
 210  
 211      /**
 212       * Constructor.
 213       *
 214       * Populates properties with object vars.
 215       *
 216       * @since 4.4.0
 217       *
 218       * @param object $comment Comment object.
 219       */
 220  	public function __construct( $comment ) {
 221          foreach ( get_object_vars( $comment ) as $key => $value ) {
 222              $this->$key = $value;
 223          }
 224      }
 225  
 226      /**
 227       * Converts object to array.
 228       *
 229       * @since 4.4.0
 230       *
 231       * @return array Object as array.
 232       */
 233  	public function to_array() {
 234          return get_object_vars( $this );
 235      }
 236  
 237      /**
 238       * Gets the children of a comment.
 239       *
 240       * @since 4.4.0
 241       *
 242       * @param array $args {
 243       *     Array of arguments used to pass to get_comments() and determine format.
 244       *
 245       *     @type string $format        Return value format. 'tree' for a hierarchical tree, 'flat' for a flattened array.
 246       *                                 Default 'tree'.
 247       *     @type string $status        Comment status to limit results by. Accepts 'hold' (`comment_status=0`),
 248       *                                 'approve' (`comment_status=1`), 'all', or a custom comment status.
 249       *                                 Default 'all'.
 250       *     @type string $hierarchical  Whether to include comment descendants in the results.
 251       *                                 'threaded' returns a tree, with each comment's children
 252       *                                 stored in a `children` property on the `WP_Comment` object.
 253       *                                 'flat' returns a flat array of found comments plus their children.
 254       *                                 Pass `false` to leave out descendants.
 255       *                                 The parameter is ignored (forced to `false`) when `$fields` is 'ids' or 'counts'.
 256       *                                 Accepts 'threaded', 'flat', or false. Default: 'threaded'.
 257       *     @type string|array $orderby Comment status or array of statuses. To use 'meta_value'
 258       *                                 or 'meta_value_num', `$meta_key` must also be defined.
 259       *                                 To sort by a specific `$meta_query` clause, use that
 260       *                                 clause's array key. Accepts 'comment_agent',
 261       *                                 'comment_approved', 'comment_author',
 262       *                                 'comment_author_email', 'comment_author_IP',
 263       *                                 'comment_author_url', 'comment_content', 'comment_date',
 264       *                                 'comment_date_gmt', 'comment_ID', 'comment_karma',
 265       *                                 'comment_parent', 'comment_post_ID', 'comment_type',
 266       *                                 'user_id', 'comment__in', 'meta_value', 'meta_value_num',
 267       *                                 the value of $meta_key, and the array keys of
 268       *                                 `$meta_query`. Also accepts false, an empty array, or
 269       *                                 'none' to disable `ORDER BY` clause.
 270       * }
 271       * @return WP_Comment[] Array of `WP_Comment` objects.
 272       */
 273  	public function get_children( $args = array() ) {
 274          $defaults = array(
 275              'format'       => 'tree',
 276              'status'       => 'all',
 277              'hierarchical' => 'threaded',
 278              'orderby'      => '',
 279          );
 280  
 281          $_args           = wp_parse_args( $args, $defaults );
 282          $_args['parent'] = $this->comment_ID;
 283  
 284          if ( is_null( $this->children ) ) {
 285              if ( $this->populated_children ) {
 286                  $this->children = array();
 287              } else {
 288                  $this->children = get_comments( $_args );
 289              }
 290          }
 291  
 292          if ( 'flat' === $_args['format'] ) {
 293              $children = array();
 294              foreach ( $this->children as $child ) {
 295                  $child_args           = $_args;
 296                  $child_args['format'] = 'flat';
 297                  // get_children() resets this value automatically.
 298                  unset( $child_args['parent'] );
 299  
 300                  $children = array_merge( $children, array( $child ), $child->get_children( $child_args ) );
 301              }
 302          } else {
 303              $children = $this->children;
 304          }
 305  
 306          return $children;
 307      }
 308  
 309      /**
 310       * Adds a child to the comment.
 311       *
 312       * Used by `WP_Comment_Query` when bulk-filling descendants.
 313       *
 314       * @since 4.4.0
 315       *
 316       * @param WP_Comment $child Child comment.
 317       */
 318  	public function add_child( WP_Comment $child ) {
 319          $this->children[ $child->comment_ID ] = $child;
 320      }
 321  
 322      /**
 323       * Gets a child comment by ID.
 324       *
 325       * @since 4.4.0
 326       *
 327       * @param int $child_id ID of the child.
 328       * @return WP_Comment|false Returns the comment object if found, otherwise false.
 329       */
 330  	public function get_child( $child_id ) {
 331          return $this->children[ $child_id ] ?? false;
 332      }
 333  
 334      /**
 335       * Sets the 'populated_children' flag.
 336       *
 337       * This flag is important for ensuring that calling `get_children()` on a childless comment will not trigger
 338       * unneeded database queries.
 339       *
 340       * @since 4.4.0
 341       *
 342       * @param bool $set Whether the comment's children have already been populated.
 343       */
 344  	public function populated_children( $set ) {
 345          $this->populated_children = (bool) $set;
 346      }
 347  
 348      /**
 349       * Determines whether a non-public property is set.
 350       *
 351       * If `$name` matches a post field, the comment post will be loaded and the post's value checked.
 352       *
 353       * @since 4.4.0
 354       *
 355       * @param string $name Property to check if set.
 356       * @return bool Whether the property is set.
 357       */
 358  	public function __isset( $name ) {
 359          if ( in_array( $name, $this->post_fields, true ) && 0 !== (int) $this->comment_post_ID ) {
 360              $post = get_post( $this->comment_post_ID );
 361              return property_exists( $post, $name );
 362          }
 363  
 364          return false;
 365      }
 366  
 367      /**
 368       * Magic getter.
 369       *
 370       * If `$name` matches a post field, the comment post will be loaded and the post's value returned.
 371       *
 372       * @since 4.4.0
 373       *
 374       * @param string $name Property name.
 375       * @return mixed
 376       */
 377  	public function __get( $name ) {
 378          if ( in_array( $name, $this->post_fields, true ) ) {
 379              $post = get_post( $this->comment_post_ID );
 380              return $post->$name;
 381          }
 382      }
 383  }