',
$args['next_text'],
$args['in_same_term'],
$args['excluded_terms'],
$args['taxonomy']
);
// Only add markup if there's somewhere to navigate to.
if ( $previous || $next ) {
$navigation = _navigation_markup( $previous . $next, 'post-navigation', $args['screen_reader_text'] );
}
return $navigation;
}
/**
* Displays the navigation to next/previous post, when applicable.
*
* @since 4.1.0
*
* @param array $args Optional. See get_the_post_navigation() for available arguments.
* Default empty array.
*/
function the_post_navigation( $args = array() ) {
echo get_the_post_navigation( $args );
}
/**
* Returns the navigation to next/previous set of posts, when applicable.
*
* @since 4.1.0
*
* @global WP_Query $wp_query WordPress Query object.
*
* @param array $args {
* Optional. Default posts navigation arguments. Default empty array.
*
* @type string $prev_text Anchor text to display in the previous posts link.
* Default 'Older posts'.
* @type string $next_text Anchor text to display in the next posts link.
* Default 'Newer posts'.
* @type string $screen_reader_text Screen reader text for nav element.
* Default 'Posts navigation'.
* }
* @return string Markup for posts links.
*/
function get_the_posts_navigation( $args = array() ) {
$navigation = '';
// Don't print empty markup if there's only one page.
if ( $GLOBALS['wp_query']->max_num_pages > 1 ) {
$args = wp_parse_args( $args, array(
'prev_text' => __( 'Older posts' ),
'next_text' => __( 'Newer posts' ),
'screen_reader_text' => __( 'Posts navigation' ),
) );
$next_link = get_previous_posts_link( $args['next_text'] );
$prev_link = get_next_posts_link( $args['prev_text'] );
if ( $prev_link ) {
$navigation .= '
' . $prev_link . '
';
}
if ( $next_link ) {
$navigation .= '
' . $next_link . '
';
}
$navigation = _navigation_markup( $navigation, 'posts-navigation', $args['screen_reader_text'] );
}
return $navigation;
}
/**
* Displays the navigation to next/previous set of posts, when applicable.
*
* @since 4.1.0
*
* @param array $args Optional. See get_the_posts_navigation() for available arguments.
* Default empty array.
*/
function the_posts_navigation( $args = array() ) {
echo get_the_posts_navigation( $args );
}
/**
* Retrieves a paginated navigation to next/previous set of posts, when applicable.
*
* @since 4.1.0
*
* @param array $args {
* Optional. Default pagination arguments, see paginate_links().
*
* @type string $screen_reader_text Screen reader text for navigation element.
* Default 'Posts navigation'.
* }
* @return string Markup for pagination links.
*/
function get_the_posts_pagination( $args = array() ) {
$navigation = '';
// Don't print empty markup if there's only one page.
if ( $GLOBALS['wp_query']->max_num_pages > 1 ) {
$args = wp_parse_args( $args, array(
'mid_size' => 1,
'prev_text' => _x( 'Previous', 'previous post' ),
'next_text' => _x( 'Next', 'next post' ),
'screen_reader_text' => __( 'Posts navigation' ),
) );
// Make sure we get a string back. Plain is the next best thing.
if ( isset( $args['type'] ) && 'array' == $args['type'] ) {
$args['type'] = 'plain';
}
// Set up paginated links.
$links = paginate_links( $args );
if ( $links ) {
$navigation = _navigation_markup( $links, 'pagination', $args['screen_reader_text'] );
}
}
return $navigation;
}
/**
* Displays a paginated navigation to next/previous set of posts, when applicable.
*
* @since 4.1.0
*
* @param array $args Optional. See get_the_posts_pagination() for available arguments.
* Default empty array.
*/
function the_posts_pagination( $args = array() ) {
echo get_the_posts_pagination( $args );
}
/**
* Wraps passed links in navigational markup.
*
* @since 4.1.0
* @access private
*
* @param string $links Navigational links.
* @param string $class Optional. Custom class for nav element. Default: 'posts-navigation'.
* @param string $screen_reader_text Optional. Screen reader text for nav element. Default: 'Posts navigation'.
* @return string Navigation template tag.
*/
function _navigation_markup( $links, $class = 'posts-navigation', $screen_reader_text = '' ) {
if ( empty( $screen_reader_text ) ) {
$screen_reader_text = __( 'Posts navigation' );
}
$template = '
';
/**
* Filters the navigation markup template.
*
* Note: The filtered template HTML must contain specifiers for the navigation
* class (%1$s), the screen-reader-text value (%2$s), and placement of the
* navigation links (%3$s):
*
*
*
* @since 4.4.0
*
* @param string $template The default template.
* @param string $class The class passed by the calling function.
* @return string Navigation template.
*/
$template = apply_filters( 'navigation_markup_template', $template, $class );
return sprintf( $template, sanitize_html_class( $class ), esc_html( $screen_reader_text ), $links );
}
/**
* Retrieves the comments page number link.
*
* @since 2.7.0
*
* @global WP_Rewrite $wp_rewrite
*
* @param int $pagenum Optional. Page number. Default 1.
* @param int $max_page Optional. The maximum number of comment pages. Default 0.
* @return string The comments page number link URL.
*/
function get_comments_pagenum_link( $pagenum = 1, $max_page = 0 ) {
global $wp_rewrite;
$pagenum = (int) $pagenum;
$result = get_permalink();
if ( 'newest' == get_option('default_comments_page') ) {
if ( $pagenum != $max_page ) {
if ( $wp_rewrite->using_permalinks() )
$result = user_trailingslashit( trailingslashit($result) . $wp_rewrite->comments_pagination_base . '-' . $pagenum, 'commentpaged');
else
$result = add_query_arg( 'cpage', $pagenum, $result );
}
} elseif ( $pagenum > 1 ) {
if ( $wp_rewrite->using_permalinks() )
$result = user_trailingslashit( trailingslashit($result) . $wp_rewrite->comments_pagination_base . '-' . $pagenum, 'commentpaged');
else
$result = add_query_arg( 'cpage', $pagenum, $result );
}
$result .= '#comments';
/**
* Filters the comments page number link for the current request.
*
* @since 2.7.0
*
* @param string $result The comments page number link.
*/
return apply_filters( 'get_comments_pagenum_link', $result );
}
/**
* Retrieves the link to the next comments page.
*
* @since 2.7.1
*
* @global WP_Query $wp_query
*
* @param string $label Optional. Label for link text. Default empty.
* @param int $max_page Optional. Max page. Default 0.
* @return string|void HTML-formatted link for the next page of comments.
*/
function get_next_comments_link( $label = '', $max_page = 0 ) {
global $wp_query;
if ( ! is_singular() )
return;
$page = get_query_var('cpage');
if ( ! $page ) {
$page = 1;
}
$nextpage = intval($page) + 1;
if ( empty($max_page) )
$max_page = $wp_query->max_num_comment_pages;
if ( empty($max_page) )
$max_page = get_comment_pages_count();
if ( $nextpage > $max_page )
return;
if ( empty($label) )
$label = __('Newer Comments »');
/**
* Filters the anchor tag attributes for the next comments page link.
*
* @since 2.7.0
*
* @param string $attributes Attributes for the anchor tag.
*/
return ''. preg_replace('/&([^#])(?![a-z]{1,8};)/i', '&$1', $label) .'';
}
/**
* Displays the link to the next comments page.
*
* @since 2.7.0
*
* @param string $label Optional. Label for link text. Default empty.
* @param int $max_page Optional. Max page. Default 0.
*/
function next_comments_link( $label = '', $max_page = 0 ) {
echo get_next_comments_link( $label, $max_page );
}
/**
* Retrieves the link to the previous comments page.
*
* @since 2.7.1
*
* @param string $label Optional. Label for comments link text. Default empty.
* @return string|void HTML-formatted link for the previous page of comments.
*/
function get_previous_comments_link( $label = '' ) {
if ( ! is_singular() )
return;
$page = get_query_var('cpage');
if ( intval($page) <= 1 )
return;
$prevpage = intval($page) - 1;
if ( empty($label) )
$label = __('« Older Comments');
/**
* Filters the anchor tag attributes for the previous comments page link.
*
* @since 2.7.0
*
* @param string $attributes Attributes for the anchor tag.
*/
return '' . preg_replace('/&([^#])(?![a-z]{1,8};)/i', '&$1', $label) .'';
}
/**
* Displays the link to the previous comments page.
*
* @since 2.7.0
*
* @param string $label Optional. Label for comments link text. Default empty.
*/
function previous_comments_link( $label = '' ) {
echo get_previous_comments_link( $label );
}
/**
* Displays or retrieves pagination links for the comments on the current post.
*
* @see paginate_links()
* @since 2.7.0
*
* @global WP_Rewrite $wp_rewrite
*
* @param string|array $args Optional args. See paginate_links(). Default empty array.
* @return string|void Markup for pagination links.
*/
function paginate_comments_links( $args = array() ) {
global $wp_rewrite;
if ( ! is_singular() )
return;
$page = get_query_var('cpage');
if ( !$page )
$page = 1;
$max_page = get_comment_pages_count();
$defaults = array(
'base' => add_query_arg( 'cpage', '%#%' ),
'format' => '',
'total' => $max_page,
'current' => $page,
'echo' => true,
'add_fragment' => '#comments'
);
if ( $wp_rewrite->using_permalinks() )
$defaults['base'] = user_trailingslashit(trailingslashit(get_permalink()) . $wp_rewrite->comments_pagination_base . '-%#%', 'commentpaged');
$args = wp_parse_args( $args, $defaults );
$page_links = paginate_links( $args );
if ( $args['echo'] )
echo $page_links;
else
return $page_links;
}
/**
* Retrieves navigation to next/previous set of comments, when applicable.
*
* @since 4.4.0
*
* @param array $args {
* Optional. Default comments navigation arguments.
*
* @type string $prev_text Anchor text to display in the previous comments link.
* Default 'Older comments'.
* @type string $next_text Anchor text to display in the next comments link.
* Default 'Newer comments'.
* @type string $screen_reader_text Screen reader text for nav element. Default 'Comments navigation'.
* }
* @return string Markup for comments links.
*/
function get_the_comments_navigation( $args = array() ) {
$navigation = '';
// Are there comments to navigate through?
if ( get_comment_pages_count() > 1 ) {
$args = wp_parse_args( $args, array(
'prev_text' => __( 'Older comments' ),
'next_text' => __( 'Newer comments' ),
'screen_reader_text' => __( 'Comments navigation' ),
) );
$prev_link = get_previous_comments_link( $args['prev_text'] );
$next_link = get_next_comments_link( $args['next_text'] );
if ( $prev_link ) {
$navigation .= '
' . $prev_link . '
';
}
if ( $next_link ) {
$navigation .= '
' . $next_link . '
';
}
$navigation = _navigation_markup( $navigation, 'comment-navigation', $args['screen_reader_text'] );
}
return $navigation;
}
/**
* Displays navigation to next/previous set of comments, when applicable.
*
* @since 4.4.0
*
* @param array $args See get_the_comments_navigation() for available arguments. Default empty array.
*/
function the_comments_navigation( $args = array() ) {
echo get_the_comments_navigation( $args );
}
/**
* Retrieves a paginated navigation to next/previous set of comments, when applicable.
*
* @since 4.4.0
*
* @see paginate_comments_links()
*
* @param array $args {
* Optional. Default pagination arguments.
*
* @type string $screen_reader_text Screen reader text for nav element. Default 'Comments navigation'.
* }
* @return string Markup for pagination links.
*/
function get_the_comments_pagination( $args = array() ) {
$navigation = '';
$args = wp_parse_args( $args, array(
'screen_reader_text' => __( 'Comments navigation' ),
) );
$args['echo'] = false;
// Make sure we get plain links, so we get a string we can work with.
$args['type'] = 'plain';
$links = paginate_comments_links( $args );
if ( $links ) {
$navigation = _navigation_markup( $links, 'comments-pagination', $args['screen_reader_text'] );
}
return $navigation;
}
/**
* Displays a paginated navigation to next/previous set of comments, when applicable.
*
* @since 4.4.0
*
* @param array $args See get_the_comments_pagination() for available arguments. Default empty array.
*/
function the_comments_pagination( $args = array() ) {
echo get_the_comments_pagination( $args );
}
/**
* Retrieves the Press This bookmarklet link.
*
* @since 2.6.0
*/
function get_shortcut_link() {
$link = '';
if ( wp_is_IE() ) {
/*
* Return the old/shorter bookmarklet code for MSIE 8 and lower,
* since they only support a max length of ~2000 characters for
* bookmark[let] URLs, which is way to small for our smarter one.
* Do update the version number so users do not get the "upgrade your
* bookmarklet" notice when using PT in those browsers.
*/
$ua = $_SERVER['HTTP_USER_AGENT'];
if ( ! empty( $ua ) && preg_match( '/\bMSIE (\d)/', $ua, $matches ) && (int) $matches[1] <= 8 ) {
$url = wp_json_encode( admin_url( 'press-this.php' ) );
$link = 'javascript:var d=document,w=window,e=w.getSelection,k=d.getSelection,x=d.selection,' .
's=(e?e():(k)?k():(x?x.createRange().text:0)),f=' . $url . ',l=d.location,e=encodeURIComponent,' .
'u=f+"?u="+e(l.href)+"&t="+e(d.title)+"&s="+e(s)+"&v=' . WP_Press_This::VERSION . '";' .
'a=function(){if(!w.open(u,"t","toolbar=0,resizable=1,scrollbars=1,status=1,width=600,height=700"))l.href=u;};' .
'if(/Firefox/.test(navigator.userAgent))setTimeout(a,0);else a();void(0)';
}
}
if ( empty( $link ) ) {
$src = @file_get_contents( ABSPATH . 'wp-admin/js/bookmarklet.min.js' );
if ( $src ) {
$url = wp_json_encode( admin_url( 'press-this.php' ) . '?v=' . WP_Press_This::VERSION );
$link = 'javascript:' . str_replace( 'window.pt_url', $url, $src );
}
}
$link = str_replace( array( "\r", "\n", "\t" ), '', $link );
/**
* Filters the Press This bookmarklet link.
*
* @since 2.6.0
*
* @param string $link The Press This bookmarklet link.
*/
return apply_filters( 'shortcut_link', $link );
}
/**
* Retrieves the URL for the current site where the front end is accessible.
*
* Returns the 'home' option with the appropriate protocol, 'https' if
* is_ssl() and 'http' otherwise. If `$scheme` is 'http' or 'https',
* `is_ssl()` is overridden.
*
* @since 3.0.0
*
* @param string $path Optional. Path relative to the home URL. Default empty.
* @param string|null $scheme Optional. Scheme to give the home URL context. Accepts
* 'http', 'https', 'relative', 'rest', or null. Default null.
* @return string Home URL link with optional path appended.
*/
function home_url( $path = '', $scheme = null ) {
return get_home_url( null, $path, $scheme );
}
/**
* Retrieves the URL for a given site where the front end is accessible.
*
* Returns the 'home' option with the appropriate protocol, 'https' if
* is_ssl() and 'http' otherwise. If `$scheme` is 'http' or 'https',
* `is_ssl()` is overridden.
*
* @since 3.0.0
*
* @global string $pagenow
*
* @param int $blog_id Optional. Site ID. Default null (current site).
* @param string $path Optional. Path relative to the home URL. Default empty.
* @param string|null $scheme Optional. Scheme to give the home URL context. Accepts
* 'http', 'https', 'relative', 'rest', or null. Default null.
* @return string Home URL link with optional path appended.
*/
function get_home_url( $blog_id = null, $path = '', $scheme = null ) {
global $pagenow;
$orig_scheme = $scheme;
if ( empty( $blog_id ) || !is_multisite() ) {
$url = get_option( 'home' );
} else {
switch_to_blog( $blog_id );
$url = get_option( 'home' );
restore_current_blog();
}
if ( ! in_array( $scheme, array( 'http', 'https', 'relative' ) ) ) {
if ( is_ssl() && ! is_admin() && 'wp-login.php' !== $pagenow )
$scheme = 'https';
else
$scheme = parse_url( $url, PHP_URL_SCHEME );
}
$url = set_url_scheme( $url, $scheme );
if ( $path && is_string( $path ) )
$url .= '/' . ltrim( $path, '/' );
/**
* Filters the home URL.
*
* @since 3.0.0
*
* @param string $url The complete home URL including scheme and path.
* @param string $path Path relative to the home URL. Blank string if no path is specified.
* @param string|null $orig_scheme Scheme to give the home URL context. Accepts 'http', 'https',
* 'relative', 'rest', or null.
* @param int|null $blog_id Site ID, or null for the current site.
*/
return apply_filters( 'home_url', $url, $path, $orig_scheme, $blog_id );
}
/**
* Retrieves the URL for the current site where WordPress application files
* (e.g. wp-blog-header.php or the wp-admin/ folder) are accessible.
*
* Returns the 'site_url' option with the appropriate protocol, 'https' if
* is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
* overridden.
*
* @since 3.0.0
*
* @param string $path Optional. Path relative to the site URL. Default empty.
* @param string $scheme Optional. Scheme to give the site URL context. See set_url_scheme().
* @return string Site URL link with optional path appended.
*/
function site_url( $path = '', $scheme = null ) {
return get_site_url( null, $path, $scheme );
}
/**
* Retrieves the URL for a given site where WordPress application files
* (e.g. wp-blog-header.php or the wp-admin/ folder) are accessible.
*
* Returns the 'site_url' option with the appropriate protocol, 'https' if
* is_ssl() and 'http' otherwise. If `$scheme` is 'http' or 'https',
* `is_ssl()` is overridden.
*
* @since 3.0.0
*
* @param int $blog_id Optional. Site ID. Default null (current site).
* @param string $path Optional. Path relative to the site URL. Default empty.
* @param string $scheme Optional. Scheme to give the site URL context. Accepts
* 'http', 'https', 'login', 'login_post', 'admin', or
* 'relative'. Default null.
* @return string Site URL link with optional path appended.
*/
function get_site_url( $blog_id = null, $path = '', $scheme = null ) {
if ( empty( $blog_id ) || !is_multisite() ) {
$url = get_option( 'siteurl' );
} else {
switch_to_blog( $blog_id );
$url = get_option( 'siteurl' );
restore_current_blog();
}
$url = set_url_scheme( $url, $scheme );
if ( $path && is_string( $path ) )
$url .= '/' . ltrim( $path, '/' );
/**
* Filters the site URL.
*
* @since 2.7.0
*
* @param string $url The complete site URL including scheme and path.
* @param string $path Path relative to the site URL. Blank string if no path is specified.
* @param string|null $scheme Scheme to give the site URL context. Accepts 'http', 'https', 'login',
* 'login_post', 'admin', 'relative' or null.
* @param int|null $blog_id Site ID, or null for the current site.
*/
return apply_filters( 'site_url', $url, $path, $scheme, $blog_id );
}
/**
* Retrieves the URL to the admin area for the current site.
*
* @since 2.6.0
*
* @param string $path Optional path relative to the admin URL.
* @param string $scheme The scheme to use. Default is 'admin', which obeys force_ssl_admin() and is_ssl().
* 'http' or 'https' can be passed to force those schemes.
* @return string Admin URL link with optional path appended.
*/
function admin_url( $path = '', $scheme = 'admin' ) {
return get_admin_url( null, $path, $scheme );
}
/**
* Retrieves the URL to the admin area for a given site.
*
* @since 3.0.0
*
* @param int $blog_id Optional. Site ID. Default null (current site).
* @param string $path Optional. Path relative to the admin URL. Default empty.
* @param string $scheme Optional. The scheme to use. Accepts 'http' or 'https',
* to force those schemes. Default 'admin', which obeys
* force_ssl_admin() and is_ssl().
* @return string Admin URL link with optional path appended.
*/
function get_admin_url( $blog_id = null, $path = '', $scheme = 'admin' ) {
$url = get_site_url($blog_id, 'wp-admin/', $scheme);
if ( $path && is_string( $path ) )
$url .= ltrim( $path, '/' );
/**
* Filters the admin area URL.
*
* @since 2.8.0
*
* @param string $url The complete admin area URL including scheme and path.
* @param string $path Path relative to the admin area URL. Blank string if no path is specified.
* @param int|null $blog_id Site ID, or null for the current site.
*/
return apply_filters( 'admin_url', $url, $path, $blog_id );
}
/**
* Retrieves the URL to the includes directory.
*
* @since 2.6.0
*
* @param string $path Optional. Path relative to the includes URL. Default empty.
* @param string $scheme Optional. Scheme to give the includes URL context. Accepts
* 'http', 'https', or 'relative'. Default null.
* @return string Includes URL link with optional path appended.
*/
function includes_url( $path = '', $scheme = null ) {
$url = site_url( '/' . WPINC . '/', $scheme );
if ( $path && is_string( $path ) )
$url .= ltrim($path, '/');
/**
* Filters the URL to the includes directory.
*
* @since 2.8.0
*
* @param string $url The complete URL to the includes directory including scheme and path.
* @param string $path Path relative to the URL to the wp-includes directory. Blank string
* if no path is specified.
*/
return apply_filters( 'includes_url', $url, $path );
}
/**
* Retrieves the URL to the content directory.
*
* @since 2.6.0
*
* @param string $path Optional. Path relative to the content URL. Default empty.
* @return string Content URL link with optional path appended.
*/
function content_url( $path = '' ) {
$url = set_url_scheme( WP_CONTENT_URL );
if ( $path && is_string( $path ) )
$url .= '/' . ltrim($path, '/');
/**
* Filters the URL to the content directory.
*
* @since 2.8.0
*
* @param string $url The complete URL to the content directory including scheme and path.
* @param string $path Path relative to the URL to the content directory. Blank string
* if no path is specified.
*/
return apply_filters( 'content_url', $url, $path);
}
/**
* Retrieves a URL within the plugins or mu-plugins directory.
*
* Defaults to the plugins directory URL if no arguments are supplied.
*
* @since 2.6.0
*
* @param string $path Optional. Extra path appended to the end of the URL, including
* the relative directory if $plugin is supplied. Default empty.
* @param string $plugin Optional. A full path to a file inside a plugin or mu-plugin.
* The URL will be relative to its directory. Default empty.
* Typically this is done by passing `__FILE__` as the argument.
* @return string Plugins URL link with optional paths appended.
*/
function plugins_url( $path = '', $plugin = '' ) {
$path = wp_normalize_path( $path );
$plugin = wp_normalize_path( $plugin );
$mu_plugin_dir = wp_normalize_path( WPMU_PLUGIN_DIR );
if ( !empty($plugin) && 0 === strpos($plugin, $mu_plugin_dir) )
$url = WPMU_PLUGIN_URL;
else
$url = WP_PLUGIN_URL;
$url = set_url_scheme( $url );
if ( !empty($plugin) && is_string($plugin) ) {
$folder = dirname(plugin_basename($plugin));
if ( '.' != $folder )
$url .= '/' . ltrim($folder, '/');
}
if ( $path && is_string( $path ) )
$url .= '/' . ltrim($path, '/');
/**
* Filters the URL to the plugins directory.
*
* @since 2.8.0
*
* @param string $url The complete URL to the plugins directory including scheme and path.
* @param string $path Path relative to the URL to the plugins directory. Blank string
* if no path is specified.
* @param string $plugin The plugin file path to be relative to. Blank string if no plugin
* is specified.
*/
return apply_filters( 'plugins_url', $url, $path, $plugin );
}
/**
* Retrieves the site URL for the current network.
*
* Returns the site URL with the appropriate protocol, 'https' if
* is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
* overridden.
*
* @since 3.0.0
*
* @see set_url_scheme()
*
* @param string $path Optional. Path relative to the site URL. Default empty.
* @param string $scheme Optional. Scheme to give the site URL context. Accepts
* 'http', 'https', or 'relative'. Default null.
* @return string Site URL link with optional path appended.
*/
function network_site_url( $path = '', $scheme = null ) {
if ( ! is_multisite() )
return site_url($path, $scheme);
$current_site = get_current_site();
if ( 'relative' == $scheme ) {
$url = $current_site->path;
} else {
$url = set_url_scheme( 'http://' . $current_site->domain . $current_site->path, $scheme );
}
if ( $path && is_string( $path ) ) {
$url .= ltrim( $path, '/' );
}
/**
* Filters the network site URL.
*
* @since 3.0.0
*
* @param string $url The complete network site URL including scheme and path.
* @param string $path Path relative to the network site URL. Blank string if
* no path is specified.
* @param string|null $scheme Scheme to give the URL context. Accepts 'http', 'https',
* 'relative' or null.
*/
return apply_filters( 'network_site_url', $url, $path, $scheme );
}
/**
* Retrieves the home URL for the current network.
*
* Returns the home URL with the appropriate protocol, 'https' is_ssl()
* and 'http' otherwise. If `$scheme` is 'http' or 'https', `is_ssl()` is
* overridden.
*
* @since 3.0.0
*
* @param string $path Optional. Path relative to the home URL. Default empty.
* @param string $scheme Optional. Scheme to give the home URL context. Accepts
* 'http', 'https', or 'relative'. Default null.
* @return string Home URL link with optional path appended.
*/
function network_home_url( $path = '', $scheme = null ) {
if ( ! is_multisite() )
return home_url($path, $scheme);
$current_site = get_current_site();
$orig_scheme = $scheme;
if ( ! in_array( $scheme, array( 'http', 'https', 'relative' ) ) )
$scheme = is_ssl() && ! is_admin() ? 'https' : 'http';
if ( 'relative' == $scheme ) {
$url = $current_site->path;
} else {
$url = set_url_scheme( 'http://' . $current_site->domain . $current_site->path, $scheme );
}
if ( $path && is_string( $path ) ) {
$url .= ltrim( $path, '/' );
}
/**
* Filters the network home URL.
*
* @since 3.0.0
*
* @param string $url The complete network home URL including scheme and path.
* @param string $path Path relative to the network home URL. Blank string
* if no path is specified.
* @param string|null $orig_scheme Scheme to give the URL context. Accepts 'http', 'https',
* 'relative' or null.
*/
return apply_filters( 'network_home_url', $url, $path, $orig_scheme);
}
/**
* Retrieves the URL to the admin area for the network.
*
* @since 3.0.0
*
* @param string $path Optional path relative to the admin URL. Default empty.
* @param string $scheme Optional. The scheme to use. Default is 'admin', which obeys force_ssl_admin()
* and is_ssl(). 'http' or 'https' can be passed to force those schemes.
* @return string Admin URL link with optional path appended.
*/
function network_admin_url( $path = '', $scheme = 'admin' ) {
if ( ! is_multisite() )
return admin_url( $path, $scheme );
$url = network_site_url('wp-admin/network/', $scheme);
if ( $path && is_string( $path ) )
$url .= ltrim($path, '/');
/**
* Filters the network admin URL.
*
* @since 3.0.0
*
* @param string $url The complete network admin URL including scheme and path.
* @param string $path Path relative to the network admin URL. Blank string if
* no path is specified.
*/
return apply_filters( 'network_admin_url', $url, $path );
}
/**
* Retrieves the URL to the admin area for the current user.
*
* @since 3.0.0
*
* @param string $path Optional. Path relative to the admin URL. Default empty.
* @param string $scheme Optional. The scheme to use. Default is 'admin', which obeys force_ssl_admin()
* and is_ssl(). 'http' or 'https' can be passed to force those schemes.
* @return string Admin URL link with optional path appended.
*/
function user_admin_url( $path = '', $scheme = 'admin' ) {
$url = network_site_url('wp-admin/user/', $scheme);
if ( $path && is_string( $path ) )
$url .= ltrim($path, '/');
/**
* Filters the user admin URL for the current user.
*
* @since 3.1.0
*
* @param string $url The complete URL including scheme and path.
* @param string $path Path relative to the URL. Blank string if
* no path is specified.
*/
return apply_filters( 'user_admin_url', $url, $path );
}
/**
* Retrieves the URL to the admin area for either the current site or the network depending on context.
*
* @since 3.1.0
*
* @param string $path Optional. Path relative to the admin URL. Default empty.
* @param string $scheme Optional. The scheme to use. Default is 'admin', which obeys force_ssl_admin()
* and is_ssl(). 'http' or 'https' can be passed to force those schemes.
* @return string Admin URL link with optional path appended.
*/
function self_admin_url( $path = '', $scheme = 'admin' ) {
if ( is_network_admin() )
return network_admin_url($path, $scheme);
elseif ( is_user_admin() )
return user_admin_url($path, $scheme);
else
return admin_url($path, $scheme);
}
/**
* Sets the scheme for a URL.
*
* @since 3.4.0
* @since 4.4.0 The 'rest' scheme was added.
*
* @param string $url Absolute URL that includes a scheme
* @param string|null $scheme Optional. Scheme to give $url. Currently 'http', 'https', 'login',
* 'login_post', 'admin', 'relative', 'rest', 'rpc', or null. Default null.
* @return string $url URL with chosen scheme.
*/
function set_url_scheme( $url, $scheme = null ) {
$orig_scheme = $scheme;
if ( ! $scheme ) {
$scheme = is_ssl() ? 'https' : 'http';
} elseif ( $scheme === 'admin' || $scheme === 'login' || $scheme === 'login_post' || $scheme === 'rpc' ) {
$scheme = is_ssl() || force_ssl_admin() ? 'https' : 'http';
} elseif ( $scheme !== 'http' && $scheme !== 'https' && $scheme !== 'relative' ) {
$scheme = is_ssl() ? 'https' : 'http';
}
$url = trim( $url );
if ( substr( $url, 0, 2 ) === '//' )
$url = 'http:' . $url;
if ( 'relative' == $scheme ) {
$url = ltrim( preg_replace( '#^\w+://[^/]*#', '', $url ) );
if ( $url !== '' && $url[0] === '/' )
$url = '/' . ltrim($url , "/ \t\n\r\0\x0B" );
} else {
$url = preg_replace( '#^\w+://#', $scheme . '://', $url );
}
/**
* Filters the resulting URL after setting the scheme.
*
* @since 3.4.0
*
* @param string $url The complete URL including scheme and path.
* @param string $scheme Scheme applied to the URL. One of 'http', 'https', or 'relative'.
* @param string|null $orig_scheme Scheme requested for the URL. One of 'http', 'https', 'login',
* 'login_post', 'admin', 'relative', 'rest', 'rpc', or null.
*/
return apply_filters( 'set_url_scheme', $url, $scheme, $orig_scheme );
}
/**
* Retrieves the URL to the user's dashboard.
*
* If a user does not belong to any site, the global user dashboard is used. If the user
* belongs to the current site, the dashboard for the current site is returned. If the user
* cannot edit the current site, the dashboard to the user's primary site is returned.
*
* @since 3.1.0
*
* @param int $user_id Optional. User ID. Defaults to current user.
* @param string $path Optional path relative to the dashboard. Use only paths known to
* both site and user admins. Default empty.
* @param string $scheme The scheme to use. Default is 'admin', which obeys force_ssl_admin()
* and is_ssl(). 'http' or 'https' can be passed to force those schemes.
* @return string Dashboard URL link with optional path appended.
*/
function get_dashboard_url( $user_id = 0, $path = '', $scheme = 'admin' ) {
$user_id = $user_id ? (int) $user_id : get_current_user_id();
$blogs = get_blogs_of_user( $user_id );
if ( ! is_super_admin() && empty($blogs) ) {
$url = user_admin_url( $path, $scheme );
} elseif ( ! is_multisite() ) {
$url = admin_url( $path, $scheme );
} else {
$current_blog = get_current_blog_id();
if ( $current_blog && ( is_super_admin( $user_id ) || in_array( $current_blog, array_keys( $blogs ) ) ) ) {
$url = admin_url( $path, $scheme );
} else {
$active = get_active_blog_for_user( $user_id );
if ( $active )
$url = get_admin_url( $active->blog_id, $path, $scheme );
else
$url = user_admin_url( $path, $scheme );
}
}
/**
* Filters the dashboard URL for a user.
*
* @since 3.1.0
*
* @param string $url The complete URL including scheme and path.
* @param int $user_id The user ID.
* @param string $path Path relative to the URL. Blank string if no path is specified.
* @param string $scheme Scheme to give the URL context. Accepts 'http', 'https', 'login',
* 'login_post', 'admin', 'relative' or null.
*/
return apply_filters( 'user_dashboard_url', $url, $user_id, $path, $scheme);
}
/**
* Retrieves the URL to the user's profile editor.
*
* @since 3.1.0
*
* @param int $user_id Optional. User ID. Defaults to current user.
* @param string $scheme Optional. The scheme to use. Default is 'admin', which obeys force_ssl_admin()
* and is_ssl(). 'http' or 'https' can be passed to force those schemes.
* @return string Dashboard URL link with optional path appended.
*/
function get_edit_profile_url( $user_id = 0, $scheme = 'admin' ) {
$user_id = $user_id ? (int) $user_id : get_current_user_id();
if ( is_user_admin() )
$url = user_admin_url( 'profile.php', $scheme );
elseif ( is_network_admin() )
$url = network_admin_url( 'profile.php', $scheme );
else
$url = get_dashboard_url( $user_id, 'profile.php', $scheme );
/**
* Filters the URL for a user's profile editor.
*
* @since 3.1.0
*
* @param string $url The complete URL including scheme and path.
* @param int $user_id The user ID.
* @param string $scheme Scheme to give the URL context. Accepts 'http', 'https', 'login',
* 'login_post', 'admin', 'relative' or null.
*/
return apply_filters( 'edit_profile_url', $url, $user_id, $scheme);
}
/**
* Returns the canonical URL for a post.
*
* When the post is the same as the current requested page the function will handle the
* pagination arguments too.
*
* @since 4.6.0
*
* @param int|WP_Post $post Optional. Post ID or object. Default is global `$post`.
* @return string|false The canonical URL, or false if the post does not exist or has not
* been published yet.
*/
function wp_get_canonical_url( $post = null ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
if ( 'publish' !== $post->post_status ) {
return false;
}
$canonical_url = get_permalink( $post );
// If a canonical is being generated for the current page, make sure it has pagination if needed.
if ( $post->ID === get_queried_object_id() ) {
$page = get_query_var( 'page', 0 );
if ( $page >= 2 ) {
if ( '' == get_option( 'permalink_structure' ) ) {
$canonical_url = add_query_arg( 'page', $page, $canonical_url );
} else {
$canonical_url = trailingslashit( $canonical_url ) . user_trailingslashit( $page, 'single_paged' );
}
}
$cpage = get_query_var( 'cpage', 0 );
if ( $cpage ) {
$canonical_url = get_comments_pagenum_link( $cpage );
}
}
/**
* Filters the canonical URL for a post.
*
* @since 4.6.0
*
* @param string $string The post's canonical URL.
* @param WP_Post $post Post object.
*/
return apply_filters( 'get_canonical_url', $canonical_url, $post );
}
/**
* Outputs rel=canonical for singular queries.
*
* @since 2.9.0
* @since 4.6.0 Adjusted to use wp_get_canonical_url().
*/
function rel_canonical() {
if ( ! is_singular() ) {
return;
}
$id = get_queried_object_id();
if ( 0 === $id ) {
return;
}
$url = wp_get_canonical_url( $id );
if ( ! empty( $url ) ) {
echo '' . "\n";
}
}
/**
* Returns a shortlink for a post, page, attachment, or site.
*
* This function exists to provide a shortlink tag that all themes and plugins can target.
* A plugin must hook in to provide the actual shortlinks. Default shortlink support is
* limited to providing ?p= style links for posts. Plugins can short-circuit this function
* via the {@see 'pre_get_shortlink'} filter or filter the output via the {@see 'get_shortlink'}
* filter.
*
* @since 3.0.0.
*
* @param int $id Optional. A post or site id. Default is 0, which means the current post or site.
* @param string $context Optional. Whether the id is a 'site' id, 'post' id, or 'media' id. If 'post',
* the post_type of the post is consulted. If 'query', the current query is consulted
* to determine the id and context. Default 'post'.
* @param bool $allow_slugs Optional. Whether to allow post slugs in the shortlink. It is up to the plugin how
* and whether to honor this. Default true.
* @return string A shortlink or an empty string if no shortlink exists for the requested resource or if shortlinks
* are not enabled.
*/
function wp_get_shortlink( $id = 0, $context = 'post', $allow_slugs = true ) {
/**
* Filters whether to preempt generating a shortlink for the given post.
*
* Passing a truthy value to the filter will effectively short-circuit the
* shortlink-generation process, returning that value instead.
*
* @since 3.0.0
*
* @param bool|string $return Short-circuit return value. Either false or a URL string.
* @param int $id Post ID, or 0 for the current post.
* @param string $context The context for the link. One of 'post' or 'query',
* @param bool $allow_slugs Whether to allow post slugs in the shortlink.
*/
$shortlink = apply_filters( 'pre_get_shortlink', false, $id, $context, $allow_slugs );
if ( false !== $shortlink ) {
return $shortlink;
}
$post_id = 0;
if ( 'query' == $context && is_singular() ) {
$post_id = get_queried_object_id();
$post = get_post( $post_id );
} elseif ( 'post' == $context ) {
$post = get_post( $id );
if ( ! empty( $post->ID ) )
$post_id = $post->ID;
}
$shortlink = '';
// Return p= link for all public post types.
if ( ! empty( $post_id ) ) {
$post_type = get_post_type_object( $post->post_type );
if ( 'page' === $post->post_type && $post->ID == get_option( 'page_on_front' ) && 'page' == get_option( 'show_on_front' ) ) {
$shortlink = home_url( '/' );
} elseif ( $post_type->public ) {
$shortlink = home_url( '?p=' . $post_id );
}
}
/**
* Filters the shortlink for a post.
*
* @since 3.0.0
*
* @param string $shortlink Shortlink URL.
* @param int $id Post ID, or 0 for the current post.
* @param string $context The context for the link. One of 'post' or 'query',
* @param bool $allow_slugs Whether to allow post slugs in the shortlink. Not used by default.
*/
return apply_filters( 'get_shortlink', $shortlink, $id, $context, $allow_slugs );
}
/**
* Injects rel=shortlink into the head if a shortlink is defined for the current page.
*
* Attached to the {@see 'wp_head'} action.
*
* @since 3.0.0
*/
function wp_shortlink_wp_head() {
$shortlink = wp_get_shortlink( 0, 'query' );
if ( empty( $shortlink ) )
return;
echo "\n";
}
/**
* Sends a Link: rel=shortlink header if a shortlink is defined for the current page.
*
* Attached to the {@see 'wp'} action.
*
* @since 3.0.0
*/
function wp_shortlink_header() {
if ( headers_sent() )
return;
$shortlink = wp_get_shortlink(0, 'query');
if ( empty($shortlink) )
return;
header('Link: <' . $shortlink . '>; rel=shortlink', false);
}
/**
* Displays the shortlink for a post.
*
* Must be called from inside "The Loop"
*
* Call like the_shortlink( __( 'Shortlinkage FTW' ) )
*
* @since 3.0.0
*
* @param string $text Optional The link text or HTML to be displayed. Defaults to 'This is the short link.'
* @param string $title Optional The tooltip for the link. Must be sanitized. Defaults to the sanitized post title.
* @param string $before Optional HTML to display before the link. Default empty.
* @param string $after Optional HTML to display after the link. Default empty.
*/
function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) {
$post = get_post();
if ( empty( $text ) )
$text = __('This is the short link.');
if ( empty( $title ) )
$title = the_title_attribute( array( 'echo' => false ) );
$shortlink = wp_get_shortlink( $post->ID );
if ( !empty( $shortlink ) ) {
$link = '' . $text . '';
/**
* Filters the short link anchor tag for a post.
*
* @since 3.0.0
*
* @param string $link Shortlink anchor tag.
* @param string $shortlink Shortlink URL.
* @param string $text Shortlink's text.
* @param string $title Shortlink's title attribute.
*/
$link = apply_filters( 'the_shortlink', $link, $shortlink, $text, $title );
echo $before, $link, $after;
}
}
/**
* Retrieves the avatar URL.
*
* @since 4.2.0
*
* @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash,
* user email, WP_User object, WP_Post object, or WP_Comment object.
* @param array $args {
* Optional. Arguments to return instead of the default arguments.
*
* @type int $size Height and width of the avatar in pixels. Default 96.
* @type string $default URL for the default image or a default type. Accepts '404' (return
* a 404 instead of a default image), 'retro' (8bit), 'monsterid' (monster),
* 'wavatar' (cartoon face), 'indenticon' (the "quilt"), 'mystery', 'mm',
* or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF), or
* 'gravatar_default' (the Gravatar logo). Default is the value of the
* 'avatar_default' option, with a fallback of 'mystery'.
* @type bool $force_default Whether to always show the default image, never the Gravatar. Default false.
* @type string $rating What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are
* judged in that order. Default is the value of the 'avatar_rating' option.
* @type string $scheme URL scheme to use. See set_url_scheme() for accepted values.
* Default null.
* @type array $processed_args When the function returns, the value will be the processed/sanitized $args
* plus a "found_avatar" guess. Pass as a reference. Default null.
* }
* @return false|string The URL of the avatar we found, or false if we couldn't find an avatar.
*/
function get_avatar_url( $id_or_email, $args = null ) {
$args = get_avatar_data( $id_or_email, $args );
return $args['url'];
}
/**
* Retrieves default data about the avatar.
*
* @since 4.2.0
*
* @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
* user email, WP_User object, WP_Post object, or WP_Comment object.
* @param array $args {
* Optional. Arguments to return instead of the default arguments.
*
* @type int $size Height and width of the avatar image file in pixels. Default 96.
* @type int $height Display height of the avatar in pixels. Defaults to $size.
* @type int $width Display width of the avatar in pixels. Defaults to $size.
* @type string $default URL for the default image or a default type. Accepts '404' (return
* a 404 instead of a default image), 'retro' (8bit), 'monsterid' (monster),
* 'wavatar' (cartoon face), 'indenticon' (the "quilt"), 'mystery', 'mm',
* or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF), or
* 'gravatar_default' (the Gravatar logo). Default is the value of the
* 'avatar_default' option, with a fallback of 'mystery'.
* @type bool $force_default Whether to always show the default image, never the Gravatar. Default false.
* @type string $rating What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are
* judged in that order. Default is the value of the 'avatar_rating' option.
* @type string $scheme URL scheme to use. See set_url_scheme() for accepted values.
* Default null.
* @type array $processed_args When the function returns, the value will be the processed/sanitized $args
* plus a "found_avatar" guess. Pass as a reference. Default null.
* @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized. Default empty.
* }
* @return array $processed_args {
* Along with the arguments passed in `$args`, this will contain a couple of extra arguments.
*
* @type bool $found_avatar True if we were able to find an avatar for this user,
* false or not set if we couldn't.
* @type string $url The URL of the avatar we found.
* }
*/
function get_avatar_data( $id_or_email, $args = null ) {
$args = wp_parse_args( $args, array(
'size' => 96,
'height' => null,
'width' => null,
'default' => get_option( 'avatar_default', 'mystery' ),
'force_default' => false,
'rating' => get_option( 'avatar_rating' ),
'scheme' => null,
'processed_args' => null, // if used, should be a reference
'extra_attr' => '',
) );
if ( is_numeric( $args['size'] ) ) {
$args['size'] = absint( $args['size'] );
if ( ! $args['size'] ) {
$args['size'] = 96;
}
} else {
$args['size'] = 96;
}
if ( is_numeric( $args['height'] ) ) {
$args['height'] = absint( $args['height'] );
if ( ! $args['height'] ) {
$args['height'] = $args['size'];
}
} else {
$args['height'] = $args['size'];
}
if ( is_numeric( $args['width'] ) ) {
$args['width'] = absint( $args['width'] );
if ( ! $args['width'] ) {
$args['width'] = $args['size'];
}
} else {
$args['width'] = $args['size'];
}
if ( empty( $args['default'] ) ) {
$args['default'] = get_option( 'avatar_default', 'mystery' );
}
switch ( $args['default'] ) {
case 'mm' :
case 'mystery' :
case 'mysteryman' :
$args['default'] = 'mm';
break;
case 'gravatar_default' :
$args['default'] = false;
break;
}
$args['force_default'] = (bool) $args['force_default'];
$args['rating'] = strtolower( $args['rating'] );
$args['found_avatar'] = false;
/**
* Filters whether to retrieve the avatar URL early.
*
* Passing a non-null value in the 'url' member of the return array will
* effectively short circuit get_avatar_data(), passing the value through
* the {@see 'get_avatar_data'} filter and returning early.
*
* @since 4.2.0
*
* @param array $args Arguments passed to get_avatar_data(), after processing.
* @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
* user email, WP_User object, WP_Post object, or WP_Comment object.
*/
$args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email );
if ( isset( $args['url'] ) && ! is_null( $args['url'] ) ) {
/** This filter is documented in wp-includes/link-template.php */
return apply_filters( 'get_avatar_data', $args, $id_or_email );
}
$email_hash = '';
$user = $email = false;
if ( is_object( $id_or_email ) && isset( $id_or_email->comment_ID ) ) {
$id_or_email = get_comment( $id_or_email );
}
// Process the user identifier.
if ( is_numeric( $id_or_email ) ) {
$user = get_user_by( 'id', absint( $id_or_email ) );
} elseif ( is_string( $id_or_email ) ) {
if ( strpos( $id_or_email, '@md5.gravatar.com' ) ) {
// md5 hash
list( $email_hash ) = explode( '@', $id_or_email );
} else {
// email address
$email = $id_or_email;
}
} elseif ( $id_or_email instanceof WP_User ) {
// User Object
$user = $id_or_email;
} elseif ( $id_or_email instanceof WP_Post ) {
// Post Object
$user = get_user_by( 'id', (int) $id_or_email->post_author );
} elseif ( $id_or_email instanceof WP_Comment ) {
/**
* Filters the list of allowed comment types for retrieving avatars.
*
* @since 3.0.0
*
* @param array $types An array of content types. Default only contains 'comment'.
*/
$allowed_comment_types = apply_filters( 'get_avatar_comment_types', array( 'comment' ) );
if ( ! empty( $id_or_email->comment_type ) && ! in_array( $id_or_email->comment_type, (array) $allowed_comment_types ) ) {
$args['url'] = false;
/** This filter is documented in wp-includes/link-template.php */
return apply_filters( 'get_avatar_data', $args, $id_or_email );
}
if ( ! empty( $id_or_email->user_id ) ) {
$user = get_user_by( 'id', (int) $id_or_email->user_id );
}
if ( ( ! $user || is_wp_error( $user ) ) && ! empty( $id_or_email->comment_author_email ) ) {
$email = $id_or_email->comment_author_email;
}
}
if ( ! $email_hash ) {
if ( $user ) {
$email = $user->user_email;
}
if ( $email ) {
$email_hash = md5( strtolower( trim( $email ) ) );
}
}
if ( $email_hash ) {
$args['found_avatar'] = true;
$gravatar_server = hexdec( $email_hash[0] ) % 3;
} else {
$gravatar_server = rand( 0, 2 );
}
$url_args = array(
's' => $args['size'],
'd' => $args['default'],
'f' => $args['force_default'] ? 'y' : false,
'r' => $args['rating'],
);
if ( is_ssl() ) {
$url = 'https://secure.gravatar.com/avatar/' . $email_hash;
} else {
$url = sprintf( 'http://%d.gravatar.com/avatar/%s', $gravatar_server, $email_hash );
}
$url = add_query_arg(
rawurlencode_deep( array_filter( $url_args ) ),
set_url_scheme( $url, $args['scheme'] )
);
/**
* Filters the avatar URL.
*
* @since 4.2.0
*
* @param string $url The URL of the avatar.
* @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
* user email, WP_User object, WP_Post object, or WP_Comment object.
* @param array $args Arguments passed to get_avatar_data(), after processing.
*/
$args['url'] = apply_filters( 'get_avatar_url', $url, $id_or_email, $args );
/**
* Filters the avatar data.
*
* @since 4.2.0
*
* @param array $args Arguments passed to get_avatar_data(), after processing.
* @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
* user email, WP_User object, WP_Post object, or WP_Comment object.
*/
return apply_filters( 'get_avatar_data', $args, $id_or_email );
}