WordPress.org
Get WordPress

Make WordPress Core

Ticket #27716: 27716.2.patch

File 27716.2.patch, 33.3 KB (added by DrewAPicture, 10 years ago)

Final pass.

  • src/wp-includes/link-template.php

     
    1010 * Display the permalink for the current post.
    1111 *
    1212 * @since 1.2.0
    13  * @uses apply_filters() Calls 'the_permalink' filter on the permalink string.
    1413 */
    1514function the_permalink() {
     15        /**
     16         * Filter the display of the permalink for the current post.
     17         *
     18         * @since 1.5.0
     19         *
     20         * @param string $permalink The permalink for the current post.
     21         */
    1622        echo esc_url( apply_filters( 'the_permalink', get_permalink() ) );
    1723}
    1824
    … …  
    3844        else
    3945                $string = untrailingslashit($string);
    4046
    41         // Note that $type_of_url can be one of following:
    42         // single, single_trackback, single_feed, single_paged, feed, category, page, year, month, day, paged, post_type_archive
    43         $string = apply_filters('user_trailingslashit', $string, $type_of_url);
     47        /**
     48         * Filter the trailing slashed string, depending on whether the site is set
     49         * to use training slashes.
     50         *
     51         * @since 2.2.0
     52         *
     53         * @param string $string      URL with or without a trailing slash.
     54         * @param string $type_of_url The type of URL being considered. Accepts 'single', 'single_trackback',
     55         *                            'single_feed', 'single_paged', 'feed', 'category', 'page', 'year',
     56         *                            'month', 'day', 'paged', 'post_type_archive'.
     57         */
     58        $string = apply_filters( 'user_trailingslashit', $string, $type_of_url );
    4459        return $string;
    4560}
    4661
    … …  
    129144
    130145        $permalink = get_option('permalink_structure');
    131146
    132         $permalink = apply_filters('pre_post_link', $permalink, $post, $leavename);
     147        /**
     148         * Filter the permalink structure for a post before token replacement occurs.
     149         *
     150         * Only applies to posts with post_type of 'post'.
     151         *
     152         * @since 3.0.0
     153         *
     154         * @param string  $permalink The site's permalink structure.
     155         * @param WP_Post $post      The post in question.
     156         * @param bool    $leavename Whether to keep the post name.
     157         */
     158        $permalink = apply_filters( 'pre_post_link', $permalink, $post, $leavename );
    133159
    134160        if ( '' != $permalink && !in_array($post->post_status, array('draft', 'pending', 'auto-draft')) ) {
    135161                $unixtime = strtotime($post->post_date);
    … …  
    139165                        $cats = get_the_category($post->ID);
    140166                        if ( $cats ) {
    141167                                usort($cats, '_usort_terms_by_ID'); // order by ID
     168
     169                                /**
     170                                 * Filter the category that gets used in the %category% permalink token.
     171                                 *
     172                                 * @since 3.5.0
     173                                 *
     174                                 * @param stdClass $cat  The category to use in the permalink.
     175                                 * @param array    $cats Array of all categories associated with the post.
     176                                 * @param WP_Post  $post The post in question.
     177                                 */
    142178                                $category_object = apply_filters( 'post_link_category', $cats[0], $cats, $post );
     179
    143180                                $category_object = get_term( $category_object, 'category' );
    144181                                $category = $category_object->slug;
    145182                                if ( $parent = $category_object->parent )
    … …  
    179216        } else { // if they're not using the fancy permalink option
    180217                $permalink = home_url('?p=' . $post->ID);
    181218        }
    182         return apply_filters('post_link', $permalink, $post, $leavename);
     219
     220        /**
     221         * Filter the permalink for a post.
     222         *
     223         * Only applies to posts with post_type of 'post'.
     224         *
     225         * @since 1.5.0
     226         *
     227         * @param string  $permalink The post's permalink.
     228         * @param WP_Post $post      The post in question.
     229         * @param bool    $leavename Whether to keep the post name.
     230         */
     231        return apply_filters( 'post_link', $permalink, $post, $leavename );
    183232}
    184233
    185234/**
    … …  
    223272                $post_link = home_url($post_link);
    224273        }
    225274
    226         return apply_filters('post_type_link', $post_link, $post, $leavename, $sample);
     275        /**
     276         * Filter the permalink for a post with a custom post type.
     277         *
     278         * @since 3.0.0
     279         *
     280         * @param string  $post_link The post's permalink.
     281         * @param WP_Post $post      The post in question.
     282         * @param bool    $leavename Whether to keep the post name.
     283         * @param bool    $sample    Is it a sample permalink.
     284         */
     285        return apply_filters( 'post_type_link', $post_link, $post, $leavename, $sample );
    227286}
    228287
    229288/**
    … …  
    262321        else
    263322                $link = _get_page_link( $post, $leavename, $sample );
    264323
     324        /**
     325         * Filter the permalink for a page.
     326         *
     327         * @since 1.5.0
     328         *
     329         * @param string $link    The page's permalink.
     330         * @param int    $post_id The ID of the page.
     331         * @param bool   $sample  Is it a sample permalink.
     332         */
    265333        return apply_filters( 'page_link', $link, $post->ID, $sample );
    266334}
    267335
    … …  
    298366                $link = home_url( '?page_id=' . $post->ID );
    299367        }
    300368
     369        /**
     370         * Filter the permalink for a non-page_on_front page.
     371         *
     372         * @since 2.1.0
     373         *
     374         * @param string $link    The page's permalink.
     375         * @param int    $post_id The ID of the page.
     376         */
    301377        return apply_filters( '_get_page_link', $link, $post->ID );
    302378}
    303379
    … …  
    341417        if ( ! $link )
    342418                $link = home_url( '/?attachment_id=' . $post->ID );
    343419
     420        /**
     421         * Filter the permalink for an attachment.
     422         *
     423         * @since 2.0.0
     424         *
     425         * @param string $link    The attachment's permalink.
     426         * @param int    $post_id Attachment ID.
     427         */
    344428        return apply_filters( 'attachment_link', $link, $post->ID );
    345429}
    346430
    … …  
    359443        $yearlink = $wp_rewrite->get_year_permastruct();
    360444        if ( !empty($yearlink) ) {
    361445                $yearlink = str_replace('%year%', $year, $yearlink);
    362                 return apply_filters('year_link', home_url( user_trailingslashit($yearlink, 'year') ), $year);
     446                $yearlink = home_url( user_trailingslashit( $yearlink, 'year' ) );
    363447        } else {
    364                 return apply_filters('year_link', home_url('?m=' . $year), $year);
     448                $yearlink = home_url( '?m=' . $year );
    365449        }
     450
     451        /**
     452         * Filter the year archive permalink.
     453         *
     454         * @since 1.5.0
     455         *
     456         * @param string $yearlink Permalink for the year archive.
     457         * @param int    $year     Year for the archive.
     458         */
     459        return apply_filters( 'year_link', $yearlink, $year );
    366460}
    367461
    368462/**
    … …  
    384478        if ( !empty($monthlink) ) {
    385479                $monthlink = str_replace('%year%', $year, $monthlink);
    386480                $monthlink = str_replace('%monthnum%', zeroise(intval($month), 2), $monthlink);
    387                 return apply_filters('month_link', home_url( user_trailingslashit($monthlink, 'month') ), $year, $month);
     481                $monthlink = home_url( user_trailingslashit( $monthlink, 'month' ) );
    388482        } else {
    389                 return apply_filters('month_link', home_url( '?m=' . $year . zeroise($month, 2) ), $year, $month);
     483                $monthlink = home_url( '?m=' . $year . zeroise( $month, 2 ) );
    390484        }
     485
     486        /**
     487         * Filter the month archive permalink.
     488         *
     489         * @since 1.5.0
     490         *
     491         * @param string $monthlink Permalink for the month archive.
     492         * @param int    $year      Year for the archive.
     493         * @param int    $month     The month for the archive.
     494         */
     495        return apply_filters( 'month_link', $monthlink, $year, $month );
    391496}
    392497
    393498/**
    … …  
    414519                $daylink = str_replace('%year%', $year, $daylink);
    415520                $daylink = str_replace('%monthnum%', zeroise(intval($month), 2), $daylink);
    416521                $daylink = str_replace('%day%', zeroise(intval($day), 2), $daylink);
    417                 return apply_filters('day_link', home_url( user_trailingslashit($daylink, 'day') ), $year, $month, $day);
     522                $daylink = home_url( user_trailingslashit( $daylink, 'day' ) );
    418523        } else {
    419                 return apply_filters('day_link', home_url( '?m=' . $year . zeroise($month, 2) . zeroise($day, 2) ), $year, $month, $day);
     524                $daylink = home_url( '?m=' . $year . zeroise( $month, 2 ) . zeroise( $day, 2 ) );
    420525        }
     526
     527        /**
     528         * Filter the day archive permalink.
     529         *
     530         * @since 1.5.0
     531         *
     532         * @param string $daylink Permalink for the day archive.
     533         * @param int    $year    Year for the archive.
     534         * @param int    $month   Month for the archive.
     535         * @param int    $day     The day for the archive.
     536         */
     537        return apply_filters( 'day_link', $daylink, $year, $month, $day );
    421538}
    422539
    423540/**
    … …  
    430547 */
    431548function the_feed_link( $anchor, $feed = '' ) {
    432549        $link = '<a href="' . esc_url( get_feed_link( $feed ) ) . '">' . $anchor . '</a>';
     550
     551        /**
     552         * Filter the feed link anchor tag.
     553         *
     554         * @since 3.0.0
     555         *
     556         * @param string $link The complete anchor tag for a feed link.
     557         * @param string $feed The feed type, or an empty string for the
     558         *                     default feed type.
     559         */
    433560        echo apply_filters( 'the_feed_link', $link, $feed );
    434561}
    435562
    … …  
    467594                $output = home_url("?feed={$feed}");
    468595        }
    469596
    470         return apply_filters('feed_link', $output, $feed);
     597        /**
     598         * Filter the feed type permalink.
     599         *
     600         * @since 1.5.0
     601         *
     602         * @param string $output The feed permalink.
     603         * @param string $feed   Feed type.
     604         */
     605        return apply_filters( 'feed_link', $output, $feed );
    471606}
    472607
    473608/**
    … …  
    506641                        $url = add_query_arg( array( 'feed' => $feed, 'p' => $post_id ), home_url( '/' ) );
    507642        }
    508643
    509         return apply_filters('post_comments_feed_link', $url);
     644        /**
     645         * Filter the post comments feed permalink.
     646         *
     647         * @since 1.5.1
     648         *
     649         * @param string $url Post comments feed permalink.
     650         */
     651        return apply_filters( 'post_comments_feed_link', $url );
    510652}
    511653
    512654/**
    … …  
    528670        if ( empty($link_text) )
    529671                $link_text = __('Comments Feed');
    530672
     673        /**
     674         * Filter the post comment feed link anchor tag.
     675         *
     676         * @since 2.8.0
     677         *
     678         * @param string $link    The complete anchor tag for the comment feed link.
     679         * @param int    $post_id Post ID.
     680         * @param string $feed    The feed type, or an empty string for the default feed type.
     681         */
    531682        echo apply_filters( 'post_comments_feed_link_html', "<a href='$url'>$link_text</a>", $post_id, $feed );
    532683}
    533684
    … …  
    562713                $link = trailingslashit($link) . user_trailingslashit($feed_link, 'feed');
    563714        }
    564715
    565         $link = apply_filters('author_feed_link', $link, $feed);
     716        /**
     717         * Filter the feed link for a given author.
     718         *
     719         * @since 1.5.1
     720         *
     721         * @param string $link The author feed link.
     722         * @param string $feed Feed type.
     723         */
     724        $link = apply_filters( 'author_feed_link', $link, $feed );
    566725
    567726        return $link;
    568727}
    … …  
    629788                $link = trailingslashit( $link ) . user_trailingslashit( $feed_link, 'feed' );
    630789        }
    631790
    632         if ( 'category' == $taxonomy )
     791        if ( 'category' == $taxonomy ) {
     792                /**
     793                 * Filter the category feed link.
     794                 *
     795                 * @since 1.5.1
     796                 *
     797                 * @param string $link The category feed link.
     798                 * @param string $feed Feed type.
     799                 */
    633800                $link = apply_filters( 'category_feed_link', $link, $feed );
    634         elseif ( 'post_tag' == $taxonomy )
     801        } elseif ( 'post_tag' == $taxonomy ) {
     802                /**
     803                 * Filter the post tag feed link.
     804                 *
     805                 * @since 2.3.0
     806                 *
     807                 * @param string $link The tag feed link.
     808                 * @param string $feed Feed type.
     809                 */
    635810                $link = apply_filters( 'tag_feed_link', $link, $feed );
    636         else
     811        } else {
     812                /**
     813                 * Filter the feed link for a taxonomy other than 'category' or 'post_tag'.
     814                 *
     815                 * @since 3.0.0
     816                 *
     817                 * @param string $link The taxonomy feed link.
     818                 * @param string $feed Feed type.
     819                 * @param string $feed The taxonomy name.
     820                 */
    637821                $link = apply_filters( 'taxonomy_feed_link', $link, $feed, $taxonomy );
     822        }
    638823
    639824        return $link;
    640825}
    … …  
    662847 * @return string
    663848 */
    664849function get_edit_tag_link( $tag_id, $taxonomy = 'post_tag' ) {
     850        /**
     851         * Filter the edit link for a tag (or term in another taxonomy).
     852         *
     853         * @since 2.7.0
     854         *
     855         * @param string $link The term edit link.
     856         */
    665857        return apply_filters( 'get_edit_tag_link', get_edit_term_link( $tag_id, $taxonomy ) );
    666858}
    667859
    … …  
    678870 */
    679871function edit_tag_link( $link = '', $before = '', $after = '', $tag = null ) {
    680872        $link = edit_term_link( $link, '', '', $tag, false );
     873
     874        /**
     875         * Filter the anchor tag for the edit link for a tag (or term in another taxonomy).
     876         *
     877         * @since 2.7.0
     878         *
     879         * @param string $link The anchor tag for the edit link.
     880         */
    681881        echo $before . apply_filters( 'edit_tag_link', $link ) . $after;
    682882}
    683883
    … …  
    709909
    710910        $location = add_query_arg( $args, admin_url( 'edit-tags.php' ) );
    711911
     912        /**
     913         * Filter the edit link for a term.
     914         *
     915         * @since 3.1.0
     916         *
     917         * @param string $location    The edit link.
     918         * @param int    $term_id     Term ID.
     919         * @param string $taxonomy    Taxonomy name.
     920         * @param string $object_type The object type (eg. the post type).
     921         */
    712922        return apply_filters( 'get_edit_term_link', $location, $term_id, $taxonomy, $object_type );
    713923}
    714924
    … …  
    738948                $link = __('Edit This');
    739949
    740950        $link = '<a href="' . get_edit_term_link( $term->term_id, $term->taxonomy ) . '">' . $link . '</a>';
     951
     952        /**
     953         * Filter the anchor tag for the edit link of a term.
     954         *
     955         * @since 3.1.0
     956         *
     957         * @param string $link    The anchor tag for the edit link.
     958         * @param int    $term_id Term ID.
     959         */
    741960        $link = $before . apply_filters( 'edit_term_link', $link, $term->term_id ) . $after;
    742961
    743962        if ( $echo )
    … …  
    773992                $link = home_url( user_trailingslashit( $link, 'search' ) );
    774993        }
    775994
     995        /**
     996         * Filter the search permalink.
     997         *
     998         * @since 3.0.0
     999         *
     1000         * @param string $link   Search permalink.
     1001         * @param string $search The URL-encoded search term.
     1002         */
    7761003        return apply_filters( 'search_link', $link, $search );
    7771004}
    7781005
    … …  
    8011028                $link .= "feed/$feed/";
    8021029        }
    8031030
    804         $link = apply_filters('search_feed_link', $link, $feed, 'posts');
     1031        /**
     1032         * Filter the search feed link.
     1033         *
     1034         * @since 2.5.0
     1035         *
     1036         * @param string $link Search feed link.
     1037         * @param string $feed Feed type.
     1038         * @param string $type The search type. One of 'posts' or 'comments'.
     1039         */
     1040        $link = apply_filters( 'search_feed_link', $link, $feed, 'posts' );
    8051041
    8061042        return $link;
    8071043}
    … …  
    8301066        else
    8311067                $link = add_query_arg('withcomments', 1, $link);
    8321068
     1069        /** This filter is documented in wp-includes/link-template.php */
    8331070        $link = apply_filters('search_feed_link', $link, $feed, 'comments');
    8341071
    8351072        return $link;
    … …  
    8621099                $link = home_url( '?post_type=' . $post_type );
    8631100        }
    8641101
     1102        /**
     1103         * Filter the post type archive permalink.
     1104         *
     1105         * @since 3.1.0
     1106         *
     1107         * @param string $link      The post type archive permalink.
     1108         * @param string $post_type Post type name.
     1109         */
    8651110        return apply_filters( 'post_type_archive_link', $link, $post_type );
    8661111}
    8671112
    … …  
    8921137                $link = add_query_arg( 'feed', $feed, $link );
    8931138        }
    8941139
     1140        /**
     1141         * Filter the post type archive feed link.
     1142         *
     1143         * @since 3.1.0
     1144         *
     1145         * @param string $link The post type archive feed link.
     1146         * @param string $feed Feed type.
     1147         */
    8951148        return apply_filters( 'post_type_archive_feed_link', $link, $feed );
    8961149}
    8971150
    … …  
    9251178        if ( !current_user_can( 'edit_post', $post->ID ) )
    9261179                return;
    9271180
    928         return apply_filters( 'get_edit_post_link', admin_url( sprintf($post_type_object->_edit_link . $action, $post->ID) ), $post->ID, $context );
     1181        /**
     1182         * Filter the post edit link.
     1183         *
     1184         * @since 2.3.0
     1185         *
     1186         * @param string $link    The edit link.
     1187         * @param int    $post_id Post ID.
     1188         * @param string $context The link context. If set to 'display' then ampersands
     1189         *                        are encoded.
     1190         */
     1191        return apply_filters( 'get_edit_post_link', admin_url( sprintf( $post_type_object->_edit_link . $action, $post->ID ) ), $post->ID, $context );
    9291192}
    9301193
    9311194/**
    … …  
    9501213
    9511214        $post_type_obj = get_post_type_object( $post->post_type );
    9521215        $link = '<a class="post-edit-link" href="' . $url . '">' . $link . '</a>';
     1216
     1217        /**
     1218         * Filter the post edit link anchor tag.
     1219         *
     1220         * @since 2.3.0
     1221         *
     1222         * @param string $link    Anchor tag for the edit link.
     1223         * @param int    $post_id Post ID.
     1224         */
    9531225        echo $before . apply_filters( 'edit_post_link', $link, $post->ID ) . $after;
    9541226}
    9551227
    … …  
    9831255
    9841256        $delete_link = add_query_arg( 'action', $action, admin_url( sprintf( $post_type_object->_edit_link, $post->ID ) ) );
    9851257
     1258        /**
     1259         * Filter the post delete link.
     1260         *
     1261         * @since 2.9.0
     1262         *
     1263         * @param string $link         The delete link.
     1264         * @param int    $post_id      Post ID.
     1265         * @param bool   $force_delete Whether to bypass the trash and force deletion. Default false.
     1266         */
    9861267        return apply_filters( 'get_delete_post_link', wp_nonce_url( $delete_link, "$action-post_{$post->ID}" ), $post->ID, $force_delete );
    9871268}
    9881269
    … …  
    10011282                return;
    10021283
    10031284        $location = admin_url('comment.php?action=editcomment&amp;c=') . $comment->comment_ID;
     1285
     1286        /**
     1287         * Filter the comment edit link.
     1288         *
     1289         * @since 2.3.0
     1290         *
     1291         * @param string $location The edit link.
     1292         */
    10041293        return apply_filters( 'get_edit_comment_link', $location );
    10051294}
    10061295
    … …  
    10231312                $link = __('Edit This');
    10241313
    10251314        $link = '<a class="comment-edit-link" href="' . get_edit_comment_link( $comment->comment_ID ) . '">' . $link . '</a>';
     1315
     1316        /**
     1317         * Filter the comment edit link anchor tag.
     1318         *
     1319         * @since 2.3.0
     1320         *
     1321         * @param string $link       Anchor tag for the edit link.
     1322         * @param int    $comment_id Comment ID.
     1323         */
    10261324        echo $before . apply_filters( 'edit_comment_link', $link, $comment->comment_ID ) . $after;
    10271325}
    10281326
    … …  
    10411339                return;
    10421340
    10431341        $location = admin_url('link.php?action=edit&amp;link_id=') . $link->link_id;
     1342
     1343        /**
     1344         * Filter the bookmark (link) edit link.
     1345         *
     1346         * @since 2.7.0
     1347         *
     1348         * @param string $location The edit link.
     1349         * @param int    $link_id  Bookmark ID.
     1350         */
    10441351        return apply_filters( 'get_edit_bookmark_link', $location, $link->link_id );
    10451352}
    10461353
    … …  
    10641371                $link = __('Edit This');
    10651372
    10661373        $link = '<a href="' . get_edit_bookmark_link( $bookmark ) . '">' . $link . '</a>';
     1374
     1375        /**
     1376         * Filter the bookmark edit link anchor tag.
     1377         *
     1378         * @since 2.7.0
     1379         *
     1380         * @param string $link    Anchor tag for the edit link.
     1381         * @param int    $link_id Bookmark ID.
     1382         */
    10671383        echo $before . apply_filters( 'edit_bookmark_link', $link, $bookmark->link_id ) . $after;
    10681384}
    10691385
    … …  
    10921408        else
    10931409                $link = add_query_arg( 'user_id', $user->ID, self_admin_url( 'user-edit.php' ) );
    10941410
     1411        /**
     1412         * Filter the user edit link.
     1413         *
     1414         * @since 3.5.0
     1415         *
     1416         * @param string $link    The edit link.
     1417         * @param int    $user_id User ID.
     1418         */
    10951419        return apply_filters( 'get_edit_user_link', $link, $user->ID );
    10961420}
    10971421
    … …  
    11891513        $op = $previous ? '<' : '>';
    11901514        $order = $previous ? 'DESC' : 'ASC';
    11911515
     1516        /**
     1517         * Filter the JOIN clause in the SQL for an adjacent post query.
     1518         *
     1519         * The dynamic portion of the hook name, $adjacent, refers to the type
     1520         * of adjacency, 'next' or 'previous'.
     1521         *
     1522         * @since 2.5.0
     1523         *
     1524         * @param string $join           The JOIN clause in the SQL.
     1525         * @param bool   $in_same_term   Whether post should be in a same taxonomy term.
     1526         * @param array  $excluded_terms Array of excluded term IDs.
     1527         */
    11921528        $join  = apply_filters( "get_{$adjacent}_post_join", $join, $in_same_term, $excluded_terms );
     1529
     1530        /**
     1531         * Filter the WHERE clause in the SQL for an adjacent post query.
     1532         *
     1533         * The dynamic portion of the hook name, $adjacent, refers to the type
     1534         * of adjacency, 'next' or 'previous'.
     1535         *
     1536         * @since 2.5.0
     1537         *
     1538         * @param string $where          The WHERE clause in the SQL.
     1539         * @param bool   $in_same_term   Whether post should be in a same taxonomy term.
     1540         * @param array  $excluded_terms Array of excluded term IDs.
     1541         */
    11931542        $where = apply_filters( "get_{$adjacent}_post_where", $wpdb->prepare( "WHERE p.post_date $op %s AND p.post_type = %s AND p.post_status = 'publish' $posts_in_ex_terms_sql", $current_post_date, $post->post_type), $in_same_term, $excluded_terms );
     1543
     1544        /**
     1545         * Filter the ORDER BY clause in the SQL for an adjacent post query.
     1546         *
     1547         * The dynamic portion of the hook name, $adjacent, refers to the type
     1548         * of adjacency, 'next' or 'previous'.
     1549         *
     1550         * @since 2.5.0
     1551         *
     1552         * @param string $order_by The ORDER BY clause in the SQL.
     1553         */
    11941554        $sort  = apply_filters( "get_{$adjacent}_post_sort", "ORDER BY p.post_date $order LIMIT 1" );
    11951555
    11961556        $query = "SELECT p.ID FROM $wpdb->posts AS p $join $where $sort";
    … …  
    12521612        $link .= "' href='" . get_permalink( $post ) . "' />\n";
    12531613
    12541614        $adjacent = $previous ? 'previous' : 'next';
     1615
     1616        /**
     1617         * Filter the adjacent post relational link.
     1618         *
     1619         * The dynamic portion of the hook name, $adjacent, refers to the type
     1620         * of adjacency, 'next' or 'previous'.
     1621         *
     1622         * @since 2.8.0
     1623         *
     1624         * @param string $link The relational link.
     1625         */
    12551626        return apply_filters( "{$adjacent}_post_rel_link", $link );
    12561627}
    12571628
    … …  
    14641835
    14651836                /** This filter is documented in wp-includes/post-template.php */
    14661837                $title = apply_filters( 'the_title', $title, $post->ID );
     1838
    14671839                $date = mysql2date( get_option( 'date_format' ), $post->post_date );
    14681840                $rel = $previous ? 'prev' : 'next';
    14691841
    … …  
    14771849
    14781850        $adjacent = $previous ? 'previous' : 'next';
    14791851
     1852        /**
     1853         * Filter the adjacent post link.
     1854         *
     1855         * The dynamic portion of the hook name, $adjacent, refers to the type
     1856         * of adjacency, 'next' or 'previous'.
     1857         *
     1858         * @since 2.6.0
     1859         *
     1860         * @param string  $output The adjacent post link.
     1861         * @param string  $format Link anchor format.
     1862         * @param string  $link   Link permalink format.
     1863         * @param WP_Post $post   The adjacent post.
     1864         */
    14801865        return apply_filters( "{$adjacent}_post_link", $output, $format, $link, $post );
    14811866}
    14821867
    … …  
    15591944                $result = $base . $request . $query_string;
    15601945        }
    15611946
    1562         $result = apply_filters('get_pagenum_link', $result);
     1947        /**
     1948         * Filter the page number link for the current request.
     1949         *
     1950         * @since 2.5.0
     1951         *
     1952         * @param string $result The page number link.
     1953         */
     1954        $result = apply_filters( 'get_pagenum_link', $result );
    15631955
    15641956        if ( $escape )
    15651957                return esc_url( $result );
    … …  
    16302022                $label = __( 'Next Page &raquo;' );
    16312023
    16322024        if ( !is_single() && ( $nextpage <= $max_page ) ) {
     2025                /**
     2026                 * Filter the anchor tag attributes for the next posts page link.
     2027                 *
     2028                 * @since 2.7.0
     2029                 *
     2030                 * @param string $attributes Attributes for the anchor tag.
     2031                 */
    16332032                $attr = apply_filters( 'next_posts_link_attributes', '' );
     2033
    16342034                return '<a href="' . next_posts( $max_page, false ) . "\" $attr>" . preg_replace('/&([^#])(?![a-z]{1,8};)/i', '&#038;$1', $label) . '</a>';
    16352035        }
    16362036}
    … …  
    17012101                $label = __( '&laquo; Previous Page' );
    17022102
    17032103        if ( !is_single() && $paged > 1 ) {
     2104                /**
     2105                 * Filter the anchor tag attributes for the previous posts page link.
     2106                 *
     2107                 * @since 2.7.0
     2108                 *
     2109                 * @param string $attributes Attributes for the anchor tag.
     2110                 */
    17042111                $attr = apply_filters( 'previous_posts_link_attributes', '' );
    17052112                return '<a href="' . previous_posts( false ) . "\" $attr>". preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&#038;$1', $label ) .'</a>';
    17062113        }
    … …  
    18022209
    18032210        $result .= '#comments';
    18042211
    1805         $result = apply_filters('get_comments_pagenum_link', $result);
     2212        /**
     2213         * Filter the comments page number link for the current request.
     2214         *
     2215         * @since 2.7.0
     2216         *
     2217         * @param string $result The comments page number link.
     2218         */
     2219        $result = apply_filters( 'get_comments_pagenum_link', $result );
    18062220
    18072221        return $result;
    18082222}
    … …  
    18382252        if ( empty($label) )
    18392253                $label = __('Newer Comments &raquo;');
    18402254
     2255        /**
     2256         * Filter the anchor tag attributes for the next comments page link.
     2257         *
     2258         * @since 2.7.0
     2259         *
     2260         * @param string $attributes Attributes for the anchor tag.
     2261         */
    18412262        return '<a href="' . esc_url( get_comments_pagenum_link( $nextpage, $max_page ) ) . '" ' . apply_filters( 'next_comments_link_attributes', '' ) . '>'. preg_replace('/&([^#])(?![a-z]{1,8};)/i', '&#038;$1', $label) .'</a>';
    18422263}
    18432264
    … …  
    18752296        if ( empty($label) )
    18762297                $label = __('&laquo; Older Comments');
    18772298
     2299        /**
     2300         * Filter the anchor tag attributes for the previous comments page link.
     2301         *
     2302         * @since 2.7.0
     2303         *
     2304         * @param string $attributes Attributes for the anchor tag.
     2305         */
    18782306        return '<a href="' . esc_url( get_comments_pagenum_link( $prevpage ) ) . '" ' . apply_filters( 'previous_comments_link_attributes', '' ) . '>' . preg_replace('/&([^#])(?![a-z]{1,8};)/i', '&#038;$1', $label) .'</a>';
    18792307}
    18802308
    … …  
    19562384
    19572385        $link = str_replace(array("\r", "\n", "\t"),  '', $link);
    19582386
    1959         return apply_filters('shortcut_link', $link);
     2387        /**
     2388         * Filter the Press This bookmarklet link.
     2389         *
     2390         * @since 2.6.0
     2391         *
     2392         * @param string $link The Press This bookmarklet link.
     2393         */
     2394        return apply_filters( 'shortcut_link', $link );
    19602395}
    19612396
    19622397/**
    … …  
    20152450        if ( $path && is_string( $path ) )
    20162451                $url .= '/' . ltrim( $path, '/' );
    20172452
     2453        /**
     2454         * Filter the home URL.
     2455         *
     2456         * @since 3.0.0
     2457         *
     2458         * @param string      $url         The complete home URL including scheme and path.
     2459         * @param string      $path        Path relative to the home URL. Blank string if no path is specified.
     2460         * @param string|null $orig_scheme Scheme to give the home URL context. Accepts 'http', 'https', 'relative' or null.
     2461         * @param int|null    $blog_id     Blog ID, or null for the current blog.
     2462         */
    20182463        return apply_filters( 'home_url', $url, $path, $orig_scheme, $blog_id );
    20192464}
    20202465
    … …  
    20252470 * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
    20262471 * overridden.
    20272472 *
    2028  * @since 2.6.0
     2473 * @since 3.0.0
    20292474 *
    20302475 * @uses get_site_url()
    20312476 *
    … …  
    20652510        if ( $path && is_string( $path ) )
    20662511                $url .= '/' . ltrim( $path, '/' );
    20672512
     2513        /**
     2514         * Filter the site URL.
     2515         *
     2516         * @since 2.7.0
     2517         *
     2518         * @param string      $url     The complete site URL including scheme and path.
     2519         * @param string      $path    Path relative to the site URL. Blank string if no path is specified.
     2520         * @param string|null $scheme  Scheme to give the site URL context. Accepts 'http', 'https', 'login',
     2521         *                             'login_post', 'admin', 'relative' or null.
     2522         * @param int|null    $blog_id Blog ID, or null for the current blog.
     2523         */
    20682524        return apply_filters( 'site_url', $url, $path, $scheme, $blog_id );
    20692525}
    20702526
    … …  
    20972553        if ( $path && is_string( $path ) )
    20982554                $url .= ltrim( $path, '/' );
    20992555
     2556        /**
     2557         * Filter the admin area URL.
     2558         *
     2559         * @since 2.8.0
     2560         *
     2561         * @param string   $url     The complete admin area URL including scheme and path.
     2562         * @param string   $path    Path relative to the admin area URL. Blank string if no path is specified.
     2563         * @param int|null $blog_id Blog ID, or null for the current blog.
     2564         */
    21002565        return apply_filters( 'admin_url', $url, $path, $blog_id );
    21012566}
    21022567
    … …  
    21152580        if ( $path && is_string( $path ) )
    21162581                $url .= ltrim($path, '/');
    21172582
    2118         return apply_filters('includes_url', $url, $path);
     2583        /**
     2584         * Filter the URL to the includes directory.
     2585         *
     2586         * @since 2.8.0
     2587         *
     2588         * @param string $url  The complete URL to the includes directory including scheme and path.
     2589         * @param string $path Path relative to the URL to the wp-includes directory. Blank string
     2590         *                     if no path is specified.
     2591         */
     2592        return apply_filters( 'includes_url', $url, $path );
    21192593}
    21202594
    21212595/**
    … …  
    21322606        if ( $path && is_string( $path ) )
    21332607                $url .= '/' . ltrim($path, '/');
    21342608
    2135         return apply_filters('content_url', $url, $path);
     2609        /**
     2610         * Filter the URL to the content directory.
     2611         *
     2612         * @since 2.8.0
     2613         *
     2614         * @param string $url  The complete URL to the content directory including scheme and path.
     2615         * @param string $path Path relative to the URL to the content directory. Blank string
     2616         *                     if no path is specified.
     2617         */
     2618        return apply_filters( 'content_url', $url, $path);
    21362619}
    21372620
    21382621/**
    … …  
    21702653        if ( $path && is_string( $path ) )
    21712654                $url .= '/' . ltrim($path, '/');
    21722655
    2173         return apply_filters('plugins_url', $url, $path, $plugin);
     2656        /**
     2657         * Filter the URL to the plugins directory.
     2658         *
     2659         * @since 2.8.0
     2660         *
     2661         * @param string $url    The complete URL to the plugins directory including scheme and path.
     2662         * @param string $path   Path relative to the URL to the plugins directory. Blank string
     2663         *                       if no path is specified.
     2664         * @param string $plugin The plugin file path to be relative to. Blank string if no plugin
     2665         *                       is specified.
     2666         */
     2667        return apply_filters( 'plugins_url', $url, $path, $plugin );
    21742668}
    21752669
    21762670/**
    … …  
    22002694        if ( $path && is_string( $path ) )
    22012695                $url .= ltrim( $path, '/' );
    22022696
     2697        /**
     2698         * Filter the network site URL.
     2699         *
     2700         * @since 3.0.0
     2701         *
     2702         * @param string      $url    The complete network site URL including scheme and path.
     2703         * @param string      $path   Path relative to the network site URL. Blank string if
     2704         *                            no path is specified.
     2705         * @param string|null $scheme Scheme to give the URL context. Accepts 'http', 'https',
     2706         *                            'relative' or null.
     2707         */
    22032708        return apply_filters( 'network_site_url', $url, $path, $scheme );
    22042709}
    22052710
    … …  
    22342739        if ( $path && is_string( $path ) )
    22352740                $url .= ltrim( $path, '/' );
    22362741
     2742        /**
     2743         * Filter the network home URL.
     2744         *
     2745         * @since 3.0.0
     2746         *
     2747         * @param string      $url         The complete network home URL including scheme and path.
     2748         * @param string      $path        Path relative to the network home URL. Blank string
     2749         *                                 if no path is specified.
     2750         * @param string|null $orig_scheme Scheme to give the URL context. Accepts 'http', 'https',
     2751         *                                 'relative' or null.
     2752         */
    22372753        return apply_filters( 'network_home_url', $url, $path, $orig_scheme);
    22382754}
    22392755
    … …  
    22552771        if ( $path && is_string( $path ) )
    22562772                $url .= ltrim($path, '/');
    22572773
    2258         return apply_filters('network_admin_url', $url, $path);
     2774        /**
     2775         * Filter the network admin URL.
     2776         *
     2777         * @since 3.0.0
     2778         *
     2779         * @param string $url  The complete network admin URL including scheme and path.
     2780         * @param string $path Path relative to the network admin URL. Blank string if
     2781         *                     no path is specified.
     2782         */
     2783        return apply_filters( 'network_admin_url', $url, $path );
    22592784}
    22602785
    22612786/**
    … …  
    22732798        if ( $path && is_string( $path ) )
    22742799                $url .= ltrim($path, '/');
    22752800
    2276         return apply_filters('user_admin_url', $url, $path);
     2801        /**
     2802         * Filter the user admin URL for the current user.
     2803         *
     2804         * @since 3.1.0
     2805         *
     2806         * @param string $url  The complete URL including scheme and path.
     2807         * @param string $path Path relative to the URL. Blank string if
     2808         *                     no path is specified.
     2809         */
     2810        return apply_filters( 'user_admin_url', $url, $path );
    22772811}
    22782812
    22792813/**
    … …  
    23282862                $url = preg_replace( '#^\w+://#', $scheme . '://', $url );
    23292863        }
    23302864
     2865        /**
     2866         * Filter the resulting URL after setting the scheme.
     2867         *
     2868         * @since 3.4.0
     2869         *
     2870         * @param string $url         The complete URL including scheme and path.
     2871         * @param string $scheme      Scheme applied to the URL. One of 'http', 'https', or 'relative'.
     2872         * @param string $orig_scheme Scheme requested for the URL. One of 'http', 'https', 'login',
     2873         *                            'login_post', 'admin', 'rpc', or 'relative'.
     2874         */
    23312875        return apply_filters( 'set_url_scheme', $url, $scheme, $orig_scheme );
    23322876}
    23332877
    … …  
    23662910                }
    23672911        }
    23682912
     2913        /**
     2914         * Filter the dashboard URL for a user.
     2915         *
     2916         * @since 3.1.0
     2917         *
     2918         * @param string $url     The complete URL including scheme and path.
     2919         * @param int    $user_id The user ID.
     2920         * @param string $path    Path relative to the URL. Blank string if no path is specified.
     2921         * @param string $scheme  Scheme to give the URL context. Accepts 'http', 'https', 'login',
     2922         *                        'login_post', 'admin', 'relative' or null.
     2923         */
    23692924        return apply_filters( 'user_dashboard_url', $url, $user_id, $path, $scheme);
    23702925}
    23712926
    … …  
    23892944        else
    23902945                $url = get_dashboard_url( $user_id, 'profile.php', $scheme );
    23912946
     2947        /**
     2948         * Filter the URL for a user's profile editor.
     2949         *
     2950         * @since 3.1.0
     2951         *
     2952         * @param string $url     The complete URL including scheme and path.
     2953         * @param int    $user_id The user ID.
     2954         * @param string $scheme  Scheme to give the URL context. Accepts 'http', 'https', 'login',
     2955         *                        'login_post', 'admin', 'relative' or null.
     2956         */
    23922957        return apply_filters( 'edit_profile_url', $url, $user_id, $scheme);
    23932958}
    23942959
    … …  
    24292994 * @return string A shortlink or an empty string if no shortlink exists for the requested resource or if shortlinks are not enabled.
    24302995 */
    24312996function wp_get_shortlink($id = 0, $context = 'post', $allow_slugs = true) {
    2432         // Allow plugins to short-circuit this function.
    2433         $shortlink = apply_filters('pre_get_shortlink', false, $id, $context, $allow_slugs);
     2997        /**
     2998         * Filter whether to preempt generating a shortlink for the given post.
     2999         *
     3000         * Passing a truthy value to the filter will effectively short-circuit the
     3001         * shortlink-generation process, returning that value instead.
     3002         *
     3003         * @since 3.0.0
     3004         *
     3005         * @param bool|string $return      Short-circuit return value. Either false or a URL string.
     3006         * @param int         $id          Post ID, or 0 for the current post.
     3007         * @param string      $context     The context for the link. One of 'post' or 'query',
     3008         * @param bool        $allow_slugs Whether to allow post slugs in the shortlink.
     3009         */
     3010        $shortlink = apply_filters( 'pre_get_shortlink', false, $id, $context, $allow_slugs );
     3011
    24343012        if ( false !== $shortlink )
    24353013                return $shortlink;
    24363014
    … …  
    24583036                }
    24593037        }
    24603038
    2461         return apply_filters('get_shortlink', $shortlink, $id, $context, $allow_slugs);
     3039        /**
     3040         * Filter the shortlink for a post.
     3041         *
     3042         * @since 3.0.0
     3043         *
     3044         * @param string $shortlink   Shortlink URL.
     3045         * @param int    $id          Post ID, or 0 for the current post.
     3046         * @param string $context     The context for the link. One of 'post' or 'query',
     3047         * @param bool   $allow_slugs Whether to allow post slugs in the shortlink. Not used by default.
     3048         */
     3049        return apply_filters( 'get_shortlink', $shortlink, $id, $context, $allow_slugs );
    24623050}
    24633051
    24643052/**
    … …  
    25273115
    25283116        if ( !empty( $shortlink ) ) {
    25293117                $link = '<a rel="shortlink" href="' . esc_url( $shortlink ) . '" title="' . $title . '">' . $text . '</a>';
     3118
     3119                /**
     3120                 * Filter the shortlink anchor tag for a post.
     3121                 *
     3122                 * @since 3.0.0
     3123                 *
     3124                 * @param string $link      Shortlink anchor tag.
     3125                 * @param string $shortlink Shortlink URL.
     3126                 * @param string $text      Shortlink's text.
     3127                 * @param string $title     Shortlink's title attribute.
     3128                 */
    25303129                $link = apply_filters( 'the_shortlink', $link, $shortlink, $text, $title );
    25313130                echo $before, $link, $after;
    25323131        }