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]
 16final 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 to check if set.
355	 * @return bool Whether the property is set.
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		return false;
364	}
365
366	/**
367	 * Magic getter.
368	 *
369	 * If `$name` matches a post field, the comment post will be loaded and the post's value returned.
370	 *
371	 * @since 4.4.0
372	 *
373	 * @param string $name Property name.
374	 * @return mixed
375	 */
376	public function __get( $name ) {
377		if ( in_array( $name, $this->post_fields, true ) ) {
378			$post = get_post( $this->comment_post_ID );
379			return $post->$name;
380		}
381	}
382}
383