diff -r 3d4e9c994f10 -r a86126ab1dd4 wp/wp-includes/comment-template.php --- a/wp/wp-includes/comment-template.php Tue Oct 22 16:11:46 2019 +0200 +++ b/wp/wp-includes/comment-template.php Tue Dec 15 13:49:49 2020 +0100 @@ -9,7 +9,7 @@ */ /** - * Retrieve the author of the current comment. + * Retrieves the author of the current comment. * * If the comment has an empty comment_author field, then 'Anonymous' person is * assumed. @@ -25,7 +25,8 @@ $comment = get_comment( $comment_ID ); if ( empty( $comment->comment_author ) ) { - if ( $comment->user_id && $user = get_userdata( $comment->user_id ) ) { + $user = $comment->user_id ? get_userdata( $comment->user_id ) : false; + if ( $user ) { $author = $user->display_name; } else { $author = __( 'Anonymous' ); @@ -73,7 +74,7 @@ } /** - * Retrieve the email of the author of the current comment. + * Retrieves the email of the author of the current comment. * * @since 1.5.0 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. @@ -99,7 +100,7 @@ } /** - * Display the email of the author of the current global $comment. + * Displays the email of the author of the current global $comment. * * Care should be taken to protect the email address and assure that email * harvesters do not capture your commenter's email address. Most assume that @@ -130,7 +131,7 @@ } /** - * Display the html email link to the author of the current comment. + * Displays the HTML email link to the author of the current comment. * * Care should be taken to protect the email address and assure that email * harvesters do not capture your commenter's email address. Most assume that @@ -148,13 +149,14 @@ * @param int|WP_Comment $comment Optional. Comment ID or WP_Comment object. Default is the current comment. */ function comment_author_email_link( $linktext = '', $before = '', $after = '', $comment = null ) { - if ( $link = get_comment_author_email_link( $linktext, $before, $after, $comment ) ) { + $link = get_comment_author_email_link( $linktext, $before, $after, $comment ); + if ( $link ) { echo $link; } } /** - * Return the html email link to the author of the current comment. + * Returns the HTML email link to the author of the current comment. * * Care should be taken to protect the email address and assure that email * harvesters do not capture your commenter's email address. Most assume that @@ -190,8 +192,8 @@ */ $email = apply_filters( 'comment_email', $comment->comment_author_email, $comment ); - if ( ( ! empty( $email ) ) && ( $email != '@' ) ) { - $display = ( $linktext != '' ) ? $linktext : $email; + if ( ( ! empty( $email ) ) && ( '@' !== $email ) ) { + $display = ( '' !== $linktext ) ? $linktext : $email; $return = $before; $return .= sprintf( '%2$s', esc_url( 'mailto:' . $email ), esc_html( $display ) ); $return .= $after; @@ -202,7 +204,7 @@ } /** - * Retrieve the HTML link to the URL of the author of the current comment. + * Retrieves the HTML link to the URL of the author of the current comment. * * Both get_comment_author_url() and get_comment_author() rely on get_comment(), * which falls back to the global comment variable if the $comment_ID argument is empty. @@ -219,10 +221,10 @@ $url = get_comment_author_url( $comment ); $author = get_comment_author( $comment ); - if ( empty( $url ) || 'http://' == $url ) { + if ( empty( $url ) || 'http://' === $url ) { $return = $author; } else { - $return = "$author"; + $return = "$author"; } /** @@ -240,7 +242,7 @@ } /** - * Display the html link to the url of the author of the current comment. + * Displays the HTML link to the URL of the author of the current comment. * * @since 0.71 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. @@ -262,7 +264,7 @@ * Default current comment. * @return string Comment author's IP address. */ -function get_comment_author_IP( $comment_ID = 0 ) { +function get_comment_author_IP( $comment_ID = 0 ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid $comment = get_comment( $comment_ID ); /** @@ -275,11 +277,11 @@ * @param int $comment_ID The comment ID. * @param WP_Comment $comment The comment object. */ - return apply_filters( 'get_comment_author_IP', $comment->comment_author_IP, $comment->comment_ID, $comment ); + return apply_filters( 'get_comment_author_IP', $comment->comment_author_IP, $comment->comment_ID, $comment ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.NotLowercase } /** - * Display the IP address of the author of the current comment. + * Displays the IP address of the author of the current comment. * * @since 0.71 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. @@ -287,26 +289,27 @@ * @param int|WP_Comment $comment_ID Optional. WP_Comment or the ID of the comment for which to print the author's IP address. * Default current comment. */ -function comment_author_IP( $comment_ID = 0 ) { +function comment_author_IP( $comment_ID = 0 ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid echo esc_html( get_comment_author_IP( $comment_ID ) ); } /** - * Retrieve the url of the author of the current comment. + * Retrieves the URL of the author of the current comment, not linked. * * @since 1.5.0 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. * * @param int|WP_Comment $comment_ID Optional. WP_Comment or the ID of the comment for which to get the author's URL. * Default current comment. - * @return string Comment author URL. + * @return string Comment author URL, if provided, an empty string otherwise. */ function get_comment_author_url( $comment_ID = 0 ) { $comment = get_comment( $comment_ID ); $url = ''; $id = 0; + if ( ! empty( $comment ) ) { - $author_url = ( 'http://' == $comment->comment_author_url ) ? '' : $comment->comment_author_url; + $author_url = ( 'http://' === $comment->comment_author_url ) ? '' : $comment->comment_author_url; $url = esc_url( $author_url, array( 'http', 'https' ) ); $id = $comment->comment_ID; } @@ -325,7 +328,7 @@ } /** - * Display the url of the author of the current comment. + * Displays the URL of the author of the current comment, not linked. * * @since 0.71 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. @@ -350,7 +353,7 @@ } /** - * Retrieves the HTML link of the url of the author of the current comment. + * Retrieves the HTML link of the URL of the author of the current comment. * * $linktext parameter is only used if the URL does not exist for the comment * author. If the URL does exist then the URL will be used and the $linktext @@ -374,11 +377,11 @@ */ function get_comment_author_url_link( $linktext = '', $before = '', $after = '', $comment = 0 ) { $url = get_comment_author_url( $comment ); - $display = ( $linktext != '' ) ? $linktext : $url; + $display = ( '' !== $linktext ) ? $linktext : $url; $display = str_replace( 'http://www.', '', $display ); $display = str_replace( 'http://', '', $display ); - if ( '/' == substr( $display, -1 ) ) { + if ( '/' === substr( $display, -1 ) ) { $display = substr( $display, 0, -1 ); } @@ -395,7 +398,7 @@ } /** - * Displays the HTML link of the url of the author of the current comment. + * Displays the HTML link of the URL of the author of the current comment. * * @since 0.71 * @since 4.6.0 Added the `$comment` parameter. @@ -423,13 +426,14 @@ * Default empty. * @param int|WP_Comment $comment Comment ID or WP_Comment object. Default current comment. * @param int|WP_Post $post_id Post ID or WP_Post object. Default current post. - * @param bool $echo Optional. Whether to cho or return the output. + * @param bool $echo Optional. Whether to echo or return the output. * Default true. - * @return string If `$echo` is false, the class will be returned. Void otherwise. + * @return void|string Void if `$echo` argument is true, comment classes if `$echo` is false. */ function comment_class( $class = '', $comment = null, $post_id = null, $echo = true ) { - // Separates classes with a single space, collates classes for comment DIV + // Separates classes with a single space, collates classes for comment DIV. $class = 'class="' . join( ' ', get_comment_class( $class, $comment, $post_id ) ) . '"'; + if ( $echo ) { echo $class; } else { @@ -450,7 +454,7 @@ * @param string|array $class Optional. One or more classes to add to the class list. Default empty. * @param int|WP_Comment $comment_id Comment ID or WP_Comment object. Default current comment. * @param int|WP_Post $post_id Post ID or WP_Post object. Default current post. - * @return array An array of classes. + * @return string[] An array of classes. */ function get_comment_class( $class = '', $comment_id = null, $post_id = null ) { global $comment_alt, $comment_depth, $comment_thread_alt; @@ -462,15 +466,17 @@ return $classes; } - // Get the comment type (comment, trackback), + // Get the comment type (comment, trackback). $classes[] = ( empty( $comment->comment_type ) ) ? 'comment' : $comment->comment_type; // Add classes for comment authors that are registered users. - if ( $comment->user_id > 0 && $user = get_userdata( $comment->user_id ) ) { + $user = $comment->user_id ? get_userdata( $comment->user_id ) : false; + if ( $user ) { $classes[] = 'byuser'; $classes[] = 'comment-author-' . sanitize_html_class( $user->user_nicename, $comment->user_id ); - // For comment authors who are the author of the post - if ( $post = get_post( $post_id ) ) { + // For comment authors who are the author of the post. + $post = get_post( $post_id ); + if ( $post ) { if ( $comment->user_id === $post->post_author ) { $classes[] = 'bypostauthor'; } @@ -496,7 +502,7 @@ $comment_alt++; - // Alt for top-level comments + // Alt for top-level comments. if ( 1 == $comment_depth ) { if ( $comment_thread_alt % 2 ) { $classes[] = 'thread-odd'; @@ -525,7 +531,7 @@ * * @param string[] $classes An array of comment classes. * @param string $class A comma-separated list of additional classes added to the list. - * @param int $comment_id The comment id. + * @param int $comment_id The comment ID. * @param WP_Comment $comment The comment object. * @param int|WP_Post $post_id The post ID or WP_Post object. */ @@ -533,86 +539,84 @@ } /** - * Retrieve the comment date of the current comment. + * Retrieves the comment date of the current comment. * * @since 1.5.0 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. * - * @param string $d Optional. The format of the date. Default user's setting. - * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to get the date. - * Default current comment. + * @param string $format Optional. The format of the date. Default user's setting. + * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to get the date. + * Default current comment. * @return string The comment's date. */ -function get_comment_date( $d = '', $comment_ID = 0 ) { +function get_comment_date( $format = '', $comment_ID = 0 ) { $comment = get_comment( $comment_ID ); - if ( '' == $d ) { - $date = mysql2date( get_option( 'date_format' ), $comment->comment_date ); - } else { - $date = mysql2date( $d, $comment->comment_date ); - } + + $_format = ! empty( $format ) ? $format : get_option( 'date_format' ); + + $date = mysql2date( $_format, $comment->comment_date ); + /** * Filters the returned comment date. * * @since 1.5.0 * * @param string|int $date Formatted date string or Unix timestamp. - * @param string $d The format of the date. + * @param string $format The format of the date. * @param WP_Comment $comment The comment object. */ - return apply_filters( 'get_comment_date', $date, $d, $comment ); + return apply_filters( 'get_comment_date', $date, $format, $comment ); } /** - * Display the comment date of the current comment. + * Displays the comment date of the current comment. * * @since 0.71 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. * - * @param string $d Optional. The format of the date. Default user's settings. + * @param string $format Optional. The format of the date. Default user's settings. * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to print the date. * Default current comment. */ -function comment_date( $d = '', $comment_ID = 0 ) { - echo get_comment_date( $d, $comment_ID ); +function comment_date( $format = '', $comment_ID = 0 ) { + echo get_comment_date( $format, $comment_ID ); } /** - * Retrieve the excerpt of the current comment. + * Retrieves the excerpt of the given comment. * - * Will cut each word and only output the first 20 words with '…' at the end. - * If the word count is less than 20, then no truncating is done and no '…' - * will appear. + * Returns a maximum of 20 words with an ellipsis appended if necessary. * * @since 1.5.0 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. * * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to get the excerpt. * Default current comment. - * @return string The maybe truncated comment with 20 words or less. + * @return string The possibly truncated comment excerpt. */ function get_comment_excerpt( $comment_ID = 0 ) { - $comment = get_comment( $comment_ID ); - $comment_text = strip_tags( str_replace( array( "\n", "\r" ), ' ', $comment->comment_content ) ); - $words = explode( ' ', $comment_text ); + $comment = get_comment( $comment_ID ); + + if ( ! post_password_required( $comment->comment_post_ID ) ) { + $comment_text = strip_tags( str_replace( array( "\n", "\r" ), ' ', $comment->comment_content ) ); + } else { + $comment_text = __( 'Password protected' ); + } + + /* translators: Maximum number of words used in a comment excerpt. */ + $comment_excerpt_length = intval( _x( '20', 'comment_excerpt_length' ) ); /** - * Filters the amount of words used in the comment excerpt. + * Filters the maximum number of words used in the comment excerpt. * * @since 4.4.0 * * @param int $comment_excerpt_length The amount of words you want to display in the comment excerpt. */ - $comment_excerpt_length = apply_filters( 'comment_excerpt_length', 20 ); + $comment_excerpt_length = apply_filters( 'comment_excerpt_length', $comment_excerpt_length ); - $use_ellipsis = count( $words ) > $comment_excerpt_length; - if ( $use_ellipsis ) { - $words = array_slice( $words, 0, $comment_excerpt_length ); - } + $excerpt = wp_trim_words( $comment_text, $comment_excerpt_length, '…' ); - $excerpt = trim( join( ' ', $words ) ); - if ( $use_ellipsis ) { - $excerpt .= '…'; - } /** * Filters the retrieved comment excerpt. * @@ -627,7 +631,7 @@ } /** - * Display the excerpt of the current comment. + * Displays the excerpt of the current comment. * * @since 1.2.0 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. @@ -652,13 +656,13 @@ } /** - * Retrieve the comment id of the current comment. + * Retrieves the comment ID of the current comment. * * @since 1.5.0 * * @return int The comment ID. */ -function get_comment_ID() { +function get_comment_ID() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid $comment = get_comment(); /** @@ -670,27 +674,27 @@ * @param int $comment_ID The current comment ID. * @param WP_Comment $comment The comment object. */ - return apply_filters( 'get_comment_ID', $comment->comment_ID, $comment ); + return apply_filters( 'get_comment_ID', $comment->comment_ID, $comment ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.NotLowercase } /** - * Display the comment id of the current comment. + * Displays the comment ID of the current comment. * * @since 0.71 */ -function comment_ID() { +function comment_ID() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid echo get_comment_ID(); } /** - * Retrieve the link to a given comment. + * Retrieves the link to a given comment. * * @since 1.5.0 * @since 4.4.0 Added the ability for `$comment` to also accept a WP_Comment object. Added `$cpage` argument. * * @see get_page_of_comment() * - * @global WP_Rewrite $wp_rewrite + * @global WP_Rewrite $wp_rewrite WordPress rewrite component. * @global bool $in_comment_loop * * @param WP_Comment|int|null $comment Comment to retrieve. Default current comment. @@ -821,7 +825,7 @@ } /** - * Display the link to the current post comments. + * Displays the link to the current post comments. * * @since 0.71 * @@ -869,51 +873,53 @@ } /** - * Display the language string for the number of comments the current post has. + * Displays the language string for the number of comments the current post has. * * @since 0.71 + * @since 5.4.0 The `$deprecated` parameter was changed to `$post_id`. * - * @param string $zero Optional. Text for no comments. Default false. - * @param string $one Optional. Text for one comment. Default false. - * @param string $more Optional. Text for more than one comment. Default false. - * @param string $deprecated Not used. + * @param string $zero Optional. Text for no comments. Default false. + * @param string $one Optional. Text for one comment. Default false. + * @param string $more Optional. Text for more than one comment. Default false. + * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default is the global `$post`. */ -function comments_number( $zero = false, $one = false, $more = false, $deprecated = '' ) { - if ( ! empty( $deprecated ) ) { - _deprecated_argument( __FUNCTION__, '1.3.0' ); - } - echo get_comments_number_text( $zero, $one, $more ); +function comments_number( $zero = false, $one = false, $more = false, $post_id = 0 ) { + echo get_comments_number_text( $zero, $one, $more, $post_id ); } /** - * Display the language string for the number of comments the current post has. + * Displays the language string for the number of comments the current post has. * * @since 4.0.0 + * @since 5.4.0 Added the `$post_id` parameter to allow using the function outside of the loop. * - * @param string $zero Optional. Text for no comments. Default false. - * @param string $one Optional. Text for one comment. Default false. - * @param string $more Optional. Text for more than one comment. Default false. + * @param string $zero Optional. Text for no comments. Default false. + * @param string $one Optional. Text for one comment. Default false. + * @param string $more Optional. Text for more than one comment. Default false. + * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default is the global `$post`. + * @return string Language string for the number of comments a post has. */ -function get_comments_number_text( $zero = false, $one = false, $more = false ) { - $number = get_comments_number(); +function get_comments_number_text( $zero = false, $one = false, $more = false, $post_id = 0 ) { + $number = get_comments_number( $post_id ); if ( $number > 1 ) { if ( false === $more ) { - /* translators: %s: number of comments */ + /* translators: %s: Number of comments. */ $output = sprintf( _n( '%s Comment', '%s Comments', $number ), number_format_i18n( $number ) ); } else { // % Comments - /* translators: If comment number in your language requires declension, + /* + * translators: If comment number in your language requires declension, * translate this to 'on'. Do not translate into your own language. */ if ( 'on' === _x( 'off', 'Comment number declension: on or off' ) ) { $text = preg_replace( '#.+?#', '', $more ); - $text = preg_replace( '/&.+?;/', '', $text ); // Kill entities + $text = preg_replace( '/&.+?;/', '', $text ); // Kill entities. $text = trim( strip_tags( $text ), '% ' ); - // Replace '% Comments' with a proper plural form + // Replace '% Comments' with a proper plural form. if ( $text && ! preg_match( '/[0-9]+/', $text ) && false !== strpos( $more, '%' ) ) { - /* translators: %s: number of comments */ + /* translators: %s: Number of comments. */ $new_text = _n( '%s Comment', '%s Comments', $number ); $new_text = trim( sprintf( $new_text, '' ) ); @@ -926,9 +932,9 @@ $output = str_replace( '%', number_format_i18n( $number ), $more ); } - } elseif ( $number == 0 ) { + } elseif ( 0 == $number ) { $output = ( false === $zero ) ? __( 'No Comments' ) : $zero; - } else { // must be one + } else { // Must be one. $output = ( false === $one ) ? __( '1 Comment' ) : $one; } /** @@ -946,21 +952,38 @@ } /** - * Retrieve the text of the current comment. + * Retrieves the text of the current comment. * * @since 1.5.0 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. + * @since 5.4.0 Added 'In reply to %s.' prefix to child comments in comments feed. * * @see Walker_Comment::comment() * - * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to get the text. - * Default current comment. - * @param array $args Optional. An array of arguments. Default empty. + * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to get the text. + * Default current comment. + * @param array $args Optional. An array of arguments. Default empty array. * @return string The comment content. */ function get_comment_text( $comment_ID = 0, $args = array() ) { $comment = get_comment( $comment_ID ); + $comment_content = $comment->comment_content; + + if ( is_comment_feed() && $comment->comment_parent ) { + $parent = get_comment( $comment->comment_parent ); + if ( $parent ) { + $parent_link = esc_url( get_comment_link( $parent ) ); + $name = get_comment_author( $parent ); + + $comment_content = sprintf( + /* translators: %s: Comment link. */ + ent2ncr( __( 'In reply to %s.' ) ), + '' . $name . '' + ) . "\n\n" . $comment_content; + } + } + /** * Filters the text of a comment. * @@ -972,20 +995,20 @@ * @param WP_Comment $comment The comment object. * @param array $args An array of arguments. */ - return apply_filters( 'get_comment_text', $comment->comment_content, $comment, $args ); + return apply_filters( 'get_comment_text', $comment_content, $comment, $args ); } /** - * Display the text of the current comment. + * Displays the text of the current comment. * * @since 0.71 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. * * @see Walker_Comment::comment() * - * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to print the text. - * Default current comment. - * @param array $args Optional. An array of arguments. Default empty array. Default empty. + * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to print the text. + * Default current comment. + * @param array $args Optional. An array of arguments. Default empty array. */ function comment_text( $comment_ID = 0, $args = array() ) { $comment = get_comment( $comment_ID ); @@ -999,32 +1022,31 @@ * @see Walker_Comment::comment() * * @param string $comment_text Text of the current comment. - * @param WP_Comment|null $comment The comment object. + * @param WP_Comment|null $comment The comment object. Null if not found. * @param array $args An array of arguments. */ echo apply_filters( 'comment_text', $comment_text, $comment, $args ); } /** - * Retrieve the comment time of the current comment. + * Retrieves the comment time of the current comment. * * @since 1.5.0 * - * @param string $d Optional. The format of the time. Default user's settings. + * @param string $format Optional. The format of the time. Default user's settings. * @param bool $gmt Optional. Whether to use the GMT date. Default false. * @param bool $translate Optional. Whether to translate the time (for use in feeds). * Default true. * @return string The formatted time. */ -function get_comment_time( $d = '', $gmt = false, $translate = true ) { +function get_comment_time( $format = '', $gmt = false, $translate = true ) { $comment = get_comment(); $comment_date = $gmt ? $comment->comment_date_gmt : $comment->comment_date; - if ( '' == $d ) { - $date = mysql2date( get_option( 'time_format' ), $comment_date, $translate ); - } else { - $date = mysql2date( $d, $comment_date, $translate ); - } + + $_format = ! empty( $format ) ? $format : get_option( 'time_format' ); + + $date = mysql2date( $_format, $comment_date, $translate ); /** * Filters the returned comment time. @@ -1032,27 +1054,27 @@ * @since 1.5.0 * * @param string|int $date The comment time, formatted as a date string or Unix timestamp. - * @param string $d Date format. + * @param string $format Date format. * @param bool $gmt Whether the GMT date is in use. * @param bool $translate Whether the time is translated. * @param WP_Comment $comment The comment object. */ - return apply_filters( 'get_comment_time', $date, $d, $gmt, $translate, $comment ); + return apply_filters( 'get_comment_time', $date, $format, $gmt, $translate, $comment ); } /** - * Display the comment time of the current comment. + * Displays the comment time of the current comment. * * @since 0.71 * - * @param string $d Optional. The format of the time. Default user's settings. + * @param string $format Optional. The format of the time. Default user's settings. */ -function comment_time( $d = '' ) { - echo get_comment_time( $d ); +function comment_time( $format = '' ) { + echo get_comment_time( $format ); } /** - * Retrieve the comment type of the current comment. + * Retrieves the comment type of the current comment. * * @since 1.5.0 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. @@ -1063,7 +1085,8 @@ */ function get_comment_type( $comment_ID = 0 ) { $comment = get_comment( $comment_ID ); - if ( '' == $comment->comment_type ) { + + if ( '' === $comment->comment_type ) { $comment->comment_type = 'comment'; } @@ -1081,7 +1104,7 @@ } /** - * Display the comment type of the current comment. + * Displays the comment type of the current comment. * * @since 0.71 * @@ -1113,7 +1136,7 @@ } /** - * Retrieve The current post's trackback URL. + * Retrieves the current post's trackback URL. * * There is a check to see if permalink's have been enabled and if so, will * retrieve the pretty path. If permalinks weren't enabled, the ID of the @@ -1124,7 +1147,7 @@ * @return string The trackback URL after being filtered. */ function get_trackback_url() { - if ( '' != get_option( 'permalink_structure' ) ) { + if ( get_option( 'permalink_structure' ) ) { $tb_url = trailingslashit( get_permalink() ) . user_trailingslashit( 'trackback', 'single_trackback' ); } else { $tb_url = get_option( 'siteurl' ) . '/wp-trackback.php?p=' . get_the_ID(); @@ -1141,7 +1164,7 @@ } /** - * Display the current post's trackback URL. + * Displays the current post's trackback URL. * * @since 0.71 * @@ -1154,8 +1177,8 @@ _deprecated_argument( __FUNCTION__, '2.5.0', - /* translators: %s: get_trackback_url() */ sprintf( + /* translators: %s: get_trackback_url() */ __( 'Use %s instead if you do not want the value echoed.' ), 'get_trackback_url()' ) @@ -1170,7 +1193,7 @@ } /** - * Generate and display the RDF for the trackback information of current post. + * Generates and displays the RDF for the trackback information of current post. * * Deprecated in 3.0.0, and restored in 3.0.1. * @@ -1218,7 +1241,7 @@ $_post = get_post( $post_id ); $post_id = $_post ? $_post->ID : 0; - $open = ( 'open' == $_post->comment_status ); + $open = ( 'open' === $_post->comment_status ); /** * Filters whether the current post is open for comments. @@ -1248,7 +1271,7 @@ $_post = get_post( $post_id ); $post_id = $_post ? $_post->ID : 0; - $open = ( 'open' == $_post->ping_status ); + $open = ( 'open' === $_post->ping_status ); /** * Filters whether the current post is open for pings. @@ -1262,7 +1285,7 @@ } /** - * Display form token for unfiltered comments. + * Displays form token for unfiltered comments. * * Will only display nonce token if the current user has permissions for * unfiltered html. Won't display the token for other users. @@ -1286,7 +1309,7 @@ } /** - * Load the comment template specified in $file. + * Loads the comment template specified in $file. * * Will not display the comments template if not on single post or page, or if * the post does not have comments. @@ -1305,13 +1328,12 @@ * * @since 1.5.0 * - * @global WP_Query $wp_query - * @global WP_Post $post - * @global wpdb $wpdb + * @global WP_Query $wp_query WordPress Query object. + * @global WP_Post $post Global post object. + * @global wpdb $wpdb WordPress database abstraction object. * @global int $id - * @global WP_Comment $comment + * @global WP_Comment $comment Global comment object. * @global string $user_login - * @global int $user_ID * @global string $user_identity * @global bool $overridden_cpage * @global bool $withcomments @@ -1321,7 +1343,7 @@ * Default false. */ function comments_template( $file = '/comments.php', $separate_comments = false ) { - global $wp_query, $withcomments, $post, $wpdb, $id, $comment, $user_login, $user_ID, $user_identity, $overridden_cpage; + global $wp_query, $withcomments, $post, $wpdb, $id, $comment, $user_login, $user_identity, $overridden_cpage; if ( ! ( is_single() || is_page() || $withcomments ) || empty( $post ) ) { return; @@ -1351,7 +1373,7 @@ $comment_author_email = $commenter['comment_author_email']; /* - * The url of the current comment author escaped for use in attributes. + * The URL of the current comment author escaped for use in attributes. */ $comment_author_url = esc_url( $commenter['comment_author_url'] ); @@ -1370,8 +1392,8 @@ $comment_args['hierarchical'] = false; } - if ( $user_ID ) { - $comment_args['include_unapproved'] = array( $user_ID ); + if ( is_user_logged_in() ) { + $comment_args['include_unapproved'] = array( get_current_user_id() ); } else { $unapproved_email = wp_get_unapproved_comment_author_email(); @@ -1488,8 +1510,9 @@ } $overridden_cpage = false; + if ( '' == get_query_var( 'cpage' ) && $wp_query->max_num_comment_pages > 1 ) { - set_query_var( 'cpage', 'newest' == get_option( 'default_comments_page' ) ? get_comment_pages_count() : 1 ); + set_query_var( 'cpage', 'newest' === get_option( 'default_comments_page' ) ? get_comment_pages_count() : 1 ); $overridden_cpage = true; } @@ -1498,6 +1521,7 @@ } $theme_template = STYLESHEETPATH . $file; + /** * Filters the path to the theme template file used for the comments template. * @@ -1506,12 +1530,13 @@ * @param string $theme_template The path to the theme template file. */ $include = apply_filters( 'comments_template', $theme_template ); + if ( file_exists( $include ) ) { - require( $include ); + require $include; } elseif ( file_exists( TEMPLATEPATH . $file ) ) { - require( TEMPLATEPATH . $file ); - } else { // Backward compat code will be removed in a future release - require( ABSPATH . WPINC . '/theme-compat/comments.php' ); + require TEMPLATEPATH . $file; + } else { // Backward compat code will be removed in a future release. + require ABSPATH . WPINC . '/theme-compat/comments.php'; } } @@ -1527,29 +1552,29 @@ * @param false|string $none Optional. String to display when comments have been turned off. Default false. */ function comments_popup_link( $zero = false, $one = false, $more = false, $css_class = '', $none = false ) { - $id = get_the_ID(); - $title = get_the_title(); - $number = get_comments_number( $id ); + $post_id = get_the_ID(); + $post_title = get_the_title(); + $number = get_comments_number( $post_id ); if ( false === $zero ) { - /* translators: %s: post title */ - $zero = sprintf( __( 'No Comments on %s' ), $title ); + /* translators: %s: Post title. */ + $zero = sprintf( __( 'No Comments on %s' ), $post_title ); } if ( false === $one ) { - /* translators: %s: post title */ - $one = sprintf( __( '1 Comment on %s' ), $title ); + /* translators: %s: Post title. */ + $one = sprintf( __( '1 Comment on %s' ), $post_title ); } if ( false === $more ) { - /* translators: 1: number of comments, 2: post title */ + /* translators: 1: Number of comments, 2: Post title. */ $more = _n( '%1$s Comment on %2$s', '%1$s Comments on %2$s', $number ); - $more = sprintf( $more, number_format_i18n( $number ), $title ); + $more = sprintf( $more, number_format_i18n( $number ), $post_title ); } if ( false === $none ) { - /* translators: %s: post title */ - $none = sprintf( __( 'Comments Off on %s' ), $title ); + /* translators: %s: Post title. */ + $none = sprintf( __( 'Comments Off on %s' ), $post_title ); } if ( 0 == $number && ! comments_open() && ! pings_open() ) { @@ -1571,9 +1596,9 @@ * @since 4.4.0 * * @param string $respond_link The default response link. - * @param integer $id The post ID. + * @param int $post_id The post ID. */ - echo apply_filters( 'respond_link', $respond_link, $id ); + echo apply_filters( 'respond_link', $respond_link, $post_id ); } else { comments_link(); } @@ -1599,12 +1624,12 @@ } /** - * Retrieve HTML content for reply to comment link. + * Retrieves HTML content for reply to comment link. * * @since 2.7.0 * @since 4.4.0 Added the ability for `$comment` to also accept a WP_Comment object. * - * @param array $args { + * @param array $args { * Optional. Override default arguments. * * @type string $add_below The first part of the selector used to identify the comment to respond below. @@ -1624,14 +1649,14 @@ * @param int|WP_Comment $comment Comment being replied to. Default current comment. * @param int|WP_Post $post Post ID or WP_Post object the comment is going to be displayed on. * Default current post. - * @return void|false|string Link to show comment form, if successful. False, if comments are closed. + * @return string|false|null Link to show comment form, if successful. False, if comments are closed. */ function get_comment_reply_link( $args = array(), $comment = null, $post = null ) { $defaults = array( 'add_below' => 'comment', 'respond_id' => 'respond', 'reply_text' => __( 'Reply' ), - /* translators: Comment reply button text. %s: Comment author name */ + /* translators: Comment reply button text. %s: Comment author name. */ 'reply_to_text' => __( 'Reply to %s' ), 'login_text' => __( 'Log in to Reply' ), 'max_depth' => 0, @@ -1648,6 +1673,10 @@ $comment = get_comment( $comment ); + if ( empty( $comment ) ) { + return; + } + if ( empty( $post ) ) { $post = $comment->comment_post_ID; } @@ -1682,6 +1711,7 @@ 'postid' => $post->ID, 'belowelement' => $args['add_below'] . '-' . $comment->comment_ID, 'respondelement' => $args['respond_id'], + 'replyto' => sprintf( $args['reply_to_text'], $comment->comment_author ), ); $data_attribute_string = ''; @@ -1700,7 +1730,8 @@ 'replytocom' => $comment->comment_ID, 'unapproved' => false, 'moderation-hash' => false, - ) + ), + get_permalink( $post->ID ) ) ) . '#' . $args['respond_id'], $data_attribute_string, @@ -1714,10 +1745,10 @@ * * @since 2.7.0 * - * @param string $link The HTML markup for the comment reply link. - * @param array $args An array of arguments overriding the defaults. - * @param object $comment The object of the comment being replied. - * @param WP_Post $post The WP_Post object. + * @param string $link The HTML markup for the comment reply link. + * @param array $args An array of arguments overriding the defaults. + * @param WP_Comment $comment The object of the comment being replied. + * @param WP_Post $post The WP_Post object. */ return apply_filters( 'comment_reply_link', $args['before'] . $link . $args['after'], $args, $comment, $post ); } @@ -1729,22 +1760,21 @@ * * @see get_comment_reply_link() * - * @param array $args Optional. Override default options. - * @param int $comment Comment being replied to. Default current comment. - * @param int|WP_Post $post Post ID or WP_Post object the comment is going to be displayed on. - * Default current post. - * @return mixed Link to show comment form, if successful. False, if comments are closed. + * @param array $args Optional. Override default options. Default empty array. + * @param int|WP_Comment $comment Comment being replied to. Default current comment. + * @param int|WP_Post $post Post ID or WP_Post object the comment is going to be displayed on. + * Default current post. */ function comment_reply_link( $args = array(), $comment = null, $post = null ) { echo get_comment_reply_link( $args, $comment, $post ); } /** - * Retrieve HTML content for reply to post link. + * Retrieves HTML content for reply to post link. * * @since 2.7.0 * - * @param array $args { + * @param array $args { * Optional. Override default arguments. * * @type string $add_below The first part of the selector used to identify the comment to respond below. @@ -1760,7 +1790,7 @@ * } * @param int|WP_Post $post Optional. Post ID or WP_Post object the comment is going to be displayed on. * Default current post. - * @return false|null|string Link to show comment form, if successful. False, if comments are closed. + * @return string|false|null Link to show comment form, if successful. False, if comments are closed. */ function get_post_reply_link( $args = array(), $post = null ) { $defaults = array( @@ -1821,21 +1851,21 @@ * * @see get_post_reply_link() * - * @param array $args Optional. Override default options, + * @param array $args Optional. Override default options. Default empty array. * @param int|WP_Post $post Post ID or WP_Post object the comment is going to be displayed on. * Default current post. - * @return string|bool|null Link to show comment form, if successful. False, if comments are closed. */ function post_reply_link( $args = array(), $post = null ) { echo get_post_reply_link( $args, $post ); } /** - * Retrieve HTML content for cancel comment reply link. + * Retrieves HTML content for cancel comment reply link. * * @since 2.7.0 * - * @param string $text Optional. Text to display for cancel reply link. Default empty. + * @param string $text Optional. Text to display for cancel reply link. If empty, + * defaults to 'Click here to cancel reply'. Default empty. * @return string */ function get_cancel_comment_reply_link( $text = '' ) { @@ -1861,58 +1891,66 @@ } /** - * Display HTML content for cancel comment reply link. + * Displays HTML content for cancel comment reply link. * * @since 2.7.0 * - * @param string $text Optional. Text to display for cancel reply link. Default empty. + * @param string $text Optional. Text to display for cancel reply link. If empty, + * defaults to 'Click here to cancel reply'. Default empty. */ function cancel_comment_reply_link( $text = '' ) { echo get_cancel_comment_reply_link( $text ); } /** - * Retrieve hidden input HTML for replying to comments. + * Retrieves hidden input HTML for replying to comments. * * @since 3.0.0 * - * @param int $id Optional. Post ID. Default current post ID. - * @return string Hidden input HTML for replying to comments + * @param int $post_id Optional. Post ID. Defaults to the current post ID. + * @return string Hidden input HTML for replying to comments. */ -function get_comment_id_fields( $id = 0 ) { - if ( empty( $id ) ) { - $id = get_the_ID(); +function get_comment_id_fields( $post_id = 0 ) { + if ( empty( $post_id ) ) { + $post_id = get_the_ID(); } - $replytoid = isset( $_GET['replytocom'] ) ? (int) $_GET['replytocom'] : 0; - $result = "\n"; - $result .= "\n"; + $reply_to_id = isset( $_GET['replytocom'] ) ? (int) $_GET['replytocom'] : 0; + $result = "\n"; + $result .= "\n"; /** - * Filters the returned comment id fields. + * Filters the returned comment ID fields. * * @since 3.0.0 * - * @param string $result The HTML-formatted hidden id field comment elements. - * @param int $id The post ID. - * @param int $replytoid The id of the comment being replied to. + * @param string $result The HTML-formatted hidden ID field comment elements. + * @param int $post_id The post ID. + * @param int $reply_to_id The ID of the comment being replied to. */ - return apply_filters( 'comment_id_fields', $result, $id, $replytoid ); + return apply_filters( 'comment_id_fields', $result, $post_id, $reply_to_id ); } /** - * Output hidden input HTML for replying to comments. + * Outputs hidden input HTML for replying to comments. + * + * Adds two hidden inputs to the comment form to identify the `comment_post_ID` + * and `comment_parent` values for threaded comments. + * + * This tag must be within the `
` section of the `comments.php` template. * * @since 2.7.0 * - * @param int $id Optional. Post ID. Default current post ID. + * @see get_comment_id_fields() + * + * @param int $post_id Optional. Post ID. Defaults to the current post ID. */ -function comment_id_fields( $id = 0 ) { - echo get_comment_id_fields( $id ); +function comment_id_fields( $post_id = 0 ) { + echo get_comment_id_fields( $post_id ); } /** - * Display text based on comment reply status. + * Displays text based on comment reply status. * * Only affects users with JavaScript disabled. * @@ -1921,40 +1959,48 @@ * * @since 2.7.0 * - * @global WP_Comment $comment Current comment. + * @global WP_Comment $comment Global comment object. * - * @param string $noreplytext Optional. Text to display when not replying to a comment. - * Default false. - * @param string $replytext Optional. Text to display when replying to a comment. - * Default false. Accepts "%s" for the author of the comment - * being replied to. - * @param string $linktoparent Optional. Boolean to control making the author's name a link - * to their comment. Default true. + * @param string $no_reply_text Optional. Text to display when not replying to a comment. + * Default false. + * @param string $reply_text Optional. Text to display when replying to a comment. + * Default false. Accepts "%s" for the author of the comment + * being replied to. + * @param string $link_to_parent Optional. Boolean to control making the author's name a link + * to their comment. Default true. */ -function comment_form_title( $noreplytext = false, $replytext = false, $linktoparent = true ) { +function comment_form_title( $no_reply_text = false, $reply_text = false, $link_to_parent = true ) { global $comment; - if ( false === $noreplytext ) { - $noreplytext = __( 'Leave a Reply' ); + if ( false === $no_reply_text ) { + $no_reply_text = __( 'Leave a Reply' ); } - if ( false === $replytext ) { - $replytext = __( 'Leave a Reply to %s' ); + + if ( false === $reply_text ) { + /* translators: %s: Author of the comment being replied to. */ + $reply_text = __( 'Leave a Reply to %s' ); } - $replytoid = isset( $_GET['replytocom'] ) ? (int) $_GET['replytocom'] : 0; + $reply_to_id = isset( $_GET['replytocom'] ) ? (int) $_GET['replytocom'] : 0; - if ( 0 == $replytoid ) { - echo $noreplytext; + if ( 0 == $reply_to_id ) { + echo $no_reply_text; } else { // Sets the global so that template tags can be used in the comment form. - $comment = get_comment( $replytoid ); - $author = ( $linktoparent ) ? '' . get_comment_author( $comment ) . '' : get_comment_author( $comment ); - printf( $replytext, $author ); + $comment = get_comment( $reply_to_id ); + + if ( $link_to_parent ) { + $author = '' . get_comment_author( $comment ) . ''; + } else { + $author = get_comment_author( $comment ); + } + + printf( $reply_text, $author ); } } /** - * List comments. + * Displays a list of comments. * * Used in the comments.php template to list comments for a particular post. * @@ -1962,7 +2008,7 @@ * * @see WP_Query->comments * - * @global WP_Query $wp_query + * @global WP_Query $wp_query WordPress Query object. * @global int $comment_alt * @global int $comment_depth * @global int $comment_thread_alt @@ -1972,32 +2018,37 @@ * @param string|array $args { * Optional. Formatting options. * - * @type object $walker Instance of a Walker class to list comments. Default null. - * @type int $max_depth The maximum comments depth. Default empty. - * @type string $style The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'. - * @type string $callback Callback function to use. Default null. - * @type string $end-callback Callback function to use at the end. Default null. - * @type string $type Type of comments to list. - * Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'. - * @type int $page Page ID to list comments for. Default empty. - * @type int $per_page Number of comments to list per page. Default empty. - * @type int $avatar_size Height and width dimensions of the avatar size. Default 32. - * @type bool $reverse_top_level Ordering of the listed comments. If true, will display newest comments first. - * @type bool $reverse_children Whether to reverse child comments in the list. Default null. - * @type string $format How to format the comments list. - * Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'. - * @type bool $short_ping Whether to output short pings. Default false. - * @type bool $echo Whether to echo the output or return it. Default true. + * @type object $walker Instance of a Walker class to list comments. Default null. + * @type int $max_depth The maximum comments depth. Default empty. + * @type string $style The style of list ordering. Accepts 'ul', 'ol', or 'div'. + * 'div' will result in no additional list markup. Default 'ul'. + * @type callable $callback Callback function to use. Default null. + * @type callable $end-callback Callback function to use at the end. Default null. + * @type string $type Type of comments to list. Accepts 'all', 'comment', + * 'pingback', 'trackback', 'pings'. Default 'all'. + * @type int $page Page ID to list comments for. Default empty. + * @type int $per_page Number of comments to list per page. Default empty. + * @type int $avatar_size Height and width dimensions of the avatar size. Default 32. + * @type bool $reverse_top_level Ordering of the listed comments. If true, will display + * newest comments first. Default null. + * @type bool $reverse_children Whether to reverse child comments in the list. Default null. + * @type string $format How to format the comments list. Accepts 'html5', 'xhtml'. + * Default 'html5' if the theme supports it. + * @type bool $short_ping Whether to output short pings. Default false. + * @type bool $echo Whether to echo the output or return it. Default true. * } - * @param array $comments Optional. Array of WP_Comment objects. + * @param WP_Comment[] $comments Optional. Array of WP_Comment objects. + * @return void|string Void if 'echo' argument is true, or no comments to list. + * Otherwise, HTML list of comments. */ 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 = $comment_thread_alt = 0; - $comment_depth = 1; + $comment_alt = 0; + $comment_thread_alt = 0; + $comment_depth = 1; $defaults = array( 'walker' => null, @@ -2016,7 +2067,7 @@ 'echo' => true, ); - $r = wp_parse_args( $args, $defaults ); + $parsed_args = wp_parse_args( $args, $defaults ); /** * Filters the arguments used in retrieving the comment list. @@ -2025,22 +2076,22 @@ * * @see wp_list_comments() * - * @param array $r An array of arguments for displaying comments. + * @param array $parsed_args An array of arguments for displaying comments. */ - $r = apply_filters( 'wp_list_comments_args', $r ); + $parsed_args = apply_filters( 'wp_list_comments_args', $parsed_args ); - // Figure out what comments we'll be looping through ($_comments) + // Figure out what comments we'll be looping through ($_comments). if ( null !== $comments ) { $comments = (array) $comments; if ( empty( $comments ) ) { return; } - if ( 'all' != $r['type'] ) { + if ( 'all' !== $parsed_args['type'] ) { $comments_by_type = separate_comments( $comments ); - if ( empty( $comments_by_type[ $r['type'] ] ) ) { + if ( empty( $comments_by_type[ $parsed_args['type'] ] ) ) { return; } - $_comments = $comments_by_type[ $r['type'] ]; + $_comments = $comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $comments; } @@ -2049,14 +2100,14 @@ * 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 ( $r['page'] || $r['per_page'] ) { + 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 ( $r['page'] != $current_cpage || $r['per_page'] != $current_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', @@ -2065,7 +2116,7 @@ ); if ( is_user_logged_in() ) { - $comment_args['include_unapproved'] = get_current_user_id(); + $comment_args['include_unapproved'] = array( get_current_user_id() ); } else { $unapproved_email = wp_get_unapproved_comment_author_email(); @@ -2076,13 +2127,13 @@ $comments = get_comments( $comment_args ); - if ( 'all' != $r['type'] ) { + if ( 'all' !== $parsed_args['type'] ) { $comments_by_type = separate_comments( $comments ); - if ( empty( $comments_by_type[ $r['type'] ] ) ) { + if ( empty( $comments_by_type[ $parsed_args['type'] ] ) ) { return; } - $_comments = $comments_by_type[ $r['type'] ]; + $_comments = $comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $comments; } @@ -2093,14 +2144,14 @@ if ( empty( $wp_query->comments ) ) { return; } - if ( 'all' != $r['type'] ) { + 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[ $r['type'] ] ) ) { + if ( empty( $wp_query->comments_by_type[ $parsed_args['type'] ] ) ) { return; } - $_comments = $wp_query->comments_by_type[ $r['type'] ]; + $_comments = $wp_query->comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $wp_query->comments; } @@ -2109,73 +2160,73 @@ $default_comments_page = get_option( 'default_comments_page' ); $cpage = get_query_var( 'cpage' ); if ( 'newest' === $default_comments_page ) { - $r['cpage'] = $cpage; + $parsed_args['cpage'] = $cpage; /* * When first page shows oldest comments, post permalink is the same as * the comment permalink. */ - } elseif ( $cpage == 1 ) { - $r['cpage'] = ''; + } elseif ( 1 == $cpage ) { + $parsed_args['cpage'] = ''; } else { - $r['cpage'] = $cpage; + $parsed_args['cpage'] = $cpage; } - $r['page'] = 0; - $r['per_page'] = 0; + $parsed_args['page'] = 0; + $parsed_args['per_page'] = 0; } } } - if ( '' === $r['per_page'] && get_option( 'page_comments' ) ) { - $r['per_page'] = get_query_var( 'comments_per_page' ); + if ( '' === $parsed_args['per_page'] && get_option( 'page_comments' ) ) { + $parsed_args['per_page'] = get_query_var( 'comments_per_page' ); } - if ( empty( $r['per_page'] ) ) { - $r['per_page'] = 0; - $r['page'] = 0; + if ( empty( $parsed_args['per_page'] ) ) { + $parsed_args['per_page'] = 0; + $parsed_args['page'] = 0; } - if ( '' === $r['max_depth'] ) { + if ( '' === $parsed_args['max_depth'] ) { if ( get_option( 'thread_comments' ) ) { - $r['max_depth'] = get_option( 'thread_comments_depth' ); + $parsed_args['max_depth'] = get_option( 'thread_comments_depth' ); } else { - $r['max_depth'] = -1; + $parsed_args['max_depth'] = -1; } } - if ( '' === $r['page'] ) { + if ( '' === $parsed_args['page'] ) { if ( empty( $overridden_cpage ) ) { - $r['page'] = get_query_var( 'cpage' ); + $parsed_args['page'] = get_query_var( 'cpage' ); } else { - $threaded = ( -1 != $r['max_depth'] ); - $r['page'] = ( 'newest' == get_option( 'default_comments_page' ) ) ? get_comment_pages_count( $_comments, $r['per_page'], $threaded ) : 1; - set_query_var( 'cpage', $r['page'] ); + $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 - $r['page'] = intval( $r['page'] ); - if ( 0 == $r['page'] && 0 != $r['per_page'] ) { - $r['page'] = 1; + // Validation check. + $parsed_args['page'] = intval( $parsed_args['page'] ); + if ( 0 == $parsed_args['page'] && 0 != $parsed_args['per_page'] ) { + $parsed_args['page'] = 1; } - if ( null === $r['reverse_top_level'] ) { - $r['reverse_top_level'] = ( 'desc' == get_option( 'comment_order' ) ); + 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( $r['walker'] ) ) { + if ( empty( $parsed_args['walker'] ) ) { $walker = new Walker_Comment; } else { - $walker = $r['walker']; + $walker = $parsed_args['walker']; } - $output = $walker->paged_walk( $_comments, $r['max_depth'], $r['page'], $r['per_page'], $r ); + $output = $walker->paged_walk( $_comments, $parsed_args['max_depth'], $parsed_args['page'], $parsed_args['per_page'], $parsed_args ); $in_comment_loop = false; - if ( $r['echo'] ) { + if ( $parsed_args['echo'] ) { echo $output; } else { return $output; @@ -2201,6 +2252,7 @@ * and 200 characters, respectively. * @since 4.6.0 Introduced the 'action' argument. * @since 4.9.6 Introduced the 'cookies' default comment field. + * @since 5.5.0 Introduced the 'class_container' argument. * * @param array $args { * Optional. Default arguments and form fields to override. @@ -2223,6 +2275,7 @@ * @type string $action The comment form element action attribute. Default '/wp-comments-post.php'. * @type string $id_form The comment form element id attribute. Default 'commentform'. * @type string $id_submit The comment submit element id attribute. Default 'submit'. + * @type string $class_container The comment form container class attribute. Default 'comment-respond'. * @type string $class_form The comment form element class attribute. Default 'comment-form'. * @type string $class_submit The comment submit element class attribute. Default 'submit'. * @type string $name_submit The comment submit element name attribute. Default 'submit'. @@ -2275,19 +2328,63 @@ $req = get_option( 'require_name_email' ); $html_req = ( $req ? " required='required'" : '' ); $html5 = 'html5' === $args['format']; - $fields = array( - 'author' => '

' . ' ' . - '

', - 'email' => '

' . - '

', - 'url' => '

' . - '

', + + $fields = array( + 'author' => sprintf( + '

%s %s

', + sprintf( + '', + __( 'Name' ), + ( $req ? ' *' : '' ) + ), + sprintf( + '', + esc_attr( $commenter['comment_author'] ), + $html_req + ) + ), + 'email' => sprintf( + '

%s %s

', + sprintf( + '', + __( 'Email' ), + ( $req ? ' *' : '' ) + ), + sprintf( + '', + ( $html5 ? 'type="email"' : 'type="text"' ), + esc_attr( $commenter['comment_author_email'] ), + $html_req + ) + ), + 'url' => sprintf( + '

%s %s

', + sprintf( + '', + __( 'Website' ) + ), + sprintf( + '', + ( $html5 ? 'type="url"' : 'type="text"' ), + esc_attr( $commenter['comment_author_url'] ) + ) + ), ); if ( has_action( 'set_comment_cookies', 'wp_set_comment_cookies' ) && get_option( 'show_comments_cookies_opt_in' ) ) { - $consent = empty( $commenter['comment_author_email'] ) ? '' : ' checked="checked"'; - $fields['cookies'] = '

' . - '

'; + $consent = empty( $commenter['comment_author_email'] ) ? '' : ' checked="checked"'; + + $fields['cookies'] = sprintf( + '

%s %s

', + sprintf( + '', + $consent + ), + sprintf( + '', + __( 'Save my name, email, and website in this browser for the next time I comment.' ) + ) + ); // Ensure that the passed fields include cookies consent. if ( isset( $args['fields'] ) && ! isset( $args['fields']['cookies'] ) ) { @@ -2295,7 +2392,11 @@ } } - $required_text = sprintf( ' ' . __( 'Required fields are marked %s' ), '*' ); + $required_text = sprintf( + /* translators: %s: Asterisk symbol (*). */ + ' ' . __( 'Required fields are marked %s' ), + '*' + ); /** * Filters the default comment form fields. @@ -2304,35 +2405,58 @@ * * @param string[] $fields Array of the default comment fields. */ - $fields = apply_filters( 'comment_form_default_fields', $fields ); + $fields = apply_filters( 'comment_form_default_fields', $fields ); + $defaults = array( 'fields' => $fields, - 'comment_field' => '

', - /** This filter is documented in wp-includes/link-template.php */ - 'must_log_in' => '

' . sprintf( - /* translators: %s: login URL */ - __( 'You must be logged in to post a comment.' ), - wp_login_url( apply_filters( 'the_permalink', get_permalink( $post_id ), $post_id ) ) - ) . '

', - /** This filter is documented in wp-includes/link-template.php */ - 'logged_in_as' => '

' . sprintf( - /* translators: 1: edit user link, 2: accessibility text, 3: user name, 4: logout URL */ - __( 'Logged in as %3$s. Log out?' ), - get_edit_user_link(), - /* translators: %s: user name */ - esc_attr( sprintf( __( 'Logged in as %s. Edit your profile.' ), $user_identity ) ), - $user_identity, - wp_logout_url( apply_filters( 'the_permalink', get_permalink( $post_id ), $post_id ) ) - ) . '

', - 'comment_notes_before' => '

' . __( 'Your email address will not be published.' ) . '' . ( $req ? $required_text : '' ) . '

', + 'comment_field' => sprintf( + '

%s %s

', + sprintf( + '', + _x( 'Comment', 'noun' ) + ), + '' + ), + 'must_log_in' => sprintf( + '

%s

', + sprintf( + /* translators: %s: Login URL. */ + __( 'You must be logged in to post a comment.' ), + /** This filter is documented in wp-includes/link-template.php */ + wp_login_url( apply_filters( 'the_permalink', get_permalink( $post_id ), $post_id ) ) + ) + ), + 'logged_in_as' => sprintf( + '

%s

', + sprintf( + /* translators: 1: Edit user link, 2: Accessibility text, 3: User name, 4: Logout URL. */ + __( 'Logged in as %3$s. Log out?' ), + get_edit_user_link(), + /* translators: %s: User name. */ + esc_attr( sprintf( __( 'Logged in as %s. Edit your profile.' ), $user_identity ) ), + $user_identity, + /** This filter is documented in wp-includes/link-template.php */ + wp_logout_url( apply_filters( 'the_permalink', get_permalink( $post_id ), $post_id ) ) + ) + ), + 'comment_notes_before' => sprintf( + '

%s%s

', + sprintf( + '%s', + __( 'Your email address will not be published.' ) + ), + ( $req ? $required_text : '' ) + ), 'comment_notes_after' => '', 'action' => site_url( '/wp-comments-post.php' ), 'id_form' => 'commentform', 'id_submit' => 'submit', + 'class_container' => 'comment-respond', 'class_form' => 'comment-form', 'class_submit' => 'submit', 'name_submit' => 'submit', 'title_reply' => __( 'Leave a Reply' ), + /* translators: %s: Author of the comment being replied to. */ 'title_reply_to' => __( 'Leave a Reply to %s' ), 'title_reply_before' => '

', 'title_reply_after' => '

', @@ -2359,6 +2483,15 @@ // Ensure that the filtered args contain all required default values. $args = array_merge( $defaults, $args ); + // Remove `aria-describedby` from the email field if there's no associated description. + if ( isset( $args['fields']['email'] ) && false === strpos( $args['comment_notes_before'], 'id="email-notes"' ) ) { + $args['fields']['email'] = str_replace( + ' aria-describedby="email-notes"', + '', + $args['fields']['email'] + ); + } + /** * Fires before the comment form. * @@ -2366,7 +2499,7 @@ */ do_action( 'comment_form_before' ); ?> -
+
- > - ', + esc_url( $args['action'] ), + esc_attr( $args['id_form'] ), + esc_attr( $args['class_form'] ), + ( $html5 ? ' novalidate' : '' ) + ); + + /** + * Fires at the top of the comment form, inside the form tag. + * + * @since 3.0.0 + */ + do_action( 'comment_form_top' ); + + if ( is_user_logged_in() ) : + /** - * Fires at the top of the comment form, inside the form tag. + * Filters the 'logged in' message for the comment form for display. + * + * @since 3.0.0 + * + * @param string $args_logged_in The logged-in-as HTML-formatted message. + * @param array $commenter An array containing the comment author's + * username, email, and URL. + * @param string $user_identity If the commenter is a registered user, + * the display name, blank otherwise. + */ + echo apply_filters( 'comment_form_logged_in', $args['logged_in_as'], $commenter, $user_identity ); + + /** + * Fires after the is_user_logged_in() check in the comment form. * * @since 3.0.0 + * + * @param array $commenter An array containing the comment author's + * username, email, and URL. + * @param string $user_identity If the commenter is a registered user, + * the display name, blank otherwise. */ - do_action( 'comment_form_top' ); + do_action( 'comment_form_logged_in_after', $commenter, $user_identity ); + + else : + + echo $args['comment_notes_before']; + + endif; + + // Prepare an array of all fields, including the textarea. + $comment_fields = array( 'comment' => $args['comment_field'] ) + (array) $args['fields']; - if ( is_user_logged_in() ) : - /** - * Filters the 'logged in' message for the comment form for display. - * - * @since 3.0.0 - * - * @param string $args_logged_in The logged-in-as HTML-formatted message. - * @param array $commenter An array containing the comment author's - * username, email, and URL. - * @param string $user_identity If the commenter is a registered user, - * the display name, blank otherwise. - */ - echo apply_filters( 'comment_form_logged_in', $args['logged_in_as'], $commenter, $user_identity ); + /** + * Filters the comment form fields, including the textarea. + * + * @since 4.4.0 + * + * @param array $comment_fields The comment fields. + */ + $comment_fields = apply_filters( 'comment_form_fields', $comment_fields ); + + // Get an array of field names, excluding the textarea. + $comment_field_keys = array_diff( array_keys( $comment_fields ), array( 'comment' ) ); + + // Get the first and the last field name, excluding the textarea. + $first_field = reset( $comment_field_keys ); + $last_field = end( $comment_field_keys ); + + foreach ( $comment_fields as $name => $field ) { + + if ( 'comment' === $name ) { /** - * Fires after the is_user_logged_in() check in the comment form. + * Filters the content of the comment textarea field for display. * * @since 3.0.0 * - * @param array $commenter An array containing the comment author's - * username, email, and URL. - * @param string $user_identity If the commenter is a registered user, - * the display name, blank otherwise. + * @param string $args_comment_field The content of the comment textarea field. */ - do_action( 'comment_form_logged_in_after', $commenter, $user_identity ); + echo apply_filters( 'comment_form_field_comment', $field ); - else : - - echo $args['comment_notes_before']; - - endif; - - // Prepare an array of all fields, including the textarea - $comment_fields = array( 'comment' => $args['comment_field'] ) + (array) $args['fields']; + echo $args['comment_notes_after']; - /** - * Filters the comment form fields, including the textarea. - * - * @since 4.4.0 - * - * @param array $comment_fields The comment fields. - */ - $comment_fields = apply_filters( 'comment_form_fields', $comment_fields ); + } elseif ( ! is_user_logged_in() ) { - // Get an array of field names, excluding the textarea - $comment_field_keys = array_diff( array_keys( $comment_fields ), array( 'comment' ) ); - - // Get the first and the last field name, excluding the textarea - $first_field = reset( $comment_field_keys ); - $last_field = end( $comment_field_keys ); - - foreach ( $comment_fields as $name => $field ) { - - if ( 'comment' === $name ) { - + if ( $first_field === $name ) { /** - * Filters the content of the comment textarea field for display. + * Fires before the comment fields in the comment form, excluding the textarea. * * @since 3.0.0 - * - * @param string $args_comment_field The content of the comment textarea field. */ - echo apply_filters( 'comment_form_field_comment', $field ); - - echo $args['comment_notes_after']; - - } elseif ( ! is_user_logged_in() ) { + do_action( 'comment_form_before_fields' ); + } - if ( $first_field === $name ) { - /** - * Fires before the comment fields in the comment form, excluding the textarea. - * - * @since 3.0.0 - */ - do_action( 'comment_form_before_fields' ); - } + /** + * Filters a comment form field for display. + * + * The dynamic portion of the filter hook, `$name`, refers to the name + * of the comment form field. Such as 'author', 'email', or 'url'. + * + * @since 3.0.0 + * + * @param string $field The HTML-formatted output of the comment form field. + */ + echo apply_filters( "comment_form_field_{$name}", $field ) . "\n"; + if ( $last_field === $name ) { /** - * Filters a comment form field for display. - * - * The dynamic portion of the filter hook, `$name`, refers to the name - * of the comment form field. Such as 'author', 'email', or 'url'. + * Fires after the comment fields in the comment form, excluding the textarea. * * @since 3.0.0 - * - * @param string $field The HTML-formatted output of the comment form field. */ - echo apply_filters( "comment_form_field_{$name}", $field ) . "\n"; - - if ( $last_field === $name ) { - /** - * Fires after the comment fields in the comment form, excluding the textarea. - * - * @since 3.0.0 - */ - do_action( 'comment_form_after_fields' ); - } + do_action( 'comment_form_after_fields' ); } } + } - $submit_button = sprintf( - $args['submit_button'], - esc_attr( $args['name_submit'] ), - esc_attr( $args['id_submit'] ), - esc_attr( $args['class_submit'] ), - esc_attr( $args['label_submit'] ) - ); + $submit_button = sprintf( + $args['submit_button'], + esc_attr( $args['name_submit'] ), + esc_attr( $args['id_submit'] ), + esc_attr( $args['class_submit'] ), + esc_attr( $args['label_submit'] ) + ); - /** - * Filters the submit button for the comment form to display. - * - * @since 4.2.0 - * - * @param string $submit_button HTML markup for the submit button. - * @param array $args Arguments passed to comment_form(). - */ - $submit_button = apply_filters( 'comment_form_submit_button', $submit_button, $args ); + /** + * Filters the submit button for the comment form to display. + * + * @since 4.2.0 + * + * @param string $submit_button HTML markup for the submit button. + * @param array $args Arguments passed to comment_form(). + */ + $submit_button = apply_filters( 'comment_form_submit_button', $submit_button, $args ); - $submit_field = sprintf( - $args['submit_field'], - $submit_button, - get_comment_id_fields( $post_id ) - ); + $submit_field = sprintf( + $args['submit_field'], + $submit_button, + get_comment_id_fields( $post_id ) + ); - /** - * Filters the submit field for the comment form to display. - * - * The submit field includes the submit button, hidden fields for the - * comment form, and any wrapper markup. - * - * @since 4.2.0 - * - * @param string $submit_field HTML markup for the submit field. - * @param array $args Arguments passed to comment_form(). - */ - echo apply_filters( 'comment_form_submit_field', $submit_field, $args ); + /** + * Filters the submit field for the comment form to display. + * + * The submit field includes the submit button, hidden fields for the + * comment form, and any wrapper markup. + * + * @since 4.2.0 + * + * @param string $submit_field HTML markup for the submit field. + * @param array $args Arguments passed to comment_form(). + */ + echo apply_filters( 'comment_form_submit_field', $submit_field, $args ); - /** - * Fires at the bottom of the comment form, inside the closing tag. - * - * @since 1.5.0 - * - * @param int $post_id The post ID. - */ - do_action( 'comment_form', $post_id ); - ?> - - + /** + * Fires at the bottom of the comment form, inside the closing form tag. + * + * @since 1.5.0 + * + * @param int $post_id The post ID. + */ + do_action( 'comment_form', $post_id ); + + echo ''; + + endif; + ?>