wp-includes/comment-template.php

Global
Classes
- \Walker_Comment

Comment template functions

These functions are meant to live inside of the WordPress loop.

package: WordPress
subpackage: Template

Functions

 
            cancel_comment_reply_link(
          string $text
          )
        
        :

Display HTML content for cancel comment reply link.

Parameters

Name	Type	Description
$text	string	Optional. Text to display for cancel reply link.

Details

since: 2.7.0

 
            comment_ID(
          )
        
        :

Displays the comment id of the current comment.

Details

see: \get_comment_ID()
since: 0.71

 
            comment_author(
          int $comment_ID
              =
              0
          )
        
        :

Displays the author of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to print the author. Optional.

Details

since: 0.71
uses: \apply_filters()

 
            comment_author_IP(
          int $comment_ID
              =
              0
          )
        
        :

Display the IP address of the author of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to print the author's IP address. Optional.

Details

see: \get_comment_author_IP()
since: 0.71

 
            comment_author_email(
          int $comment_ID
              =
              0
          )
        
        :

Display 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 commentors' email address. Most assume that their email address will not appear in raw form on the blog. Doing so will enable anyone, including those that people don't want to get the email address and use it for their own means good and bad.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to print the author's email. Optional.

Details

since: 0.71
uses: \apply_filters()

 
            comment_author_email_link(
          string $linktext, string $before, string $after
          )
        
        :

Display the html email link to the author of the current comment.

Parameters

Name	Type	Description
$linktext	string	The text to display instead of the comment author's email address
$before	string	The text or HTML to display before the email link.
$after	string	The text or HTML to display after the email link.

Details

global: object $comment The current Comment row object
since: 0.71
uses: \apply_filters()
uses: \get_comment_author_email_link()

 
            comment_author_link(
          int $comment_ID
              =
              0
          )
        
        :

Display the html link to the url of the author of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to print the author's link. Optional.

Details

see: \get_comment_author_link()
since: 0.71

 
            comment_author_url(
          int $comment_ID
              =
              0
          )
        
        :

Display the url of the author of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to print the author's URL. Optional.

Details

since: 0.71
uses: \apply_filters()
uses: \get_comment_author_url()

 
            comment_author_url_link(
          string $linktext, string $before, string $after
          )
        
        :

Displays the HTML link of the url of the author of the current comment.

Parameters

Name	Type	Description
$linktext	string	The text to display instead of the comment author's email address
$before	string	The text or HTML to display before the email link.
$after	string	The text or HTML to display after the email link.

Details

see: \get_comment_author_url_link()
since: 0.71

 
            comment_class(
          string|array $class, int $comment_id
              =
              null, int $post_id
              =
              null, bool $echo
              =
              true
          )
        
        :

Generates semantic classes for each comment element

Parameters

Name	Type	Description
$class	string\|array	One or more classes to add to the class list
$comment_id	int	An optional comment ID
$post_id	int	An optional post ID
$echo	bool	Whether comment_class should echo or return

Details

since: 2.7.0

 
            comment_date(
          string $d, int $comment_ID
              =
              0
          )
        
        :

Display the comment date of the current comment.

Parameters

Name	Type	Description
$d	string	The format of the date (defaults to user's config)
$comment_ID	int	The ID of the comment for which to print the date. Optional.

Details

since: 0.71

 
            comment_excerpt(
          int $comment_ID
              =
              0
          )
        
        :

Display the excerpt of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to print the excerpt. Optional.

Details

since: 1.2.0
uses: \apply_filters()

 
            comment_form(
          array $args
              =
              array, mixed $post_id
              =
              null
          )
        
        :
        void

Outputs a complete commenting form for use within a template.

Most strings and form fields may be controlled through the $args array passed into the function, while you may also choose to use the comment_form_default_fields filter to modify the array of default fields if you'd just like to add a new one or remove a single field. All fields are also individually passed through a filter of the form comment_form_field_$name where $name is the key used in the array of fields.

Parameters

Name	Type	Description
$args	array	Options for strings, fields etc in the form
$post_id	mixed	Post ID to generate the form for, uses the current post if null

Details

since: 3.0.0

 
            comment_form_title(
          string $noreplytext
              =
              false, string $replytext
              =
              false, string $linktoparent
              =
              TRUE
          )
        
        :

Display text based on comment reply status. Only affects users with Javascript disabled.

Parameters

Name	Type	Description
$noreplytext	string	Optional. Text to display when not replying to a comment.
$replytext	string	Optional. Text to display when replying to a comment. Accepts "%s" for the author of the comment being replied to.
$linktoparent	string	Optional. Boolean to control making the author's name a link to their comment.

Details

since: 2.7.0

 
            comment_id_fields(
           $id
              =
              0
          )
        
        :

Output hidden input HTML for replying to comments.

Parameters

Name	Type	Description
$id

Details

see: \get_comment_id_fields()
since: 2.7.0

 
            comment_reply_link(
          array $args
              =
              array, int $comment
              =
              null, int $post
              =
              null
          )
        
        :
        string|bool|null

Displays the HTML content for reply to comment link.

Parameters

Name	Type	Description
$args	array	Optional. Override default options.
$comment	int	Optional. Comment being replied to.
$post	int	Optional. Post that the comment is going to be displayed on.

Returns

Type	Description
stringboolnull

Details

see: \get_comment_reply_link()
since: 2.7.0

 
            comment_text(
          int $comment_ID
              =
              0
          )
        
        :

Displays the text of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to print the text. Optional.

Details

since: 0.71
uses: \apply_filters()
uses: \get_comment_text()

 
            comment_time(
          string $d
          )
        
        :

Display the comment time of the current comment.

Parameters

Name	Type	Description
$d	string	Optional. The format of the time (defaults to user's config)

Details

since: 0.71

 
            comment_type(
          string $commenttxt
              =
              false, string $trackbacktxt
              =
              false, string $pingbacktxt
              =
              false
          )
        
        :

Display the comment type of the current comment.

Parameters

Name	Type	Description
$commenttxt	string	The string to display for comment type
$trackbacktxt	string	The string to display for trackback type
$pingbacktxt	string	The string to display for pingback type

Details

since: 0.71

 
            comments_link(
          string $deprecated, bool $deprecated_2
          )
        
        :

Displays the link to the current post comments.

Parameters

Name	Type	Description
$deprecated	string	Not Used
$deprecated_2	bool	Not Used

Details

since: 0.71

 
            comments_number(
          string $zero
              =
              false, string $one
              =
              false, string $more
              =
              false, string $deprecated
          )
        
        :

Display the language string for the number of comments the current post has.

Parameters

Name	Type	Description
$zero	string	Text for no comments
$one	string	Text for one comment
$more	string	Text for more than one comment
$deprecated	string	Not used.

Details

since: 0.71
uses: \apply_filters()

 
            comments_open(
          int $post_id
              =
              NULL
          )
        
        :
        bool

Whether the current post is open for comments.

Parameters

Name	Type	Description
$post_id	int	An optional post ID to check instead of the current post.

Returns

Type	Description
bool

Details

since: 1.5.0
uses: \$post

 
            comments_popup_link(
          string $zero
              =
              false, string $one
              =
              false, string $more
              =
              false, string $css_class, string $none
              =
              false
          )
        
        :
        null

Displays the link to the comments popup window for the current post ID.

Is not meant to be displayed on single posts and pages. Should be used on the lists of posts

Parameters

Name	Type	Description
$zero	string	The string to display when no comments
$one	string	The string to display when only one comment is available
$more	string	The string to display when there are more than one comment
$css_class	string	The CSS class to use for comments
$none	string	The string to display when comments have been turned off

Returns

Type	Description
null

Details

since: 0.71
uses: \$wpcommentspopupfile
uses: \$wpcommentsjavascript
uses: \$post

 
            comments_popup_script(
          int $width
              =
              400, int $height
              =
              400, string $file
          )
        
        :

Displays the JS popup script to show a comment.

If the $file parameter is empty, then the home page is assumed. The defaults for the window are 400px by 400px.

For the comment link popup to work, this function has to be called or the normal comment link will be assumed.

Parameters

Name	Type	Description
$width	int	Optional. The width of the popup window
$height	int	Optional. The height of the popup window
$file	string	Optional. Sets the location of the popup window

Details

global: string $wpcommentspopupfile The URL to use for the popup window
global: int $wpcommentsjavascript Whether to use JavaScript. Set when function is called
since: 0.71

 
            comments_template(
          string $file
              =
              /comments.php, bool $separate_comments
              =
              false
          )
        
        :
        null

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.

Uses the WordPress database object to query for the comments. The comments are passed through the 'comments_array' filter hook with the list of comments and the post ID respectively.

The $file path is passed through a filter hook called, 'comments_template' which includes the TEMPLATEPATH and $file combined. Tries the $filtered path first and if it fails it will require the default comment themplate from the default theme. If either does not exist, then the WordPress process will be halted. It is advised for that reason, that the default theme is not deleted.

Parameters

Name	Type	Description
$file	string	Optional, default '/comments.php'. The file to load
$separate_comments	bool	Optional, whether to separate the comments by comment type. Default is false.

Returns

Type	Description
null

Details

global: array $comment List of comment objects for the current post
since: 1.5.0
uses: \$wpdb
uses: \$post
uses: \$withcomments

 
            get_cancel_comment_reply_link(
          string $text
          )
        
        :

Retrieve HTML content for cancel comment reply link.

Parameters

Name	Type	Description
$text	string	Optional. Text to display for cancel reply link.

Details

since: 2.7.0

 
            get_comment_ID(
          )
        
        :
        int

Retrieve the comment id of the current comment.

Returns

Type	Description
int

Details

since: 1.5.0
uses: \$comment
uses: \apply_filters()

 
            get_comment_author(
          int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the author of the current comment.

If the comment has an empty comment_author field, then 'Anonymous' person is assumed.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to retrieve the author. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \apply_filters()

 
            get_comment_author_IP(
          int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the IP address of the author of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to get the author's IP address. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \$comment
uses: \apply_filters()

 
            get_comment_author_email(
          int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the email of the author of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to get the author's email. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \apply_filters()
uses: \$comment

 
            get_comment_author_email_link(
          string $linktext, string $before, string $after
          )
        
        :

Return the html email link to the author of the current comment.

Parameters

Name	Type	Description
$linktext	string	The text to display instead of the comment author's email address
$before	string	The text or HTML to display before the email link.
$after	string	The text or HTML to display after the email link.

Details

global: object $comment The current Comment row object
since: 2.7
uses: \apply_filters()

 
            get_comment_author_link(
          int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the html link to the url of the author of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to get the author's link. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \apply_filters()

 
            get_comment_author_url(
          int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the url of the author of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to get the author's URL. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \apply_filters()

 
            get_comment_author_url_link(
          string $linktext, string $before, string $after
          )
        
        :
        string

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 will be ignored.

Encapsulate the HTML link between the $before and $after. So it will appear in the order of $before, link, and finally $after.

Parameters

Name	Type	Description
$linktext	string	The text to display instead of the comment author's email address
$before	string	The text or HTML to display before the email link.
$after	string	The text or HTML to display after the email link.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \apply_filters()

 
            get_comment_class(
          string|array $class, int $comment_id
              =
              null, int $post_id
              =
              null
          )
        
        :
        array

Returns the classes for the comment div as an array

Parameters

Name	Type	Description
$class	string\|array	One or more classes to add to the class list
$comment_id	int	An optional comment ID
$post_id	int	An optional post ID

Returns

Type	Description
array

Details

since: 2.7.0

 
            get_comment_date(
          string $d, int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the comment date of the current comment.

Parameters

Name	Type	Description
$d	string	The format of the date (defaults to user's config)
$comment_ID	int	The ID of the comment for which to get the date. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \apply_filters()
uses: \$comment

 
            get_comment_excerpt(
          int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the excerpt of the current 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.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to get the excerpt. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \$comment
uses: \apply_filters()

 
            get_comment_id_fields(
           $id
              =
              0
          )
        
        :
        string

Retrieve hidden input HTML for replying to comments.

Parameters

Name	Type	Description
$id

Returns

Type	Description
string

Details

since: 3.0.0

 
            get_comment_link(
          object|string|int $comment
              =
              null, array $args
              =
              array
          )
        
        :
        string

Retrieve the link to a given comment.

Parameters

Name	Type	Description
$comment	object\|string\|int	Comment to retrieve.
$args	array	Optional args.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \$comment

 
            get_comment_reply_link(
          array $args
              =
              array, int $comment
              =
              null, int $post
              =
              null
          )
        
        :
        string|bool|null

Retrieve HTML content for reply to comment link.

The default arguments that can be override are 'add_below', 'respond_id', 'reply_text', 'login_text', and 'depth'. The 'login_text' argument will be used, if the user must log in or register first before posting a comment. The 'reply_text' will be used, if they can post a reply. The 'add_below' and 'respond_id' arguments are for the JavaScript moveAddCommentForm() function parameters.

Parameters

Name	Type	Description
$args	array	Optional. Override default options.
$comment	int	Optional. Comment being replied to.
$post	int	Optional. Post that the comment is going to be displayed on.

Returns

Type	Description
stringboolnull

Details

since: 2.7.0

 
            get_comment_text(
          int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the text of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to get the text. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \$comment

 
            get_comment_time(
          string $d, bool $gmt
              =
              false, bool $translate
              =
              true
          )
        
        :
        string

Retrieve the comment time of the current comment.

Parameters

Name	Type	Description
$d	string	Optional. The format of the time (defaults to user's config)
$gmt	bool	Whether to use the GMT date
$translate	bool	Whether to translate the time (for use in feeds)

Returns

Type	Description
string

Details

since: 1.5.0
uses: \$comment
uses: \apply_filter()

 
            get_comment_type(
          int $comment_ID
              =
              0
          )
        
        :
        string

Retrieve the comment type of the current comment.

Parameters

Name	Type	Description
$comment_ID	int	The ID of the comment for which to get the type. Optional.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \$comment
uses: \apply_filters()

 
            get_comments_link(
          int $post_id
              =
              0
          )
        
        :
        string

Retrieves the link to the current post comments.

Parameters

Name	Type	Description
$post_id	int	Optional post id

Returns

Type	Description
string

Details

since: 1.5.0

 
            get_comments_number(
          int $post_id
              =
              0
          )
        
        :
        int

Retrieve the amount of comments a post has.

Parameters

Name	Type	Description
$post_id	int	The Post ID

Returns

Type	Description
int

Details

since: 1.5.0
uses: \apply_filters()

 
            get_post_reply_link(
          array $args
              =
              array, int|object $post
              =
              null
          )
        
        :
        string|bool|null

Retrieve HTML content for reply to post link.

Parameters

Name	Type	Description
$args	array	Optional. Override default options.
$post	int\|object	Optional. Post that the comment is going to be displayed on. Defaults to current post.

Returns

Type	Description
stringboolnull

Details

since: 2.7.0

 
            get_trackback_url(
          )
        
        :
        string

Retrieve 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 current post is used and appended to the correct page to go to.

Returns

Type	Description
string

Details

since: 1.5.0
uses: \apply_filters()

 
            pings_open(
          int $post_id
              =
              NULL
          )
        
        :
        bool

Whether the current post is open for pings.

Parameters

Name	Type	Description
$post_id	int	An optional post ID to check instead of the current post.

Returns

Type	Description
bool

Details

since: 1.5.0
uses: \$post

 
            post_reply_link(
          array $args
              =
              array, int|object $post
              =
              null
          )
        
        :
        string|bool|null

Displays the HTML content for reply to post link.

Parameters

Name	Type	Description
$args	array	Optional. Override default options.
$post	int\|object	Optional. Post that the comment is going to be displayed on.

Returns

Type	Description
stringboolnull

Details

see: \get_post_reply_link()
since: 2.7.0

 
            trackback_rdf(
          int $deprecated
          )
        
        :

Generates and displays the RDF for the trackback information of current post.

Deprecated in 3.0.0, and restored in 3.0.1.

Parameters

Name	Type	Description
$deprecated	int	Not used (Was $timezone = 0)

Details

since: 0.71

 
            trackback_url(
          bool $deprecated_echo
              =
              true
          )
        
        :
        void|string

Displays the current post's trackback URL.

Parameters

Name	Type	Description
$deprecated_echo	bool	Remove backwards compat in 2.5

Returns

Type	Description
voidstring

Details

since: 0.71
uses: \get_trackback_url()

 
            wp_comment_form_unfiltered_html_nonce(
          )
        
        :

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.

The function was backported to 2.0.10 and was added to versions 2.1.3 and above. Does not exist in versions prior to 2.0.10 in the 2.0 branch and in the 2.1 branch, prior to 2.1.3. Technically added in 2.2.0.

Backported to 2.0.10.

Details

since: 2.1.3
uses: \$post

 
            wp_list_comments(
          string|array $args
              =
              array, array $comments
              =
              null
          )
        
        :

List comments

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

Parameters

Name	Type	Description
$args	string\|array	Formatting options
$comments	array	Optional array of comment objects. Defaults to $wp_query->comments

Details

since: 2.7.0
uses: \Walker_Comment

\Walker_Comment
jump to top

HTML comment list class.

Extend the Walker class to use it, see examples at the below. Child classes do not need to implement all of the abstract methods in the class. The child only needs to implement the methods that are needed. Also, the methods are not strictly abstract in that the parameter definition needs to be followed. The child classes can have additional parameters.

Extends from: \Walker
package: WordPress
since: 2.7.0
used_by: get_comment_pages_count()
used_by: wp_list_comments()
uses: \Walker

Properties

array
                 $db_fields= 'array'

Default valuearrayDetails

Type: array
see: \Walker::$db_fields
since: 2.7.0

string
                 $tree_type= 'comment'

Default valuecommentDetails

Type: string
see: \Walker::$tree_type
since: 2.7.0

Methods

 
            display_element(
           $element,  $children_elements,  $max_depth,  $depth
              =
              0,  $args,  $output
          )
        
        :

This function is designed to enhance Walker::display_element() to display children of higher nesting levels than selected inline on the highest depth level displayed. This prevents them being orphaned at the end of the comment list.

Example: max_depth = 2, with 5 levels of nested content. 1 1.1 1.1.1 1.1.1.1 1.1.1.1.1 1.1.2 1.1.2.1 2 2.2

Parameters

Name	Type	Description
$element
$children_elements
$max_depth
$depth
$args
$output

 
            end_el(
          string $output, object $comment, int $depth, array $args
          )
        
        :

Parameters

Name	Type	Description
$output	string	Passed by reference. Used to append additional content.
$comment	object
$depth	int	Depth of comment.
$args	array

Details

see: \Walker::end_el()
since: 2.7.0

 
            end_lvl(
          string $output, int $depth, array $args
          )
        
        :

Parameters

Name	Type	Description
$output	string	Passed by reference. Used to append additional content.
$depth	int	Depth of comment.
$args	array	Will only append content if style argument value is 'ol' or 'ul'.

Details

see: \Walker::end_lvl()
since: 2.7.0

 
            start_el(
          string $output, object $comment, int $depth, array $args
          )
        
        :

Parameters

Name	Type	Description
$output	string	Passed by reference. Used to append additional content.
$comment	object	Comment data object.
$depth	int	Depth of comment in reference to parents.
$args	array

Details

see: \Walker::start_el()
since: 2.7.0

 
            start_lvl(
          string $output, int $depth, array $args
          )
        
        :

Parameters

Name	Type	Description
$output	string	Passed by reference. Used to append additional content.
$depth	int	Depth of comment.
$args	array	Uses 'style' argument for type of HTML list.

Details

see: \Walker::start_lvl()
since: 2.7.0

wp-includes/comment-template.php

Functions

\Walker_Commentjump to top

Properties

Methods

\Walker_Comment
jump to top