/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. $comment_id = (int) $id; 
  195. if ( ! $comment_id ) { 
  196. return false; 
  197.  
  198. $_comment = wp_cache_get( $comment_id, 'comment' ); 
  199.  
  200. if ( ! $_comment ) { 
  201. $_comment = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_ID = %d LIMIT 1", $comment_id ) ); 
  202.  
  203. if ( ! $_comment ) { 
  204. return false; 
  205.  
  206. wp_cache_add( $_comment->comment_ID, $_comment, 'comment' ); 
  207.  
  208. return new WP_Comment( $_comment ); 
  209.  
  210. /** 
  211. * Constructor. 
  212. * 
  213. * Populates properties with object vars. 
  214. * 
  215. * @since 4.4.0 
  216. * @access public 
  217. * 
  218. * @param WP_Comment $comment Comment object. 
  219. */ 
  220. public function __construct( $comment ) { 
  221. foreach ( get_object_vars( $comment ) as $key => $value ) { 
  222. $this->$key = $value; 
  223.  
  224. /** 
  225. * Convert object to array. 
  226. * 
  227. * @since 4.4.0 
  228. * @access public 
  229. * 
  230. * @return array Object as array. 
  231. */ 
  232. public function to_array() { 
  233. return get_object_vars( $this ); 
  234.  
  235. /** 
  236. * Get the children of a comment. 
  237. * 
  238. * @since 4.4.0 
  239. * @access public 
  240. * 
  241. * @param array $args { 
  242. * Array of arguments used to pass to get_comments() and determine format. 
  243. * 
  244. * @type string $format Return value format. 'tree' for a hierarchical tree, 'flat' for a flattened array. 
  245. * Default 'tree'. 
  246. * @type string $status Comment status to limit results by. Accepts 'hold' (`comment_status=0`),  
  247. * 'approve' (`comment_status=1`), 'all', or a custom comment status. 
  248. * Default 'all'. 
  249. * @type string $hierarchical Whether to include comment descendants in the results. 
  250. * 'threaded' returns a tree, with each comment's children 
  251. * stored in a `children` property on the `WP_Comment` object. 
  252. * 'flat' returns a flat array of found comments plus their children. 
  253. * Pass `false` to leave out descendants. 
  254. * The parameter is ignored (forced to `false`) when `$fields` is 'ids' or 'counts'. 
  255. * Accepts 'threaded', 'flat', or false. Default: 'threaded'. 
  256. * @type string|array $orderby Comment status or array of statuses. To use 'meta_value' 
  257. * or 'meta_value_num', `$meta_key` must also be defined. 
  258. * To sort by a specific `$meta_query` clause, use that 
  259. * clause's array key. Accepts 'comment_agent',  
  260. * 'comment_approved', 'comment_author',  
  261. * 'comment_author_email', 'comment_author_IP',  
  262. * 'comment_author_url', 'comment_content', 'comment_date',  
  263. * 'comment_date_gmt', 'comment_ID', 'comment_karma',  
  264. * 'comment_parent', 'comment_post_ID', 'comment_type',  
  265. * 'user_id', 'comment__in', 'meta_value', 'meta_value_num',  
  266. * the value of $meta_key, and the array keys of 
  267. * `$meta_query`. Also accepts false, an empty array, or 
  268. * 'none' to disable `ORDER BY` clause. 
  269. * } 
  270. * @return array Array of `WP_Comment` objects. 
  271. */ 
  272. public function get_children( $args = array() ) { 
  273. $defaults = array( 
  274. 'format' => 'tree',  
  275. 'status' => 'all',  
  276. 'hierarchical' => 'threaded',  
  277. 'orderby' => '',  
  278. ); 
  279.  
  280. $_args = wp_parse_args( $args, $defaults ); 
  281. $_args['parent'] = $this->comment_ID; 
  282.  
  283. if ( is_null( $this->children ) ) { 
  284. if ( $this->populated_children ) { 
  285. $this->children = array(); 
  286. } else { 
  287. $this->children = get_comments( $_args ); 
  288.  
  289. if ( 'flat' === $_args['format'] ) { 
  290. $children = array(); 
  291. foreach ( $this->children as $child ) { 
  292. $child_args = $_args; 
  293. $child_args['format'] = 'flat'; 
  294. // get_children() resets this value automatically. 
  295. unset( $child_args['parent'] ); 
  296.  
  297. $children = array_merge( $children, array( $child ), $child->get_children( $child_args ) ); 
  298. } else { 
  299. $children = $this->children; 
  300.  
  301. return $children; 
  302.  
  303. /** 
  304. * Add a child to the comment. 
  305. * 
  306. * Used by `WP_Comment_Query` when bulk-filling descendants. 
  307. * 
  308. * @since 4.4.0 
  309. * @access public 
  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. * Get a child comment by ID. 
  318. * 
  319. * @since 4.4.0 
  320. * @access public 
  321. * 
  322. * @param int $child_id ID of the child. 
  323. * @return WP_Comment|bool 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. return false; 
  330.  
  331. /** 
  332. * Set the 'populated_children' flag. 
  333. * 
  334. * This flag is important for ensuring that calling `get_children()` on a childless comment will not trigger 
  335. * unneeded database queries. 
  336. * 
  337. * @since 4.4.0 
  338. * 
  339. * @param bool $set Whether the comment's children have already been populated. 
  340. */ 
  341. public function populated_children( $set ) { 
  342. $this->populated_children = (bool) $set; 
  343.  
  344. /** 
  345. * Check whether a non-public property is set. 
  346. * 
  347. * If `$name` matches a post field, the comment post will be loaded and the post's value checked. 
  348. * 
  349. * @since 4.4.0 
  350. * @access public 
  351. * 
  352. * @param string $name Property name. 
  353. * @return bool 
  354. */ 
  355. public function __isset( $name ) { 
  356. if ( in_array( $name, $this->post_fields ) && 0 !== (int) $this->comment_post_ID ) { 
  357. $post = get_post( $this->comment_post_ID ); 
  358. return property_exists( $post, $name ); 
  359.  
  360. /** 
  361. * Magic getter. 
  362. * 
  363. * If `$name` matches a post field, the comment post will be loaded and the post's value returned. 
  364. * 
  365. * @since 4.4.0 
  366. * @access public 
  367. * 
  368. * @param string $name 
  369. * @return mixed 
  370. */ 
  371. public function __get( $name ) { 
  372. if ( in_array( $name, $this->post_fields ) ) { 
  373. $post = get_post( $this->comment_post_ID ); 
  374. return $post->$name; 
.