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