WordPress 4.7
[autoinstalls/wordpress.git] / 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 }