Make WordPress Core


Ignore:
Timestamp:
09/03/2015 06:16:35 PM (9 years ago)
Author:
wonderboymusic
Message:

Introduce WP_Comment class to model/strongly-type rows from the comments database table. Inclusion of this class is a pre-req for some more general comment cleanup and sanity.

  • Takes inspiration from WP_Post and adds sanity to comment caching.
  • Clarifies when the current global value for $comment is returned. The current implementation in get_comment() introduces side effects and an occasion stale global value for $comment when comment caches are cleaned.
  • Strongly-types @param docs
  • This class is marked final for now

Props wonderboymusic, nacin.

See #32619.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/comment-template.php

    r33047 r33891  
    3838     * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
    3939     *
     40     * @param string     $author     The comment author's username.
     41     * @param int        $comment_ID The comment ID.
     42     * @param WP_Comment $comment    The comment object.
     43     */
     44    return apply_filters( 'get_comment_author', $author, $comment_ID, $comment );
     45}
     46
     47/**
     48 * Displays the author of the current comment.
     49 *
     50 * @since 0.71
     51 *
     52 * @param int $comment_ID Optional. The ID of the comment for which to print the author. Default current comment.
     53 */
     54function comment_author( $comment_ID = 0 ) {
     55    $author = get_comment_author( $comment_ID );
     56
     57    /**
     58     * Filter the comment author's name for display.
     59     *
     60     * @since 1.2.0
     61     * @since 4.1.0 The `$comment_ID` parameter was added.
     62     *
    4063     * @param string $author     The comment author's username.
    4164     * @param int    $comment_ID The comment ID.
    42      * @param object $comment    The comment object.
    43      */
    44     return apply_filters( 'get_comment_author', $author, $comment_ID, $comment );
    45 }
    46 
    47 /**
    48  * Displays the author of the current comment.
    49  *
    50  * @since 0.71
    51  *
    52  * @param int $comment_ID Optional. The ID of the comment for which to print the author. Default current comment.
    53  */
    54 function comment_author( $comment_ID = 0 ) {
    55     $author = get_comment_author( $comment_ID );
    56 
    57     /**
    58      * Filter the comment author's name for display.
    59      *
    60      * @since 1.2.0
    61      * @since 4.1.0 The `$comment_ID` parameter was added.
    62      *
    63      * @param string $author     The comment author's username.
    64      * @param int    $comment_ID The comment ID.
    6565     */
    6666    echo apply_filters( 'comment_author', $author, $comment_ID );
     
    8484     * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
    8585     *
    86      * @param string $comment_author_email The comment author's email address.
    87      * @param int    $comment_ID           The comment ID.
    88      * @param object $comment              The comment object.
     86     * @param string     $comment_author_email The comment author's email address.
     87     * @param int        $comment_ID           The comment ID.
     88     * @param WP_Comment $comment              The comment object.
    8989     */
    9090    return apply_filters( 'get_comment_author_email', $comment->comment_author_email, $comment_ID, $comment );
     
    171171     * @since 4.1.0 The `$comment` parameter was added.
    172172     *
    173      * @param string $comment_author_email The comment author's email address.
    174      * @param object $comment              The comment object.
     173     * @param string     $comment_author_email The comment author's email address.
     174     * @param WP_Comment $comment              The comment object.
    175175     */
    176176    $email = apply_filters( 'comment_email', $comment->comment_author_email, $comment );
     
    251251     * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
    252252     *
    253      * @param string $comment_author_IP The comment author's IP address.
    254      * @param int    $comment_ID        The comment ID.
    255      * @param object $comment           The comment object.
     253     * @param string     $comment_author_IP The comment author's IP address.
     254     * @param int        $comment_ID        The comment ID.
     255     * @param WP_Comment $comment           The comment object.
    256256     */
    257257    return apply_filters( 'get_comment_author_IP', $comment->comment_author_IP, $comment_ID, $comment );
     
    290290     * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
    291291     *
    292      * @param string $url        The comment author's URL.
    293      * @param int    $comment_ID The comment ID.
    294      * @param object $comment    The comment object.
     292     * @param string     $url        The comment author's URL.
     293     * @param int        $comment_ID The comment ID.
     294     * @param WP_Comment $comment    The comment object.
    295295     */
    296296    return apply_filters( 'get_comment_author_url', $url, $comment_ID, $comment );
     
    509509     * @param string|int $date    Formatted date string or Unix timestamp.
    510510     * @param string     $d       The format of the date.
    511      * @param object    $comment The comment object.
     511     * @param WP_Comment $comment The comment object.
    512512     */
    513513    return apply_filters( 'get_comment_date', $date, $d, $comment );
     
    564564     * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
    565565     *
    566      * @param string $excerpt    The comment excerpt text.
    567      * @param int    $comment_ID The comment ID.
    568      * @param object $comment    The comment object.
     566     * @param string     $excerpt    The comment excerpt text.
     567     * @param int        $comment_ID The comment ID.
     568     * @param WP_Comment $comment    The comment object.
    569569     */
    570570    return apply_filters( 'get_comment_excerpt', $excerpt, $comment_ID, $comment );
     
    612612     * @since 4.1.0 The `$comment_ID` parameter was added.
    613613     *
    614      * @param int    $comment_ID The current comment ID.
    615      * @param object $comment    The comment object.
     614     * @param int        $comment_ID The current comment ID.
     615     * @param WP_Comment $comment    The comment object.
    616616     */
    617617    return apply_filters( 'get_comment_ID', $comment->comment_ID, $comment );
     
    637637 * @global bool       $in_comment_loop
    638638 *
    639  * @param mixed $comment Comment to retrieve. Default current comment.
    640  * @param array $args    Optional. An array of arguments to override the defaults.
     639 * @param WP_Comment|int|null $comment Comment to retrieve. Default current comment.
     640 * @param array               $args    Optional. An array of arguments to override the defaults.
    641641 * @return string The permalink to the given comment.
    642642 */
     
    682682     * @see get_page_of_comment()
    683683     *
    684      * @param string $link    The comment permalink with '#comment-$id' appended.
    685      * @param object $comment The current comment object.
    686      * @param array  $args    An array of arguments to override the defaults.
     684     * @param string     $link    The comment permalink with '#comment-$id' appended.
     685     * @param WP_Comment $comment The current comment object.
     686     * @param array      $args    An array of arguments to override the defaults.
    687687     */
    688688    return apply_filters( 'get_comment_link', $link, $comment, $args );
     
    826826     * @see Walker_Comment::comment()
    827827     *
    828      * @param string $comment_content Text of the comment.
    829      * @param object $comment         The comment object.
    830      * @param array  $args            An array of arguments.
     828     * @param string     $comment_content Text of the comment.
     829     * @param WP_Comment $comment         The comment object.
     830     * @param array      $args            An array of arguments.
    831831     */
    832832    return apply_filters( 'get_comment_text', $comment->comment_content, $comment, $args );
     
    854854     * @see Walker_Comment::comment()
    855855     *
    856      * @param string $comment_text Text of the current comment.
    857      * @param object $comment      The comment object.
    858      * @param array  $args         An array of arguments.
     856     * @param string     $comment_text Text of the current comment.
     857     * @param WP_Comment $comment      The comment object.
     858     * @param array      $args         An array of arguments.
    859859     */
    860860    echo apply_filters( 'comment_text', $comment_text, $comment, $args );
     
    891891     * @param bool       $gmt       Whether the GMT date is in use.
    892892     * @param bool       $translate Whether the time is translated.
    893      * @param object    $comment   The comment object.
     893     * @param WP_Comment $comment   The comment object.
    894894     */
    895895    return apply_filters( 'get_comment_time', $date, $d, $gmt, $translate, $comment );
     
    926926     * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
    927927     *
    928      * @param string $comment_type The type of comment, such as 'comment', 'pingback', or 'trackback'.
    929      * @param int    $comment_ID   The comment ID.
    930      * @param object $comment      The comment object.
     928     * @param string     $comment_type The type of comment, such as 'comment', 'pingback', or 'trackback'.
     929     * @param int        $comment_ID   The comment ID.
     930     * @param WP_Comment $comment      The comment object.
    931931     */
    932932    return apply_filters( 'get_comment_type', $comment->comment_type, $comment_ID, $comment );
     
    18591859     * @see wp_list_comments()
    18601860     *
    1861      * @param string $output  Passed by reference. Used to append additional content.
    1862      * @param object $comment The comment object. Default current comment.
    1863      * @param int    $depth   Depth of comment.
    1864      * @param array  $args    An array of arguments.
     1861     * @param string     $output  Passed by reference. Used to append additional content.
     1862     * @param WP_Comment $comment The comment object. Default current comment.
     1863     * @param int        $depth   Depth of comment.
     1864     * @param array      $args    An array of arguments.
    18651865     */
    18661866    public function end_el( &$output, $comment, $depth = 0, $args = array() ) {
     
    18851885     * @see wp_list_comments()
    18861886     *
    1887      * @param object $comment The comment object.
    1888      * @param int    $depth   Depth of comment.
    1889      * @param array  $args    An array of arguments.
     1887     * @param WP_Comment $comment The comment object.
     1888     * @param int        $depth   Depth of comment.
     1889     * @param array      $args    An array of arguments.
    18901890     */
    18911891    protected function ping( $comment, $depth, $args ) {
     
    20492049 *     @type bool   $echo              Whether to echo the output or return it. Default true.
    20502050 * }
    2051  * @param array $comments Optional. Array of comment objects.
     2051 * @param array $comments Optional. Array of WP_Comment objects.
    20522052 */
    20532053function wp_list_comments( $args = array(), $comments = null ) {
Note: See TracChangeset for help on using the changeset viewer.