X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/9441756a895fb4fdc4bcf20e0d228cef622663ca..3d39054f012aefe514b3f5509e32f09fc4feda44:/wp-includes/general-template.php?ds=sidebyside diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index 79b42e9c..a5d5ea7d 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -36,14 +36,13 @@ function get_header( $name = null ) { $templates = array(); $name = (string) $name; - if ( '' !== $name ) + if ( '' !== $name ) { $templates[] = "header-{$name}.php"; + } $templates[] = 'header.php'; - // Backward compat code will be removed in a future release - if ('' == locate_template($templates, true)) - load_template( ABSPATH . WPINC . '/theme-compat/header.php'); + locate_template( $templates, true ); } /** @@ -76,14 +75,13 @@ function get_footer( $name = null ) { $templates = array(); $name = (string) $name; - if ( '' !== $name ) + if ( '' !== $name ) { $templates[] = "footer-{$name}.php"; + } - $templates[] = 'footer.php'; + $templates[] = 'footer.php'; - // Backward compat code will be removed in a future release - if ('' == locate_template($templates, true)) - load_template( ABSPATH . WPINC . '/theme-compat/footer.php'); + locate_template( $templates, true ); } /** @@ -121,9 +119,7 @@ function get_sidebar( $name = null ) { $templates[] = 'sidebar.php'; - // Backward compat code will be removed in a future release - if ('' == locate_template($templates, true)) - load_template( ABSPATH . WPINC . '/theme-compat/sidebar.php'); + locate_template( $templates, true ); } /** @@ -178,13 +174,13 @@ function get_template_part( $slug, $name = null ) { * the parent, then load it. If it doesn't exist, then the default search form * will be displayed. The default search form is HTML, which will be displayed. * There is a filter applied to the search form HTML in order to edit or replace - * it. The filter is 'get_search_form'. + * it. The filter is {@see 'get_search_form'}. * * This function is primarily used by themes which want to hardcode the search * form into the sidebar and also by the search widget in WordPress. * * There is also an action that is called whenever the function is run called, - * 'pre_get_search_form'. This can be useful for outputting JavaScript that the + * {@see 'pre_get_search_form'}. This can be useful for outputting JavaScript that the * search relies on or various formatting that applies to the beginning of the * search. To give a few examples of what it can be used for. * @@ -207,7 +203,7 @@ function get_search_form( $echo = true ) { $format = current_theme_supports( 'html5', 'search-form' ) ? 'html5' : 'xhtml'; /** - * Filter the HTML format of the search form. + * Filters the HTML format of the search form. * * @since 3.6.0 * @@ -226,7 +222,7 @@ function get_search_form( $echo = true ) { $form = ''; @@ -242,7 +238,7 @@ function get_search_form( $echo = true ) { } /** - * Filter the HTML output of the search form. + * Filters the HTML output of the search form. * * @since 2.7.0 * @@ -279,7 +275,7 @@ function wp_loginout($redirect = '', $echo = true) { if ( $echo ) { /** - * Filter the HTML output for the Log In/Log Out link. + * Filters the HTML output for the Log In/Log Out link. * * @since 1.5.0 * @@ -293,14 +289,14 @@ function wp_loginout($redirect = '', $echo = true) { } /** - * Returns the Log Out URL. + * Retrieves the logout URL. * * Returns the URL that allows the user to log out of the site. * * @since 2.7.0 * * @param string $redirect Path to redirect to on logout. - * @return string A log out URL. + * @return string The logout URL. Note: HTML-encoded via esc_html() in wp_nonce_url(). */ function wp_logout_url($redirect = '') { $args = array( 'action' => 'logout' ); @@ -312,24 +308,25 @@ function wp_logout_url($redirect = '') { $logout_url = wp_nonce_url( $logout_url, 'log-out' ); /** - * Filter the logout URL. + * Filters the logout URL. * * @since 2.8.0 * - * @param string $logout_url The Log Out URL. + * @param string $logout_url The HTML-encoded logout URL. * @param string $redirect Path to redirect to on logout. */ return apply_filters( 'logout_url', $logout_url, $redirect ); } /** - * Returns the URL that allows the user to log in to the site. + * Retrieves the login URL. * * @since 2.7.0 * - * @param string $redirect Path to redirect to on login. - * @param bool $force_reauth Whether to force reauthorization, even if a cookie is present. Default is false. - * @return string A log in URL. + * @param string $redirect Path to redirect to on log in. + * @param bool $force_reauth Whether to force reauthorization, even if a cookie is present. + * Default false. + * @return string The login URL. Not HTML-encoded. */ function wp_login_url($redirect = '', $force_reauth = false) { $login_url = site_url('wp-login.php', 'login'); @@ -341,12 +338,12 @@ function wp_login_url($redirect = '', $force_reauth = false) { $login_url = add_query_arg('reauth', '1', $login_url); /** - * Filter the login URL. + * Filters the login URL. * * @since 2.8.0 * @since 4.2.0 The `$force_reauth` parameter was added. * - * @param string $login_url The login URL. + * @param string $login_url The login URL. Not HTML-encoded. * @param string $redirect The path to redirect to on login, if supplied. * @param bool $force_reauth Whether to force reauthorization, even if a cookie is present. */ @@ -362,7 +359,7 @@ function wp_login_url($redirect = '', $force_reauth = false) { */ function wp_registration_url() { /** - * Filter the user registration URL. + * Filters the user registration URL. * * @since 3.6.0 * @@ -386,7 +383,7 @@ function wp_registration_url() { * @type string $redirect URL to redirect to. Must be absolute, as in "https://example.com/mypage/". * Default is to redirect back to the request URI. * @type string $form_id ID attribute value for the form. Default 'loginform'. - * @type string $label_username Label for the username field. Default 'Username'. + * @type string $label_username Label for the username or email address field. Default 'Username or Email'. * @type string $label_password Label for the password field. Default 'Password'. * @type string $label_remember Label for the remember field. Default 'Remember Me'. * @type string $label_log_in Label for the submit button. Default 'Log In'. @@ -408,7 +405,7 @@ function wp_login_form( $args = array() ) { // Default 'redirect' value takes the user back to the request URI. 'redirect' => ( is_ssl() ? 'https://' : 'http://' ) . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'], 'form_id' => 'loginform', - 'label_username' => __( 'Username' ), + 'label_username' => __( 'Username or Email' ), 'label_password' => __( 'Password' ), 'label_remember' => __( 'Remember Me' ), 'label_log_in' => __( 'Log In' ), @@ -423,7 +420,7 @@ function wp_login_form( $args = array() ) { ); /** - * Filter the default login form output arguments. + * Filters the default login form output arguments. * * @since 3.0.0 * @@ -434,7 +431,7 @@ function wp_login_form( $args = array() ) { $args = wp_parse_args( $args, apply_filters( 'login_form_defaults', $defaults ) ); /** - * Filter content to display at the top of the login form. + * Filters content to display at the top of the login form. * * The filter evaluates just following the opening form tag element. * @@ -446,7 +443,7 @@ function wp_login_form( $args = array() ) { $login_form_top = apply_filters( 'login_form_top', '', $args ); /** - * Filter content to display in the middle of the login form. + * Filters content to display in the middle of the login form. * * The filter evaluates just following the location where the 'login-password' * field is displayed. @@ -459,7 +456,7 @@ function wp_login_form( $args = array() ) { $login_form_middle = apply_filters( 'login_form_middle', '', $args ); /** - * Filter content to display at the bottom of the login form. + * Filters content to display at the bottom of the login form. * * The filter evaluates just preceding the closing form tag element. * @@ -513,7 +510,7 @@ function wp_lostpassword_url( $redirect = '' ) { $lostpassword_url = add_query_arg( $args, network_site_url('wp-login.php', 'login') ); /** - * Filter the Lost Password URL. + * Filters the Lost Password URL. * * @since 2.8.0 * @@ -549,7 +546,7 @@ function wp_register( $before = '
  • ', $after = '
    • ', $echo = true ) { } /** - * Filter the HTML link to the Registration or Admin page. + * Filters the HTML link to the Registration or Admin page. * * Users are sent to the admin page if logged-in, or the registration page * if enabled and logged-out. @@ -570,7 +567,7 @@ function wp_register( $before = '
  • ', $after = '
    • ', $echo = true ) { /** * Theme container function for the 'wp_meta' action. * - * The 'wp_meta' action can have several purposes, depending on how you use it, + * The {@see 'wp_meta'} action can have several purposes, depending on how you use it, * but one purpose might have been to allow for theme switching. * * @since 1.5.0 @@ -587,49 +584,70 @@ function wp_meta() { } /** - * Display information about the blog. + * Displays information about the current site. * - * @see get_bloginfo() For possible values for the parameter. * @since 0.71 * - * @param string $show What to display. + * @see get_bloginfo() For possible `$show` values + * + * @param string $show Optional. Site information to display. Default empty. */ -function bloginfo( $show='' ) { +function bloginfo( $show = '' ) { echo get_bloginfo( $show, 'display' ); } /** - * Retrieve information about the blog. - * - * Some show parameter values are deprecated and will be removed in future - * versions. These options will trigger the {@see _deprecated_argument()} - * function. The deprecated blog info options are listed in the function - * contents. - * - * The possible values for the 'show' parameter are listed below. - * - * 1. url - Blog URI to homepage. - * 2. wpurl - Blog URI path to WordPress. - * 3. description - Secondary title - * - * The feed URL options can be retrieved from 'rdf_url' (RSS 0.91), - * 'rss_url' (RSS 1.0), 'rss2_url' (RSS 2.0), or 'atom_url' (Atom feed). The - * comment feeds can be retrieved from the 'comments_atom_url' (Atom comment - * feed) or 'comments_rss2_url' (RSS 2.0 comment feed). + * Retrieves information about the current site. + * + * Possible values for `$show` include: + * + * - 'name' - Site title (set in Settings > General) + * - 'description' - Site tagline (set in Settings > General) + * - 'wpurl' - The WordPress address (URL) (set in Settings > General) + * - 'url' - The Site address (URL) (set in Settings > General) + * - 'admin_email' - Admin email (set in Settings > General) + * - 'charset' - The "Encoding for pages and feeds" (set in Settings > Reading) + * - 'version' - The current WordPress version + * - 'html_type' - The content-type (default: "text/html"). Themes and plugins + * can override the default value using the {@see 'pre_option_html_type'} filter + * - 'text_direction' - The text direction determined by the site's language. is_rtl() + * should be used instead + * - 'language' - Language code for the current site + * - 'stylesheet_url' - URL to the stylesheet for the active theme. An active child theme + * will take precedence over this value + * - 'stylesheet_directory' - Directory path for the active theme. An active child theme + * will take precedence over this value + * - 'template_url' / 'template_directory' - URL of the active theme's directory. An active + * child theme will NOT take precedence over this value + * - 'pingback_url' - The pingback XML-RPC file URL (xmlrpc.php) + * - 'atom_url' - The Atom feed URL (/feed/atom) + * - 'rdf_url' - The RDF/RSS 1.0 feed URL (/feed/rfd) + * - 'rss_url' - The RSS 0.92 feed URL (/feed/rss) + * - 'rss2_url' - The RSS 2.0 feed URL (/feed) + * - 'comments_atom_url' - The comments Atom feed URL (/comments/feed) + * - 'comments_rss2_url' - The comments RSS 2.0 feed URL (/comments/feed) + * + * Some `$show` values are deprecated and will be removed in future versions. + * These options will trigger the _deprecated_argument() function. + * + * Deprecated arguments include: + * + * - 'siteurl' - Use 'url' instead + * - 'home' - Use 'url' instead * * @since 0.71 * * @global string $wp_version * - * @param string $show Blog info to retrieve. - * @param string $filter How to filter what is retrieved. + * @param string $show Optional. Site info to retrieve. Default empty (site name). + * @param string $filter Optional. How to filter what is retrieved. Default 'raw'. * @return string Mostly string values, might be empty. */ function get_bloginfo( $show = '', $filter = 'raw' ) { switch( $show ) { case 'home' : // DEPRECATED case 'siteurl' : // DEPRECATED - _deprecated_argument( __FUNCTION__, '2.2', sprintf( + _deprecated_argument( __FUNCTION__, '2.2.0', sprintf( /* translators: 1: 'siteurl'/'home' argument, 2: bloginfo() function name, 3: 'url' argument */ __( 'The %1$s option is deprecated for the family of %2$s functions. Use the %3$s option instead.' ), '' . $show . '', @@ -691,11 +709,18 @@ function get_bloginfo( $show = '', $filter = 'raw' ) { $output = $wp_version; break; case 'language': - $output = get_locale(); - $output = str_replace('_', '-', $output); + /* translators: Translate this to the correct language tag for your locale, + * see https://www.w3.org/International/articles/language-tags/ for reference. + * Do not translate into your own language. + */ + $output = __( 'html_lang_attribute' ); + if ( 'html_lang_attribute' === $output || preg_match( '/[^a-zA-Z0-9-]/', $output ) ) { + $output = get_locale(); + $output = str_replace( '_', '-', $output ); + } break; case 'text_direction': - _deprecated_argument( __FUNCTION__, '2.2', sprintf( + _deprecated_argument( __FUNCTION__, '2.2.0', sprintf( /* translators: 1: 'text_direction' argument, 2: bloginfo() function name, 3: is_rtl() function name */ __( 'The %1$s option is deprecated for the family of %2$s functions. Use the %3$s function instead.' ), '' . $show . '', @@ -723,7 +748,7 @@ function get_bloginfo( $show = '', $filter = 'raw' ) { if ( 'display' == $filter ) { if ( $url ) { /** - * Filter the URL returned by get_bloginfo(). + * Filters the URL returned by get_bloginfo(). * * @since 2.0.5 * @@ -733,7 +758,7 @@ function get_bloginfo( $show = '', $filter = 'raw' ) { $output = apply_filters( 'bloginfo_url', $output, $show ); } else { /** - * Filter the site information returned by get_bloginfo(). + * Filters the site information returned by get_bloginfo(). * * @since 0.71 * @@ -778,7 +803,7 @@ function get_site_icon_url( $size = 512, $url = '', $blog_id = 0 ) { } /** - * Filter the site icon URL. + * Filters the site icon URL. * * @site 4.4.0 * @@ -814,6 +839,90 @@ function has_site_icon( $blog_id = 0 ) { return (bool) get_site_icon_url( 512, '', $blog_id ); } +/** + * Determines whether the site has a custom logo. + * + * @since 4.5.0 + * + * @param int $blog_id Optional. ID of the blog in question. Default is the ID of the current blog. + * @return bool Whether the site has a custom logo or not. + */ +function has_custom_logo( $blog_id = 0 ) { + if ( is_multisite() && (int) $blog_id !== get_current_blog_id() ) { + switch_to_blog( $blog_id ); + } + + $custom_logo_id = get_theme_mod( 'custom_logo' ); + + if ( is_multisite() && ms_is_switched() ) { + restore_current_blog(); + } + + return (bool) $custom_logo_id; +} + +/** + * Returns a custom logo, linked to home. + * + * @since 4.5.0 + * + * @param int $blog_id Optional. ID of the blog in question. Default is the ID of the current blog. + * @return string Custom logo markup. + */ +function get_custom_logo( $blog_id = 0 ) { + $html = ''; + + if ( is_multisite() && (int) $blog_id !== get_current_blog_id() ) { + switch_to_blog( $blog_id ); + } + + $custom_logo_id = get_theme_mod( 'custom_logo' ); + + // We have a logo. Logo is go. + if ( $custom_logo_id ) { + $html = sprintf( '', + esc_url( home_url( '/' ) ), + wp_get_attachment_image( $custom_logo_id, 'full', false, array( + 'class' => 'custom-logo', + 'itemprop' => 'logo', + ) ) + ); + } + + // If no logo is set but we're in the Customizer, leave a placeholder (needed for the live preview). + elseif ( is_customize_preview() ) { + $html = sprintf( '', + esc_url( home_url( '/' ) ) + ); + } + + if ( is_multisite() && ms_is_switched() ) { + restore_current_blog(); + } + + /** + * Filters the custom logo output. + * + * @since 4.5.0 + * @since 4.6.0 Added the `$blog_id` parameter. + * + * @param string $html Custom logo HTML output. + * @param int $blog_id ID of the blog to get the custom logo for. + */ + return apply_filters( 'get_custom_logo', $html, $blog_id ); +} + +/** + * Displays a custom logo, linked to home. + * + * @since 4.5.0 + * + * @param int $blog_id Optional. ID of the blog in question. Default is the ID of the current blog. + */ +function the_custom_logo( $blog_id = 0 ) { + echo get_custom_logo( $blog_id ); +} + /** * Returns document title for the current page. * @@ -827,7 +936,7 @@ function has_site_icon( $blog_id = 0 ) { function wp_get_document_title() { /** - * Filter the document title before it is generated. + * Filters the document title before it is generated. * * Passing a non-empty value will short-circuit wp_get_document_title(), * returning that value instead. @@ -907,7 +1016,7 @@ function wp_get_document_title() { } /** - * Filter the separator for the document title. + * Filters the separator for the document title. * * @since 4.4.0 * @@ -916,7 +1025,7 @@ function wp_get_document_title() { $sep = apply_filters( 'document_title_separator', '-' ); /** - * Filter the parts of the document title. + * Filters the parts of the document title. * * @since 4.4.0 * @@ -965,10 +1074,10 @@ function _wp_render_title_tag() { * important, which is the page that the user is looking at. * * There are also SEO benefits to having the blog title after or to the 'right' - * or the page title. However, it is mostly common sense to have the blog title + * of the page title. However, it is mostly common sense to have the blog title * to the right with most browsers supporting tabs. You can achieve this by * using the seplocation parameter and setting the value to 'right'. This change - * was introduced around 2.5.0, in case backwards compatibility of themes is + * was introduced around 2.5.0, in case backward compatibility of themes is * important. * * @since 1.0.0 @@ -991,7 +1100,7 @@ function wp_title( $sep = '»', $display = true, $seplocation = '' ) { $search = get_query_var( 's' ); $title = ''; - $t_sep = '%WP_TITILE_SEP%'; // Temporary separator, for accurate flipping, if necessary + $t_sep = '%WP_TITLE_SEP%'; // Temporary separator, for accurate flipping, if necessary // If there is a post if ( is_single() || ( is_home() && ! is_front_page() ) || ( is_page() && ! is_front_page() ) ) { @@ -1073,7 +1182,7 @@ function wp_title( $sep = '»', $display = true, $seplocation = '' ) { } /** - * Filter the parts of the page title. + * Filters the parts of the page title. * * @since 4.0.0 * @@ -1090,7 +1199,7 @@ function wp_title( $sep = '»', $display = true, $seplocation = '' ) { } /** - * Filter the text of the page title. + * Filters the text of the page title. * * @since 2.0.0 * @@ -1131,7 +1240,7 @@ function single_post_title( $prefix = '', $display = true ) { return; /** - * Filter the page title for a single post. + * Filters the page title for a single post. * * @since 0.71 * @@ -1168,7 +1277,7 @@ function post_type_archive_title( $prefix = '', $display = true ) { $post_type_obj = get_post_type_object( $post_type ); /** - * Filter the post type archive title. + * Filters the post type archive title. * * @since 3.1.0 * @@ -1238,7 +1347,7 @@ function single_term_title( $prefix = '', $display = true ) { if ( is_category() ) { /** - * Filter the category archive page title. + * Filters the category archive page title. * * @since 2.0.10 * @@ -1247,7 +1356,7 @@ function single_term_title( $prefix = '', $display = true ) { $term_name = apply_filters( 'single_cat_title', $term->name ); } elseif ( is_tag() ) { /** - * Filter the tag archive page title. + * Filters the tag archive page title. * * @since 2.3.0 * @@ -1256,7 +1365,7 @@ function single_term_title( $prefix = '', $display = true ) { $term_name = apply_filters( 'single_tag_title', $term->name ); } elseif ( is_tax() ) { /** - * Filter the custom taxonomy archive page title. + * Filters the custom taxonomy archive page title. * * @since 3.1.0 * @@ -1386,7 +1495,7 @@ function get_the_archive_title() { } /** - * Filter the archive title. + * Filters the archive title. * * @since 4.1.0 * @@ -1421,7 +1530,7 @@ function the_archive_description( $before = '', $after = '' ) { */ function get_the_archive_description() { /** - * Filter the archive description. + * Filters the archive description. * * @since 4.1.0 * @@ -1458,13 +1567,11 @@ function get_the_archive_description() { * * @since 1.0.0 * - * @todo Properly document optional arguments as such - * * @param string $url URL to archive. * @param string $text Archive text description. * @param string $format Optional, default is 'html'. Can be 'link', 'option', 'html', or custom. - * @param string $before Optional. - * @param string $after Optional. + * @param string $before Optional. Content to prepend to the description. Default empty. + * @param string $after Optional. Content to append to the description. Default empty. * @return string HTML link content for archive. */ function get_archives_link($url, $text, $format = 'html', $before = '', $after = '') { @@ -1481,13 +1588,19 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after = $link_html = "\t$before$text$after\n"; /** - * Filter the archive link content. + * Filters the archive link content. * * @since 2.6.0 + * @since 4.5.0 Added the `$url`, `$text`, `$format`, `$before`, and `$after` parameters. * * @param string $link_html The archive HTML link content. + * @param string $url URL to archive. + * @param string $text Archive text description. + * @param string $format Link format. Can be 'link', 'option', 'html', or custom. + * @param string $before Content to prepend to the description. + * @param string $after Content to append to the description. */ - return apply_filters( 'get_archives_link', $link_html ); + return apply_filters( 'get_archives_link', $link_html, $url, $text, $format, $before, $after ); } /** @@ -1561,26 +1674,10 @@ function wp_get_archives( $args = '' ) { // this is what will separate dates on weekly archive links $archive_week_separator = '–'; - // over-ride general date format ? 0 = no: use the date format set in Options, 1 = yes: over-ride - $archive_date_format_over_ride = 0; - - // options for daily archive (only if you over-ride the general date format) - $archive_day_date_format = 'Y/m/d'; - - // options for weekly archive (only if you over-ride the general date format) - $archive_week_start_date_format = 'Y/m/d'; - $archive_week_end_date_format = 'Y/m/d'; - - if ( ! $archive_date_format_over_ride ) { - $archive_day_date_format = get_option( 'date_format' ); - $archive_week_start_date_format = get_option( 'date_format' ); - $archive_week_end_date_format = get_option( 'date_format' ); - } - $sql_where = $wpdb->prepare( "WHERE post_type = %s AND post_status = 'publish'", $r['post_type'] ); /** - * Filter the SQL WHERE clause for retrieving archives. + * Filters the SQL WHERE clause for retrieving archives. * * @since 2.2.0 * @@ -1590,7 +1687,7 @@ function wp_get_archives( $args = '' ) { $where = apply_filters( 'getarchives_where', $sql_where, $r ); /** - * Filter the SQL JOIN clause for retrieving archives. + * Filters the SQL JOIN clause for retrieving archives. * * @since 2.2.0 * @@ -1670,7 +1767,7 @@ function wp_get_archives( $args = '' ) { $url = add_query_arg( 'post_type', $r['post_type'], $url ); } $date = sprintf( '%1$d-%2$02d-%3$02d 00:00:00', $result->year, $result->month, $result->dayofmonth ); - $text = mysql2date( $archive_day_date_format, $date ); + $text = mysql2date( get_option( 'date_format' ), $date ); if ( $r['show_post_count'] ) { $r['after'] = ' (' . $result->posts . ')' . $after; } @@ -1694,9 +1791,9 @@ function wp_get_archives( $args = '' ) { $arc_year = $result->yr; $arc_w_last = $result->week; $arc_week = get_weekstartend( $result->yyyymmdd, get_option( 'start_of_week' ) ); - $arc_week_start = date_i18n( $archive_week_start_date_format, $arc_week['start'] ); - $arc_week_end = date_i18n( $archive_week_end_date_format, $arc_week['end'] ); - $url = sprintf( '%1$s/%2$s%3$sm%4$s%5$s%6$sw%7$s%8$d', home_url(), '', '?', '=', $arc_year, '&', '=', $result->week ); + $arc_week_start = date_i18n( get_option( 'date_format' ), $arc_week['start'] ); + $arc_week_end = date_i18n( get_option( 'date_format' ), $arc_week['end'] ); + $url = add_query_arg( array( 'm' => $arc_year, 'w' => $result->week, ), home_url( '/' ) ); if ( 'post' !== $r['post_type'] ) { $url = add_query_arg( 'post_type', $r['post_type'], $url ); } @@ -1971,7 +2068,7 @@ function get_calendar( $initial = true, $echo = true ) { if ( $echo ) { /** - * Filter the HTML calendar output. + * Filters the HTML calendar output. * * @since 3.0.0 * @@ -2063,7 +2160,7 @@ function the_date( $d = '', $before = '', $after = '', $echo = true ) { $previousday = $currentday; /** - * Filter the date a post was published for display. + * Filters the date a post was published for display. * * @since 0.71 * @@ -2086,7 +2183,7 @@ function the_date( $d = '', $before = '', $after = '', $echo = true ) { * Retrieve the date on which the post was written. * * Unlike the_date() this function will always return the date. - * Modify output with 'get_the_date' filter. + * Modify output with the {@see 'get_the_date'} filter. * * @since 3.0.0 * @@ -2108,7 +2205,7 @@ function get_the_date( $d = '', $post = null ) { } /** - * Filter the date a post was published. + * Filters the date a post was published. * * @since 3.0.0 * @@ -2135,7 +2232,7 @@ function the_modified_date( $d = '', $before = '', $after = '', $echo = true ) { $the_modified_date = $before . get_the_modified_date($d) . $after; /** - * Filter the date a post was last modified for display. + * Filters the date a post was last modified for display. * * @since 2.1.0 * @@ -2158,26 +2255,36 @@ function the_modified_date( $d = '', $before = '', $after = '', $echo = true ) { * Retrieve the date on which the post was last modified. * * @since 2.1.0 + * @since 4.6.0 Added the `$post` parameter. * - * @param string $d Optional. PHP date format. Defaults to the "date_format" option - * @return string + * @param string $d Optional. PHP date format defaults to the date_format option if not specified. + * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default current post. + * @return false|string Date the current post was modified. False on failure. */ -function get_the_modified_date($d = '') { - if ( '' == $d ) - $the_time = get_post_modified_time(get_option('date_format'), null, null, true); - else - $the_time = get_post_modified_time($d, null, null, true); +function get_the_modified_date( $d = '', $post = null ) { + $post = get_post( $post ); + + if ( ! $post ) { + // For backward compatibility, failures go through the filter below. + $the_time = false; + } elseif ( empty( $d ) ) { + $the_time = get_post_modified_time( get_option( 'date_format' ), false, $post, true ); + } else { + $the_time = get_post_modified_time( $d, false, $post, true ); + } /** - * Filter the date a post was last modified. + * Filters the date a post was last modified. * * @since 2.1.0 + * @since 4.6.0 Added the `$post` parameter. * - * @param string $the_time The formatted date. - * @param string $d PHP date format. Defaults to value specified in - * 'date_format' option. + * @param string $the_time The formatted date. + * @param string $d PHP date format. Defaults to value specified in + * 'date_format' option. + * @param WP_Post $post WP_Post object. */ - return apply_filters( 'get_the_modified_date', $the_time, $d ); + return apply_filters( 'get_the_modified_date', $the_time, $d, $post ); } /** @@ -2189,7 +2296,7 @@ function get_the_modified_date($d = '') { */ function the_time( $d = '' ) { /** - * Filter the time a post was written for display. + * Filters the time a post was written for display. * * @since 0.71 * @@ -2209,7 +2316,7 @@ function the_time( $d = '' ) { * was written. Either 'G', 'U', or php date format defaults * to the value specified in the time_format option. Default empty. * @param int|WP_Post $post WP_Post object or ID. Default is global $post object. - * @return false|string Formatted date string or Unix timestamp. False on failure. + * @return string|int|false Formatted date string or Unix timestamp if `$id` is 'U' or 'G'. False on failure. */ function get_the_time( $d = '', $post = null ) { $post = get_post($post); @@ -2224,7 +2331,7 @@ function get_the_time( $d = '', $post = null ) { $the_time = get_post_time($d, false, $post, true); /** - * Filter the time a post was written. + * Filters the time a post was written. * * @since 1.5.0 * @@ -2247,7 +2354,7 @@ function get_the_time( $d = '', $post = null ) { * @param bool $gmt Optional. Whether to retrieve the GMT time. Default false. * @param int|WP_Post $post WP_Post object or ID. Default is global $post object. * @param bool $translate Whether to translate the time string. Default false. - * @return false|string|int Formatted date string or Unix timestamp. False on failure. + * @return string|int|false Formatted date string or Unix timestamp if `$id` is 'U' or 'G'. False on failure. */ function get_post_time( $d = 'U', $gmt = false, $post = null, $translate = false ) { $post = get_post($post); @@ -2264,7 +2371,7 @@ function get_post_time( $d = 'U', $gmt = false, $post = null, $translate = false $time = mysql2date($d, $time, $translate); /** - * Filter the localized time a post was written. + * Filters the localized time a post was written. * * @since 2.6.0 * @@ -2285,7 +2392,7 @@ function get_post_time( $d = 'U', $gmt = false, $post = null, $translate = false */ function the_modified_time($d = '') { /** - * Filter the localized time a post was last modified, for display. + * Filters the localized time a post was last modified, for display. * * @since 2.0.0 * @@ -2301,27 +2408,39 @@ function the_modified_time($d = '') { * Retrieve the time at which the post was last modified. * * @since 2.0.0 + * @since 4.6.0 Added the `$post` parameter. * - * @param string $d Optional Either 'G', 'U', or php date format defaults to the value specified in the time_format option. - * @return string + * @param string $d Optional. Format to use for retrieving the time the post + * was modified. Either 'G', 'U', or php date format defaults + * to the value specified in the time_format option. Default empty. + * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default current post. + * @return false|string Formatted date string or Unix timestamp. False on failure. */ -function get_the_modified_time($d = '') { - if ( '' == $d ) - $the_time = get_post_modified_time(get_option('time_format'), null, null, true); - else - $the_time = get_post_modified_time($d, null, null, true); +function get_the_modified_time( $d = '', $post = null ) { + $post = get_post( $post ); + + if ( ! $post ) { + // For backward compatibility, failures go through the filter below. + $the_time = false; + } elseif ( empty( $d ) ) { + $the_time = get_post_modified_time( get_option( 'time_format' ), false, $post, true ); + } else { + $the_time = get_post_modified_time( $d, false, $post, true ); + } /** - * Filter the localized time a post was last modified. + * Filters the localized time a post was last modified. * * @since 2.0.0 + * @since 4.6.0 Added the `$post` parameter. * * @param string $the_time The formatted time. * @param string $d Format to use for retrieving the time the post was * written. Accepts 'G', 'U', or php date format. Defaults * to value specified in 'time_format' option. + * @param WP_Post $post WP_Post object. */ - return apply_filters( 'get_the_modified_time', $the_time, $d ); + return apply_filters( 'get_the_modified_time', $the_time, $d, $post ); } /** @@ -2334,7 +2453,7 @@ function get_the_modified_time($d = '') { * @param bool $gmt Optional. Whether to retrieve the GMT time. Default false. * @param int|WP_Post $post WP_Post object or ID. Default is global $post object. * @param bool $translate Whether to translate the time string. Default false. - * @return false|string Formatted date string or Unix timestamp. False on failure. + * @return string|int|false Formatted date string or Unix timestamp if `$id` is 'U' or 'G'. False on failure. */ function get_post_modified_time( $d = 'U', $gmt = false, $post = null, $translate = false ) { $post = get_post($post); @@ -2350,7 +2469,7 @@ function get_post_modified_time( $d = 'U', $gmt = false, $post = null, $translat $time = mysql2date($d, $time, $translate); /** - * Filter the localized time a post was last modified. + * Filters the localized time a post was last modified. * * @since 2.8.0 * @@ -2373,7 +2492,7 @@ function the_weekday() { $the_weekday = $wp_locale->get_weekday( mysql2date( 'w', get_post()->post_date, false ) ); /** - * Filter the weekday on which the post was written, for display. + * Filters the weekday on which the post was written, for display. * * @since 0.71 * @@ -2408,7 +2527,7 @@ function the_weekday_date($before='',$after='') { } /** - * Filter the localized date on which the post was written, for display. + * Filters the localized date on which the post was written, for display. * * @since 0.71 * @@ -2421,13 +2540,15 @@ function the_weekday_date($before='',$after='') { } /** - * Fire the wp_head action + * Fire the wp_head action. + * + * See {@see 'wp_head'}. * * @since 1.2.0 */ function wp_head() { /** - * Print scripts or data in the head tag on the front end. + * Prints scripts or data in the head tag on the front end. * * @since 1.5.0 */ @@ -2435,13 +2556,15 @@ function wp_head() { } /** - * Fire the wp_footer action + * Fire the wp_footer action. + * + * See {@see 'wp_footer'}. * * @since 1.5.1 */ function wp_footer() { /** - * Print scripts or data before the closing body tag on the front end. + * Prints scripts or data before the closing body tag on the front end. * * @since 1.5.1 */ @@ -2471,7 +2594,7 @@ function feed_links( $args = array() ) { $args = wp_parse_args( $args, $defaults ); /** - * Filter whether to display the posts feed link. + * Filters whether to display the posts feed link. * * @since 4.4.0 * @@ -2482,7 +2605,7 @@ function feed_links( $args = array() ) { } /** - * Filter whether to display the comments feed link. + * Filters whether to display the comments feed link. * * @since 4.4.0 * @@ -2510,6 +2633,8 @@ function feed_links_extra( $args = array() ) { 'cattitle' => __('%1$s %2$s %3$s Category Feed'), /* translators: 1: blog name, 2: separator(raquo), 3: tag name */ 'tagtitle' => __('%1$s %2$s %3$s Tag Feed'), + /* translators: 1: blog name, 2: separator(raquo), 3: term name, 4: taxonomy singular name */ + 'taxtitle' => __('%1$s %2$s %3$s %4$s Feed'), /* translators: 1: blog name, 2: separator(raquo), 3: author name */ 'authortitle' => __('%1$s %2$s Posts by %3$s Feed'), /* translators: 1: blog name, 2: separator(raquo), 3: search phrase */ @@ -2550,6 +2675,11 @@ function feed_links_extra( $args = array() ) { $title = sprintf( $args['tagtitle'], get_bloginfo('name'), $args['separator'], $term->name ); $href = get_tag_feed_link( $term->term_id ); } + } elseif ( is_tax() ) { + $term = get_queried_object(); + $tax = get_taxonomy( $term->taxonomy ); + $title = sprintf( $args['taxtitle'], get_bloginfo('name'), $args['separator'], $term->name, $tax->labels->singular_name ); + $href = get_term_feed_link( $term->term_id, $term->taxonomy ); } elseif ( is_author() ) { $author_id = intval( get_query_var('author') ); @@ -2582,7 +2712,7 @@ function rsd_link() { /** * Display the link to the Windows Live Writer manifest file. * - * @link http://msdn.microsoft.com/en-us/library/bb463265.aspx + * @link https://msdn.microsoft.com/en-us/library/bb463265.aspx * @since 2.3.1 */ function wlwmanifest_link() { @@ -2591,11 +2721,15 @@ function wlwmanifest_link() { } /** - * Display a noindex meta tag if required by the blog configuration. + * Displays a noindex meta tag if required by the blog configuration. * * If a blog is marked as not being public then the noindex meta tag will be - * output to tell web robots not to index the page content. Add this to the wp_head action. - * Typical usage is as a wp_head callback. add_action( 'wp_head', 'noindex' ); + * output to tell web robots not to index the page content. Add this to the + * {@see 'wp_head'} action. + * + * Typical usage is as a {@see 'wp_head'} callback: + * + * add_action( 'wp_head', 'noindex' ); * * @see wp_no_robots * @@ -2624,7 +2758,7 @@ function wp_no_robots() { * * @since 4.3.0 * - * @link http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#rel-icon HTML5 specification link icon. + * @link https://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#rel-icon HTML5 specification link icon. */ function wp_site_icon() { if ( ! has_site_icon() && ! is_customize_preview() ) { @@ -2639,7 +2773,7 @@ function wp_site_icon() { ); /** - * Filter the site icon meta tags, so Plugins can add their own. + * Filters the site icon meta tags, so Plugins can add their own. * * @since 4.3.0 * @@ -2653,6 +2787,110 @@ function wp_site_icon() { } } +/** + * Prints resource hints to browsers for pre-fetching, pre-rendering + * and pre-connecting to web sites. + * + * Gives hints to browsers to prefetch specific pages or render them + * in the background, to perform DNS lookups or to begin the connection + * handshake (DNS, TCP, TLS) in the background. + * + * These performance improving indicators work by using ``. + * + * @since 4.6.0 + */ +function wp_resource_hints() { + $hints = array( + 'dns-prefetch' => wp_dependencies_unique_hosts(), + 'preconnect' => array(), + 'prefetch' => array(), + 'prerender' => array(), + ); + + /* + * Add DNS prefetch for the Emoji CDN. + * The path is removed in the foreach loop below. + */ + /** This filter is documented in wp-includes/formatting.php */ + $hints['dns-prefetch'][] = apply_filters( 'emoji_svg_url', 'https://s.w.org/images/core/emoji/2/svg/' ); + + foreach ( $hints as $relation_type => $urls ) { + /** + * Filters domains and URLs for resource hints of relation type. + * + * @since 4.6.0 + * + * @param array $urls URLs to print for resource hints. + * @param string $relation_type The relation type the URLs are printed for, e.g. 'preconnect' or 'prerender'. + */ + $urls = apply_filters( 'wp_resource_hints', $urls, $relation_type ); + + foreach ( $urls as $key => $url ) { + $url = esc_url( $url, array( 'http', 'https' ) ); + if ( ! $url ) { + unset( $urls[ $key ] ); + continue; + } + + if ( in_array( $relation_type, array( 'preconnect', 'dns-prefetch' ) ) ) { + $parsed = wp_parse_url( $url ); + if ( empty( $parsed['host'] ) ) { + unset( $urls[ $key ] ); + continue; + } + + if ( 'preconnect' === $relation_type && ! empty( $parsed['scheme'] ) ) { + $url = $parsed['scheme'] . '://' . $parsed['host']; + } else { + // Use protocol-relative URLs for dns-prefetch or if scheme is missing. + $url = '//' . $parsed['host']; + } + } + + $urls[ $key ] = $url; + } + + $urls = array_unique( $urls ); + + foreach ( $urls as $url ) { + printf( "\n", $relation_type, $url ); + } + } +} + +/** + * Retrieves a list of unique hosts of all enqueued scripts and styles. + * + * @since 4.6.0 + * + * @return array A list of unique hosts of enqueued scripts and styles. + */ +function wp_dependencies_unique_hosts() { + global $wp_scripts, $wp_styles; + + $unique_hosts = array(); + + foreach ( array( $wp_scripts, $wp_styles ) as $dependencies ) { + if ( $dependencies instanceof WP_Dependencies && ! empty( $dependencies->queue ) ) { + foreach ( $dependencies->queue as $handle ) { + if ( ! isset( $dependencies->registered[ $handle ] ) ) { + continue; + } + + /* @var _WP_Dependency $dependency */ + $dependency = $dependencies->registered[ $handle ]; + $parsed = wp_parse_url( $dependency->src ); + + if ( ! empty( $parsed['host'] ) && ! in_array( $parsed['host'], $unique_hosts ) && $parsed['host'] !== $_SERVER['SERVER_NAME'] ) { + $unique_hosts[] = $parsed['host']; + } + } + } + } + + return $unique_hosts; +} + /** * Whether the user should have a WYSIWIG editor. * @@ -2686,7 +2924,7 @@ function user_can_richedit() { } /** - * Filter whether the user can access the rich (Visual) editor. + * Filters whether the user can access the rich (Visual) editor. * * @since 2.1.0 * @@ -2713,7 +2951,7 @@ function wp_default_editor() { } /** - * Filter which editor should be displayed by default. + * Filters which editor should be displayed by default. * * @since 2.5.0 * @@ -2729,12 +2967,12 @@ function wp_default_editor() { * _WP_Editors should not be used directly. See https://core.trac.wordpress.org/ticket/17144. * * NOTE: Once initialized the TinyMCE editor cannot be safely moved in the DOM. For that reason - * running wp_editor() inside of a metabox is not a good idea unless only Quicktags is used. + * running wp_editor() inside of a meta box is not a good idea unless only Quicktags is used. * On the post edit screen several actions can be used to include additional editors * containing TinyMCE: 'edit_page_form', 'edit_form_advanced' and 'dbx_post_sidebar'. * See https://core.trac.wordpress.org/ticket/19173 for more information. * - * @see wp-includes/class-wp-editor.php + * @see _WP_Editors::editor() * @since 3.3.0 * * @param string $content Initial content for the editor. @@ -2749,10 +2987,10 @@ function wp_editor( $content, $editor_id, $settings = array() ) { } /** - * Retrieve the contents of the search WordPress query variable. + * Retrieves the contents of the search WordPress query variable. * - * The search query string is passed through {@link esc_attr()} - * to ensure that it is safe for placing in an html attribute. + * The search query string is passed through esc_attr() to ensure that it is safe + * for placing in an html attribute. * * @since 2.3.0 * @@ -2762,7 +3000,7 @@ function wp_editor( $content, $editor_id, $settings = array() ) { */ function get_search_query( $escaped = true ) { /** - * Filter the contents of the search query variable. + * Filters the contents of the search query variable. * * @since 2.3.0 * @@ -2776,16 +3014,16 @@ function get_search_query( $escaped = true ) { } /** - * Display the contents of the search query variable. + * Displays the contents of the search query variable. * - * The search query string is passed through {@link esc_attr()} - * to ensure that it is safe for placing in an html attribute. + * The search query string is passed through esc_attr() to ensure that it is safe + * for placing in an html attribute. * * @since 2.1.0 */ function the_search_query() { /** - * Filter the contents of the search query variable for display. + * Filters the contents of the search query variable for display. * * @since 2.3.0 * @@ -2821,7 +3059,7 @@ function get_language_attributes( $doctype = 'html' ) { $output = implode(' ', $attributes); /** - * Filter the language attributes for display in the html tag. + * Filters the language attributes for display in the html tag. * * @since 2.5.0 * @since 4.3.0 Added the `$doctype` parameter. @@ -2885,7 +3123,7 @@ function language_attributes( $doctype = 'html' ) { * numbers to either side of current page, but not including current page. * * It is possible to add query vars to the link by using the 'add_args' argument - * and see {@link add_query_arg()} for more information. + * and see add_query_arg() for more information. * * The 'before_page_number' and 'after_page_number' arguments allow users to * augment the links themselves. Typically this might be to add context to the @@ -3009,7 +3247,7 @@ function paginate_links( $args = '' ) { $link .= $args['add_fragment']; /** - * Filter the paginated links for the given archive pages. + * Filters the paginated links for the given archive pages. * * @since 3.0.0 * @@ -3076,15 +3314,20 @@ function paginate_links( $args = '' ) { * * @since 2.5.0 * - * @todo Properly document optional arguments as such - * * @global array $_wp_admin_css_colors * * @param string $key The unique key for this theme. * @param string $name The name of the theme. - * @param string $url The url of the css file containing the colour scheme. - * @param array $colors Optional An array of CSS color definitions which are used to give the user a feel for the theme. - * @param array $icons Optional An array of CSS color definitions used to color any SVG icons + * @param string $url The URL of the CSS file containing the color scheme. + * @param array $colors Optional. An array of CSS color definition strings which are used + * to give the user a feel for the theme. + * @param array $icons { + * Optional. CSS color definitions used to color any SVG icons. + * + * @type string $base SVG icon base color. + * @type string $focus SVG icon color on focus. + * @type string $current SVG icon color of current admin menu link. + * } */ function wp_admin_css_color( $key, $name, $url, $colors = array(), $icons = array() ) { global $_wp_admin_css_colors; @@ -3114,7 +3357,7 @@ function register_admin_color_schemes() { wp_admin_css_color( 'fresh', _x( 'Default', 'admin color scheme' ), false, array( '#222', '#333', '#0073aa', '#00a0d2' ), - array( 'base' => '#999', 'focus' => '#00a0d2', 'current' => '#fff' ) + array( 'base' => '#82878c', 'focus' => '#00a0d2', 'current' => '#fff' ) ); // Other color schemes are not available when running out of src @@ -3166,9 +3409,9 @@ function register_admin_color_schemes() { } /** - * Display the URL of a WordPress admin CSS file. + * Displays the URL of a WordPress admin CSS file. * - * @see WP_Styles::_css_href and its style_loader_src filter. + * @see WP_Styles::_css_href and its {@see 'style_loader_src'} filter. * * @since 2.3.0 * @@ -3184,7 +3427,7 @@ function wp_admin_css_uri( $file = 'wp-admin' ) { $_file = add_query_arg( 'version', get_bloginfo( 'version' ), $_file ); /** - * Filter the URI of a WordPress admin CSS file. + * Filters the URI of a WordPress admin CSS file. * * @since 2.3.0 * @@ -3198,8 +3441,8 @@ function wp_admin_css_uri( $file = 'wp-admin' ) { * Enqueues or directly prints a stylesheet link to the specified CSS file. * * "Intelligently" decides to enqueue or to print the CSS file. If the - * 'wp_print_styles' action has *not* yet been called, the CSS file will be - * enqueued. If the wp_print_styles action *has* been called, the CSS link will + * {@see 'wp_print_styles'} action has *not* yet been called, the CSS file will be + * enqueued. If the {@see 'wp_print_styles'} action has been called, the CSS link will * be printed. Printing may be forced by passing true as the $force_echo * (second) parameter. * @@ -3227,7 +3470,7 @@ function wp_admin_css( $file = 'wp-admin', $force_echo = false ) { } /** - * Filter the stylesheet link to the specified CSS file. + * Filters the stylesheet link to the specified CSS file. * * If the site is set to display right-to-left, the RTL stylesheet link * will be used instead. @@ -3263,13 +3506,15 @@ function add_thickbox() { } /** - * Display the XHTML generator that is generated on the wp_head hook. + * Displays the XHTML generator that is generated on the wp_head hook. + * + * See {@see 'wp_head'}. * * @since 2.5.0 */ function wp_generator() { /** - * Filter the output of the XHTML generator tag. + * Filters the output of the XHTML generator tag. * * @since 2.5.0 * @@ -3282,7 +3527,7 @@ function wp_generator() { * Display the generator XML or Comment for RSS, ATOM, etc. * * Returns the correct generator type for the requested output format. Allows - * for a plugin to filter generators overall the the_generator filter. + * for a plugin to filter generators overall the {@see 'the_generator'} filter. * * @since 2.5.0 * @@ -3290,7 +3535,7 @@ function wp_generator() { */ function the_generator( $type ) { /** - * Filter the output of the XHTML generator tag for display. + * Filters the output of the XHTML generator tag for display. * * @since 2.5.0 * @@ -3306,7 +3551,7 @@ function the_generator( $type ) { * * Returns the correct generator type for the requested output format. Allows * for a plugin to filter generators on an individual basis using the - * 'get_the_generator_{$type}' filter. + * {@see 'get_the_generator_$type'} filter. * * @since 2.5.0 * @@ -3365,13 +3610,13 @@ function get_the_generator( $type = '' ) { } /** - * Filter the HTML for the retrieved generator type. + * Filters the HTML for the retrieved generator type. * * The dynamic portion of the hook name, `$type`, refers to the generator type. * * @since 2.5.0 * - * @param string $gen The HTML markup output to {@see wp_head()}. + * @param string $gen The HTML markup output to wp_head(). * @param string $type The type of generator. Accepts 'html', 'xhtml', 'atom', * 'rss2', 'rdf', 'comment', 'export'. */