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