wp_list_comments( string|array $args = array(), WP_Comment[] $comments = null )
Displays a list of comments.
Description
Used in the comments.php template to list comments for a particular post.
See also
- WP_Query->comments
Parameters
- $args
-
(string|array) (Optional) Formatting options.
-
'walker'
(object) Instance of a Walker class to list comments. Default null. -
'max_depth'
(int) The maximum comments depth. -
'style'
(string) The style of list ordering. Accepts 'ul', 'ol', or 'div'. 'div' will result in no additional list markup. Default 'ul'. -
'callback'
(callable) Callback function to use. Default null. -
'end-callback'
(callable) Callback function to use at the end. Default null. -
'type'
(string) Type of comments to list. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'. Default 'all'. -
'page'
(int) Page ID to list comments for. -
'per_page'
(int) Number of comments to list per page. -
'avatar_size'
(int) Height and width dimensions of the avatar size. Default 32. -
'reverse_top_level'
(bool) Ordering of the listed comments. If true, will display newest comments first. Default null. -
'reverse_children'
(bool) Whether to reverse child comments in the list. Default null. -
'format'
(string) How to format the comments list. Accepts 'html5', 'xhtml'. Default 'html5' if the theme supports it. -
'short_ping'
(bool) Whether to output short pings. Default false. -
'echo'
(bool) Whether to echo the output or return it. Default true.
Default value: array()
-
'walker'
- $comments
-
(WP_Comment[]) (Optional) Array of WP_Comment objects.
Default value: null
Return
(void|string) Void if 'echo' argument is true, or no comments to list. Otherwise, HTML list of comments.
More Information
Default options for $args
$args = array( 'walker' => null, 'max_depth' => '', 'style' => 'ul', 'callback' => null, 'end-callback' => null, 'type' => 'all', 'page' => '', 'per_page' => '', 'avatar_size' => 32, 'reverse_top_level' => null, 'reverse_children' => '', 'format' => 'html5', // or 'xhtml' if no 'HTML5' theme support 'short_ping' => false, // @since 3.6 'echo' => true // boolean, default is true );
The ‘max_depth
‘, ‘per_page
‘, and ‘reverse_top_level
‘ parameters can be more easily controlled through the Discussion Settings Administration Panel but a theme can override those settings.
Source
File: wp-includes/comment-template.php
function wp_list_comments( $args = array(), $comments = null ) { global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop; $in_comment_loop = true; $comment_alt = 0; $comment_thread_alt = 0; $comment_depth = 1; $defaults = array( 'walker' => null, 'max_depth' => '', 'style' => 'ul', 'callback' => null, 'end-callback' => null, 'type' => 'all', 'page' => '', 'per_page' => '', 'avatar_size' => 32, 'reverse_top_level' => null, 'reverse_children' => '', 'format' => current_theme_supports( 'html5', 'comment-list' ) ? 'html5' : 'xhtml', 'short_ping' => false, 'echo' => true, ); $parsed_args = wp_parse_args( $args, $defaults ); /** * Filters the arguments used in retrieving the comment list. * * @since 4.0.0 * * @see wp_list_comments() * * @param array $parsed_args An array of arguments for displaying comments. */ $parsed_args = apply_filters( 'wp_list_comments_args', $parsed_args ); // Figure out what comments we'll be looping through ($_comments). if ( null !== $comments ) { $comments = (array) $comments; if ( empty( $comments ) ) { return; } if ( 'all' !== $parsed_args['type'] ) { $comments_by_type = separate_comments( $comments ); if ( empty( $comments_by_type[ $parsed_args['type'] ] ) ) { return; } $_comments = $comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $comments; } } else { /* * If 'page' or 'per_page' has been passed, and does not match what's in $wp_query, * perform a separate comment query and allow Walker_Comment to paginate. */ if ( $parsed_args['page'] || $parsed_args['per_page'] ) { $current_cpage = get_query_var( 'cpage' ); if ( ! $current_cpage ) { $current_cpage = 'newest' === get_option( 'default_comments_page' ) ? 1 : $wp_query->max_num_comment_pages; } $current_per_page = get_query_var( 'comments_per_page' ); if ( $parsed_args['page'] != $current_cpage || $parsed_args['per_page'] != $current_per_page ) { $comment_args = array( 'post_id' => get_the_ID(), 'orderby' => 'comment_date_gmt', 'order' => 'ASC', 'status' => 'approve', ); if ( is_user_logged_in() ) { $comment_args['include_unapproved'] = array( get_current_user_id() ); } else { $unapproved_email = wp_get_unapproved_comment_author_email(); if ( $unapproved_email ) { $comment_args['include_unapproved'] = array( $unapproved_email ); } } $comments = get_comments( $comment_args ); if ( 'all' !== $parsed_args['type'] ) { $comments_by_type = separate_comments( $comments ); if ( empty( $comments_by_type[ $parsed_args['type'] ] ) ) { return; } $_comments = $comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $comments; } } // Otherwise, fall back on the comments from `$wp_query->comments`. } else { if ( empty( $wp_query->comments ) ) { return; } if ( 'all' !== $parsed_args['type'] ) { if ( empty( $wp_query->comments_by_type ) ) { $wp_query->comments_by_type = separate_comments( $wp_query->comments ); } if ( empty( $wp_query->comments_by_type[ $parsed_args['type'] ] ) ) { return; } $_comments = $wp_query->comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $wp_query->comments; } if ( $wp_query->max_num_comment_pages ) { $default_comments_page = get_option( 'default_comments_page' ); $cpage = get_query_var( 'cpage' ); if ( 'newest' === $default_comments_page ) { $parsed_args['cpage'] = $cpage; /* * When first page shows oldest comments, post permalink is the same as * the comment permalink. */ } elseif ( 1 == $cpage ) { $parsed_args['cpage'] = ''; } else { $parsed_args['cpage'] = $cpage; } $parsed_args['page'] = 0; $parsed_args['per_page'] = 0; } } } if ( '' === $parsed_args['per_page'] && get_option( 'page_comments' ) ) { $parsed_args['per_page'] = get_query_var( 'comments_per_page' ); } if ( empty( $parsed_args['per_page'] ) ) { $parsed_args['per_page'] = 0; $parsed_args['page'] = 0; } if ( '' === $parsed_args['max_depth'] ) { if ( get_option( 'thread_comments' ) ) { $parsed_args['max_depth'] = get_option( 'thread_comments_depth' ); } else { $parsed_args['max_depth'] = -1; } } if ( '' === $parsed_args['page'] ) { if ( empty( $overridden_cpage ) ) { $parsed_args['page'] = get_query_var( 'cpage' ); } else { $threaded = ( -1 != $parsed_args['max_depth'] ); $parsed_args['page'] = ( 'newest' === get_option( 'default_comments_page' ) ) ? get_comment_pages_count( $_comments, $parsed_args['per_page'], $threaded ) : 1; set_query_var( 'cpage', $parsed_args['page'] ); } } // Validation check. $parsed_args['page'] = (int) $parsed_args['page']; if ( 0 == $parsed_args['page'] && 0 != $parsed_args['per_page'] ) { $parsed_args['page'] = 1; } if ( null === $parsed_args['reverse_top_level'] ) { $parsed_args['reverse_top_level'] = ( 'desc' === get_option( 'comment_order' ) ); } wp_queue_comments_for_comment_meta_lazyload( $_comments ); if ( empty( $parsed_args['walker'] ) ) { $walker = new Walker_Comment; } else { $walker = $parsed_args['walker']; } $output = $walker->paged_walk( $_comments, $parsed_args['max_depth'], $parsed_args['page'], $parsed_args['per_page'], $parsed_args ); $in_comment_loop = false; if ( $parsed_args['echo'] ) { echo $output; } else { return $output; } }
Changelog
Version | Description |
---|---|
2.7.0 | Introduced. |
© 2003–2021 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/wp_list_comments