wp_list_comments

List comments.

Description

wp_list_comments( (array) $args = array(), (null) $comments = null ); 

Used in the comments.php template to list comments for a particular post.

Parameters (2)

0. $args — Optional. (array) => array()
Formatting options.

Options

  • walker (object) => null

    Instance of a Walker class to list comments.

  • max_depth (int) => 0

    The maximum comments depth.

  • style (string) => ''

    The style of list ordering. Default ul.. Accepts ul., ol,.

  • callback (string) => null

    Callback function to use.

  • end-callback (string) => null

    Callback function to use at the end.

  • type (string) => ''

    Type of comments to list. Default all.. Accepts all., comment,, pingback, trackback, pings.

  • page (int) => 0

    Page ID to list comments for.

  • per_page (int) => 0

    Number of comments to list per page.

  • avatar_size (int) => 32

    Height and width dimensions of the avatar size.

  • reverse_top_level (bool) => null

    Ordering of the listed comments. If true, will display newest comments first.

  • reverse_children (bool) => null

    Whether to reverse child comments in the list.

  • format (string) => ''

    How to format the comments list. Default html5 if the theme supports it. Accepts html5 , xhtml,.

  • short_ping (bool) => false

    Whether to output short pings.

array(

    /**
     * Instance of a Walker class to list comments.
     *
     * @type object
     * @default null
     */
    'walker' => null,

    /**
     * The maximum comments depth.
     *
     * @type int
     */
    'max_depth' => 0,

    /**
     * The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'.
     *
     * @type string
     * @default ''
     */
    'style' => '',

    /**
     * Callback function to use.
     *
     * @type string
     * @default null
     */
    'callback' => null,

    /**
     * Callback function to use at the end.
     *
     * @type string
     * @default null
     */
    'end-callback' => null,

    /**
     * Type of comments to list. Default 'all'. Accepts 'all', 'comment', 'pingback',
     * 'trackback', 'pings'.
     *
     * @type string
     * @default ''
     */
    'type' => '',

    /**
     * Page ID to list comments for.
     *
     * @type int
     */
    'page' => 0,

    /**
     * Number of comments to list per page.
     *
     * @type int
     */
    'per_page' => 0,

    /**
     * Height and width dimensions of the avatar size.
     *
     * @type int
     * @default 32
     */
    'avatar_size' => 32,

    /**
     * Ordering of the listed comments. If true, will display newest comments first.
     *
     * @type bool
     * @default null
     */
    'reverse_top_level' => null,

    /**
     * Whether to reverse child comments in the list.
     *
     * @type bool
     * @default null
     */
    'reverse_children' => null,

    /**
     * How to format the comments list. Default 'html5' if the theme supports it. Accepts 'html5',
     * 'xhtml'.
     *
     * @type string
     * @default ''
     */
    'format' => '',

    /**
     * Whether to output short pings.
     *
     * @type bool
     * @default false
     */
    'short_ping' => false
);        

1. $comments — Optional. (null) => null
Array of WP_Comment objects.

Usage

  1. if ( !function_exists( 'wp_list_comments' ) ) { 
  2. require_once ABSPATH . WPINC . '/comment-template.php'; 
  3.  
  4. // Optional. Formatting options. 
  5. $args = array( 
  6. 'walker' => null, 
  7. 'max_depth' => 0, 
  8. 'style' => '', 
  9. 'callback' => null, 
  10. 'end-callback' => null, 
  11. 'type' => '', 
  12. 'page' => 0, 
  13. 'per_page' => 0, 
  14. 'avatar_size' => 32, 
  15. 'reverse_top_level' => null, 
  16. 'reverse_children' => null, 
  17. 'format' => '', 
  18. 'short_ping' => false 
  19. ); 
  20.  
  21. // Optional. Array of WP_Comment objects. 
  22. $comments = null; 
  23.  
  24. // NOTICE! Understand what this does before running. 
  25. $result = wp_list_comments($args, $comments); 
  26.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/comment-template.php  
  1. function wp_list_comments( $args = array(), $comments = null ) { 
  2. global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop; 
  3.  
  4. $in_comment_loop = true; 
  5.  
  6. $comment_alt = $comment_thread_alt = 0; 
  7. $comment_depth = 1; 
  8.  
  9. $defaults = array( 
  10. walker => null,  
  11. 'max_depth' => '',  
  12. 'style' => 'ul',  
  13. 'callback' => null,  
  14. 'end-callback' => null,  
  15. 'type' => 'all',  
  16. 'page' => '',  
  17. 'per_page' => '',  
  18. 'avatar_size' => 32,  
  19. 'reverse_top_level' => null,  
  20. 'reverse_children' => '',  
  21. 'format' => current_theme_supports( 'html5', 'comment-list' ) ? 'html5' : 'xhtml',  
  22. 'short_ping' => false,  
  23. 'echo' => true,  
  24. ); 
  25.  
  26. $r = wp_parse_args( $args, $defaults ); 
  27.  
  28. /** 
  29. * Filters the arguments used in retrieving the comment list. 
  30. * @since 4.0.0 
  31. * @see wp_list_comments() 
  32. * @param array $r An array of arguments for displaying comments. 
  33. */ 
  34.  
  35. // Figure out what comments we'll be looping through ($_comments) 
  36. if ( null !== $comments ) { 
  37. $comments = (array) $comments; 
  38. if ( empty($comments) ) 
  39. return; 
  40. if ( 'all' != $r['type'] ) { 
  41. $comments_by_type = separate_comments($comments); 
  42. if ( empty($comments_by_type[$r['type']]) ) 
  43. return; 
  44. $_comments = $comments_by_type[$r['type']]; 
  45. } else { 
  46. $_comments = $comments; 
  47. } else { 
  48. /** 
  49. * If 'page' or 'per_page' has been passed, and does not match what's in $wp_query,  
  50. * perform a separate comment query and allow Walker_Comment to paginate. 
  51. */ 
  52. if ( $r['page'] || $r['per_page'] ) { 
  53. $current_cpage = get_query_var( 'cpage' ); 
  54. if ( ! $current_cpage ) { 
  55. $current_cpage = 'newest' === get_option( 'default_comments_page' ) ? 1 : $wp_query->max_num_comment_pages; 
  56.  
  57. $current_per_page = get_query_var( 'comments_per_page' ); 
  58. if ( $r['page'] != $current_cpage || $r['per_page'] != $current_per_page ) { 
  59. $comment_args = array( 
  60. 'post_id' => get_the_ID(),  
  61. 'orderby' => 'comment_date_gmt',  
  62. 'order' => 'ASC',  
  63. 'status' => 'approve',  
  64. ); 
  65.  
  66. if ( is_user_logged_in() ) { 
  67. $comment_args['include_unapproved'] = get_current_user_id(); 
  68. } else { 
  69. $commenter = wp_get_current_commenter(); 
  70. if ( $commenter['comment_author_email'] ) { 
  71. $comment_args['include_unapproved'] = $commenter['comment_author_email']; 
  72.  
  73. $comments = get_comments( $comment_args ); 
  74.  
  75. if ( 'all' != $r['type'] ) { 
  76. $comments_by_type = separate_comments( $comments ); 
  77. if ( empty( $comments_by_type[ $r['type'] ] ) ) { 
  78. return; 
  79.  
  80. $_comments = $comments_by_type[ $r['type'] ]; 
  81. } else { 
  82. $_comments = $comments; 
  83.  
  84. // Otherwise, fall back on the comments from `$wp_query->comments`. 
  85. } else { 
  86. if ( empty($wp_query->comments) ) 
  87. return; 
  88. if ( 'all' != $r['type'] ) { 
  89. if ( empty($wp_query->comments_by_type) ) 
  90. $wp_query->comments_by_type = separate_comments($wp_query->comments); 
  91. if ( empty($wp_query->comments_by_type[$r['type']]) ) 
  92. return; 
  93. $_comments = $wp_query->comments_by_type[$r['type']]; 
  94. } else { 
  95. $_comments = $wp_query->comments; 
  96.  
  97. if ( $wp_query->max_num_comment_pages ) { 
  98. $default_comments_page = get_option( 'default_comments_page' ); 
  99. $cpage = get_query_var( 'cpage' ); 
  100. if ( 'newest' === $default_comments_page ) { 
  101. $r['cpage'] = $cpage; 
  102.  
  103. /** 
  104. * When first page shows oldest comments, post permalink is the same as 
  105. * the comment permalink. 
  106. */ 
  107. } elseif ( $cpage == 1 ) { 
  108. $r['cpage'] = ''; 
  109. } else { 
  110. $r['cpage'] = $cpage; 
  111.  
  112. $r['page'] = 0; 
  113. $r['per_page'] = 0; 
  114.  
  115. if ( '' === $r['per_page'] && get_option( 'page_comments' ) ) { 
  116. $r['per_page'] = get_query_var('comments_per_page'); 
  117.  
  118. if ( empty($r['per_page']) ) { 
  119. $r['per_page'] = 0; 
  120. $r['page'] = 0; 
  121.  
  122. if ( '' === $r['max_depth'] ) { 
  123. if ( get_option('thread_comments') ) 
  124. $r['max_depth'] = get_option('thread_comments_depth'); 
  125. else 
  126. $r['max_depth'] = -1; 
  127.  
  128. if ( '' === $r['page'] ) { 
  129. if ( empty($overridden_cpage) ) { 
  130. $r['page'] = get_query_var('cpage'); 
  131. } else { 
  132. $threaded = ( -1 != $r['max_depth'] ); 
  133. $r['page'] = ( 'newest' == get_option('default_comments_page') ) ? get_comment_pages_count($_comments, $r['per_page'], $threaded) : 1; 
  134. set_query_var( 'cpage', $r['page'] ); 
  135. // Validation check 
  136. $r['page'] = intval($r['page']); 
  137. if ( 0 == $r['page'] && 0 != $r['per_page'] ) 
  138. $r['page'] = 1; 
  139.  
  140. if ( null === $r['reverse_top_level'] ) 
  141. $r['reverse_top_level'] = ( 'desc' == get_option('comment_order') ); 
  142.  
  143.  
  144. if ( empty( $r[walker] ) ) { 
  145. $walker = new Walker_Comment; 
  146. } else { 
  147. $walker = $r[walker]; 
  148.  
  149. $output = $walker->paged_walk( $_comments, $r['max_depth'], $r['page'], $r['per_page'], $r ); 
  150.  
  151. $in_comment_loop = false; 
  152.  
  153. if ( $r['echo'] ) { 
  154. echo $output; 
  155. } else { 
  156. return $output;