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