wp-includes/class-wp-comment.php

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