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 	 * @var int

    22 	 */

    23 	public $comment_ID;

    24 

    25 	/**

    26 	 * ID of the post the comment is associated with.

    27 	 *

    28 	 * @since 4.4.0

    29 	 * @var int

    30 	 */

    31 	public $comment_post_ID = 0;

    32 

    33 	/**

    34 	 * Comment author name.

    35 	 *

    36 	 * @since 4.4.0

    37 	 * @var string

    38 	 */

    39 	public $comment_author = '';

    40 

    41 	/**

    42 	 * Comment author email address.

    43 	 *

    44 	 * @since 4.4.0

    45 	 * @var string

    46 	 */

    47 	public $comment_author_email = '';

    48 

    49 	/**

    50 	 * Comment author URL.

    51 	 *

    52 	 * @since 4.4.0

    53 	 * @var string

    54 	 */

    55 	public $comment_author_url = '';

    56 

    57 	/**

    58 	 * Comment author IP address (IPv4 format).

    59 	 *

    60 	 * @since 4.4.0

    61 	 * @var string

    62 	 */

    63 	public $comment_author_IP = '';

    64 

    65 	/**

    66 	 * Comment date in YYYY-MM-DD HH:MM:SS format.

    67 	 *

    68 	 * @since 4.4.0

    69 	 * @var string

    70 	 */

    71 	public $comment_date = '0000-00-00 00:00:00';

    72 

    73 	/**

    74 	 * Comment GMT date in YYYY-MM-DD HH::MM:SS format.

    75 	 *

    76 	 * @since 4.4.0

    77 	 * @var string

    78 	 */

    79 	public $comment_date_gmt = '0000-00-00 00:00:00';

    80 

    81 	/**

    82 	 * Comment content.

    83 	 *

    84 	 * @since 4.4.0

    85 	 * @var string

    86 	 */

    87 	public $comment_content;

    88 

    89 	/**

    90 	 * Comment karma count.

    91 	 *

    92 	 * @since 4.4.0

    93 	 * @var int

    94 	 */

    95 	public $comment_karma = 0;

    96 

    97 	/**

    98 	 * Comment approval status.

    99 	 *

   100 	 * @since 4.4.0

   101 	 * @var string

   102 	 */

   103 	public $comment_approved = '1';

   104 

   105 	/**

   106 	 * Comment author HTTP user agent.

   107 	 *

   108 	 * @since 4.4.0

   109 	 * @var string

   110 	 */

   111 	public $comment_agent = '';

   112 

   113 	/**

   114 	 * Comment type.

   115 	 *

   116 	 * @since 4.4.0

   117 	 * @var string

   118 	 */

   119 	public $comment_type = '';

   120 

   121 	/**

   122 	 * Parent comment ID.

   123 	 *

   124 	 * @since 4.4.0

   125 	 * @var int

   126 	 */

   127 	public $comment_parent = 0;

   128 

   129 	/**

   130 	 * Comment author ID.

   131 	 *

   132 	 * @since 4.4.0

   133 	 * @var int

   134 	 */

   135 	public $user_id = 0;

   136 

   137 	/**

   138 	 * Comment children.

   139 	 *

   140 	 * @since 4.4.0

   141 	 * @var array

   142 	 */

   143 	protected $children;

   144 

   145 	/**

   146 	 * Whether children have been populated for this comment object.

   147 	 *

   148 	 * @since 4.4.0

   149 	 * @var bool

   150 	 */

   151 	protected $populated_children = false;

   152 

   153 	/**

   154 	 * Post fields.

   155 	 *

   156 	 * @since 4.4.0

   157 	 * @var array

   158 	 */

   159 	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' );

   160 

   161 	/**

   162 	 * Retrieves a WP_Comment instance.

   163 	 *

   164 	 * @since 4.4.0

   165 	 * @static

   166 	 *

   167 	 * @global wpdb $wpdb WordPress database abstraction object.

   168 	 *

   169 	 * @param int $id Comment ID.

   170 	 * @return WP_Comment|false Comment object, otherwise false.

   171 	 */

   172 	public static function get_instance( $id ) {

   173 		global $wpdb;

   174 

   175 		$comment_id = (int) $id;

   176 		if ( ! $comment_id ) {

   177 			return false;

   178 		}

   179 

   180 		$_comment = wp_cache_get( $comment_id, 'comment' );

   181 

   182 		if ( ! $_comment ) {

   183 			$_comment = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_ID = %d LIMIT 1", $comment_id ) );

   184 

   185 			if ( ! $_comment ) {

   186 				return false;

   187 			}

   188 

   189 			wp_cache_add( $_comment->comment_ID, $_comment, 'comment' );

   190 		}

   191 

   192 		return new WP_Comment( $_comment );

   193 	}

   194 

   195 	/**

   196 	 * Constructor.

   197 	 *

   198 	 * Populates properties with object vars.

   199 	 *

   200 	 * @since 4.4.0

   201 	 *

   202 	 * @param WP_Comment $comment Comment object.

   203 	 */

   204 	public function __construct( $comment ) {

   205 		foreach ( get_object_vars( $comment ) as $key => $value ) {

   206 			$this->$key = $value;

   207 		}

   208 	}

   209 

   210 	/**

   211 	 * Convert object to array.

   212 	 *

   213 	 * @since 4.4.0

   214 	 *

   215 	 * @return array Object as array.

   216 	 */

   217 	public function to_array() {

   218 		return get_object_vars( $this );

   219 	}

   220 

   221 	/**

   222 	 * Get the children of a comment.

   223 	 *

   224 	 * @since 4.4.0

   225 	 *

   226 	 * @param array $args {

   227 	 *     Array of arguments used to pass to get_comments() and determine format.

   228 	 *

   229 	 *     @type string $format        Return value format. 'tree' for a hierarchical tree, 'flat' for a flattened array.

   230 	 *                                 Default 'tree'.

   231 	 *     @type string $status        Comment status to limit results by. Accepts 'hold' (`comment_status=0`),

   232 	 *                                 'approve' (`comment_status=1`), 'all', or a custom comment status.

   233 	 *                                 Default 'all'.

   234 	 *     @type string $hierarchical  Whether to include comment descendants in the results.

   235 	 *                                 'threaded' returns a tree, with each comment's children

   236 	 *                                 stored in a `children` property on the `WP_Comment` object.

   237 	 *                                 'flat' returns a flat array of found comments plus their children.

   238 	 *                                 Pass `false` to leave out descendants.

   239 	 *                                 The parameter is ignored (forced to `false`) when `$fields` is 'ids' or 'counts'.

   240 	 *                                 Accepts 'threaded', 'flat', or false. Default: 'threaded'.

   241 	 *     @type string|array $orderby Comment status or array of statuses. To use 'meta_value'

   242 	 *                                 or 'meta_value_num', `$meta_key` must also be defined.

   243 	 *                                 To sort by a specific `$meta_query` clause, use that

   244 	 *                                 clause's array key. Accepts 'comment_agent',

   245 	 *                                 'comment_approved', 'comment_author',

   246 	 *                                 'comment_author_email', 'comment_author_IP',

   247 	 *                                 'comment_author_url', 'comment_content', 'comment_date',

   248 	 *                                 'comment_date_gmt', 'comment_ID', 'comment_karma',

   249 	 *                                 'comment_parent', 'comment_post_ID', 'comment_type',

   250 	 *                                 'user_id', 'comment__in', 'meta_value', 'meta_value_num',

   251 	 *                                 the value of $meta_key, and the array keys of

   252 	 *                                 `$meta_query`. Also accepts false, an empty array, or

   253 	 *                                 'none' to disable `ORDER BY` clause.

   254 	 * }

   255 	 * @return array Array of `WP_Comment` objects.

   256 	 */

   257 	public function get_children( $args = array() ) {

   258 		$defaults = array(

   259 			'format' => 'tree',

   260 			'status' => 'all',

   261 			'hierarchical' => 'threaded',

   262 			'orderby' => '',

   263 		);

   264 

   265 		$_args = wp_parse_args( $args, $defaults );

   266 		$_args['parent'] = $this->comment_ID;

   267 

   268 		if ( is_null( $this->children ) ) {

   269 			if ( $this->populated_children ) {

   270 				$this->children = array();

   271 			} else {

   272 				$this->children = get_comments( $_args );

   273 			}

   274 		}

   275 

   276 		if ( 'flat' === $_args['format'] ) {

   277 			$children = array();

   278 			foreach ( $this->children as $child ) {

   279 				$child_args = $_args;

   280 				$child_args['format'] = 'flat';

   281 				// get_children() resets this value automatically.

   282 				unset( $child_args['parent'] );

   283 

   284 				$children = array_merge( $children, array( $child ), $child->get_children( $child_args ) );

   285 			}

   286 		} else {

   287 			$children = $this->children;

   288 		}

   289 

   290 		return $children;

   291 	}

   292 

   293 	/**

   294 	 * Add a child to the comment.

   295 	 *

   296 	 * Used by `WP_Comment_Query` when bulk-filling descendants.

   297 	 *

   298 	 * @since 4.4.0

   299 	 *

   300 	 * @param WP_Comment $child Child comment.

   301 	 */

   302 	public function add_child( WP_Comment $child ) {

   303 		$this->children[ $child->comment_ID ] = $child;

   304 	}

   305 

   306 	/**

   307 	 * Get a child comment by ID.

   308 	 *

   309 	 * @since 4.4.0

   310 	 *

   311 	 * @param int $child_id ID of the child.

   312 	 * @return WP_Comment|bool Returns the comment object if found, otherwise false.

   313 	 */

   314 	public function get_child( $child_id ) {

   315 		if ( isset( $this->children[ $child_id ] ) ) {

   316 			return $this->children[ $child_id ];

   317 		}

   318 

   319 		return false;

   320 	}

   321 

   322 	/**

   323 	 * Set the 'populated_children' flag.

   324 	 *

   325 	 * This flag is important for ensuring that calling `get_children()` on a childless comment will not trigger

   326 	 * unneeded database queries.

   327 	 *

   328 	 * @since 4.4.0

   329 	 *

   330 	 * @param bool $set Whether the comment's children have already been populated.

   331 	 */

   332 	public function populated_children( $set ) {

   333 		$this->populated_children = (bool) $set;

   334 	}

   335 

   336 	/**

   337 	 * Check whether a non-public property is set.

   338 	 *

   339 	 * If `$name` matches a post field, the comment post will be loaded and the post's value checked.

   340 	 *

   341 	 * @since 4.4.0

   342 	 *

   343 	 * @param string $name Property name.

   344 	 * @return bool

   345 	 */

   346 	public function __isset( $name ) {

   347 		if ( in_array( $name, $this->post_fields ) && 0 !== (int) $this->comment_post_ID ) {

   348 			$post = get_post( $this->comment_post_ID );

   349 			return property_exists( $post, $name );

   350 		}

   351 	}

   352 

   353 	/**

   354 	 * Magic getter.

   355 	 *

   356 	 * If `$name` matches a post field, the comment post will be loaded and the post's value returned.

   357 	 *

   358 	 * @since 4.4.0

   359 	 *

   360 	 * @param string $name

   361 	 * @return mixed

   362 	 */

   363 	public function __get( $name ) {

   364 		if ( in_array( $name, $this->post_fields ) ) {

   365 			$post = get_post( $this->comment_post_ID );

   366 			return $post->$name;

   367 		}

   368 	}

   369 }