X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/af50974463450c98503e763a7836a50e260461a9..53f4633144ed68c8b8fb5861f992b5489894a940:/wp-includes/general-template.php diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index 8655ceed..8f2cdf67 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -190,8 +190,8 @@ function get_template_part( $slug, $name = null ) { * * @since 2.7.0 * - * @param boolean $echo Default to echo and not return the form. - * @return string|null String when retrieving, null when displaying or if searchform.php exists. + * @param bool $echo Default to echo and not return the form. + * @return string|void String when $echo is false. */ function get_search_form( $echo = true ) { /** @@ -268,8 +268,8 @@ function get_search_form( $echo = true ) { * @since 1.5.0 * * @param string $redirect Optional path to redirect to on login/logout. - * @param boolean $echo Default to echo and not return the link. - * @return string|null String when retrieving, null when displaying. + * @param bool $echo Default to echo and not return the link. + * @return string|void String when retrieving. */ function wp_loginout($redirect = '', $echo = true) { if ( ! is_user_logged_in() ) @@ -323,14 +323,12 @@ function wp_logout_url($redirect = '') { } /** - * Returns the Log In URL. - * * Returns the URL that allows the user to log in to the site. * * @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. + * @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. */ function wp_login_url($redirect = '', $force_reauth = false) { @@ -346,16 +344,16 @@ function wp_login_url($redirect = '', $force_reauth = false) { * Filter 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 $redirect The path to redirect to on login, if supplied. + * @param string $login_url The login URL. + * @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. */ - return apply_filters( 'login_url', $login_url, $redirect ); + return apply_filters( 'login_url', $login_url, $redirect, $force_reauth ); } /** - * Returns the user registration URL. - * * Returns the URL that allows the user to register on the site. * * @since 3.6.0 @@ -380,7 +378,7 @@ function wp_registration_url() { * @since 3.0.0 * * @param array $args Configuration options to modify the form output. - * @return string|null String when retrieving, null when displaying. + * @return string|void String when retrieving. */ function wp_login_form( $args = array() ) { $defaults = array( @@ -475,8 +473,6 @@ function wp_login_form( $args = array() ) { } /** - * Returns the Lost Password URL. - * * Returns the URL that allows the user to retrieve the lost password * * @since 2.8.0 @@ -512,12 +508,11 @@ function wp_lostpassword_url( $redirect = '' ) { * @since 1.5.0 * * @param string $before Text to output before the link. Default `
  • `. - * @param string $after Text to output after the link. Default `
    • `. - * @param boolean $echo Default to echo and not return the link. - * @return string|null String when retrieving, null when displaying. + * @param string $after Text to output after the link. Default ``. + * @param bool $echo Default to echo and not return the link. + * @return string|void String when retrieving. */ function wp_register( $before = '
  • ', $after = '
    • ', $echo = true ) { - if ( ! is_user_logged_in() ) { if ( get_option('users_can_register') ) $link = $before . '' . __('Register') . '' . $after; @@ -598,16 +593,23 @@ function bloginfo( $show='' ) { * * @since 0.71 * - * @param string $show Blog info to retrieve. + * @global string $wp_version + * + * @param string $show Blog info to retrieve. * @param string $filter How to filter what is retrieved. * @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( __('The %s option is deprecated for the family of bloginfo() functions.' ), $show ) . ' ' . sprintf( __( 'Use the %s option instead.' ), 'url' ) ); + _deprecated_argument( __FUNCTION__, '2.2', 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 . '', + 'bloginfo()', + 'url' + ) ); case 'url' : $output = home_url(); break; @@ -667,7 +669,13 @@ function get_bloginfo( $show = '', $filter = 'raw' ) { $output = str_replace('_', '-', $output); break; case 'text_direction': - //_deprecated_argument( __FUNCTION__, '2.2', sprintf( __('The %s option is deprecated for the family of bloginfo() functions.' ), $show ) . ' ' . sprintf( __( 'Use the %s function instead.' ), 'is_rtl()' ) ); + _deprecated_argument( __FUNCTION__, '2.2', 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 . '', + 'bloginfo()', + 'is_rtl()' + ) ); if ( function_exists( 'is_rtl' ) ) { $output = is_rtl() ? 'rtl' : 'ltr'; } else { @@ -713,12 +721,63 @@ function get_bloginfo( $show = '', $filter = 'raw' ) { return $output; } +/** + * Returns the Site Icon URL. + * + * @param int $size Size of the site icon. + * @param string $url Fallback url if no site icon is found. + * @param int $blog_id Id of the blog to get the site icon for. + * @return string Site Icon URL. + */ +function get_site_icon_url( $size = 512, $url = '', $blog_id = 0 ) { + if ( $blog_id && is_multisite() ) { + $site_icon_id = get_blog_option( $blog_id, 'site_icon' ); + } else { + $site_icon_id = get_option( 'site_icon' ); + } + + if ( $site_icon_id ) { + if ( $size >= 512 ) { + $size_data = 'full'; + } else { + $size_data = array( $size, $size ); + } + $url_data = wp_get_attachment_image_src( $site_icon_id, $size_data ); + if ( $url_data ) { + $url = $url_data[0]; + } + } + + return $url; +} + +/** + * Displays the Site Icon URL. + * + * @param int $size Size of the site icon. + * @param string $url Fallback url if no site icon is found. + * @param int $blog_id Id of the blog to get the site icon for. + */ +function site_icon_url( $size = 512, $url = '', $blog_id = 0 ) { + echo esc_url( get_site_icon_url( $size, $url, $blog_id ) ); +} + +/** + * Whether the site has a Site Icon. + * + * @param int $blog_id Optional. Blog ID. Default: Current blog. + * @return bool + */ +function has_site_icon( $blog_id = 0 ) { + return (bool) get_site_icon_url( 512, '', $blog_id ); +} + /** * Display title tag with contents. * + * @ignore * @since 4.1.0 * @access private - * @internal * * @see wp_title() */ @@ -752,12 +811,16 @@ function _wp_render_title_tag() { * * @since 1.0.0 * - * @param string $sep Optional, default is '»'. How to separate the various items within the page title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @global WP_Locale $wp_locale + * @global int $page + * @global int $paged + * + * @param string $sep Optional, default is '»'. How to separate the various items within the page title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. * @param string $seplocation Optional. Direction to display title, 'right'. - * @return string|null String on retrieve, null when displaying. + * @return string|void String on retrieve. */ -function wp_title($sep = '»', $display = true, $seplocation = '') { +function wp_title( $sep = '»', $display = true, $seplocation = '' ) { global $wp_locale, $page, $paged; $m = get_query_var('m'); @@ -902,11 +965,11 @@ function wp_title($sep = '»', $display = true, $seplocation = '') { * * @since 0.71 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ -function single_post_title($prefix = '', $display = true) { +function single_post_title( $prefix = '', $display = true ) { $_post = get_queried_object(); if ( !isset($_post->post_title) ) @@ -935,9 +998,9 @@ function single_post_title($prefix = '', $display = true) { * * @since 3.1.0 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving, null when displaying or failure. */ function post_type_archive_title( $prefix = '', $display = true ) { if ( ! is_post_type_archive() ) @@ -978,9 +1041,9 @@ function post_type_archive_title( $prefix = '', $display = true ) { * * @since 0.71 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ function single_cat_title( $prefix = '', $display = true ) { return single_term_title( $prefix, $display ); @@ -999,9 +1062,9 @@ function single_cat_title( $prefix = '', $display = true ) { * * @since 2.3.0 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ function single_tag_title( $prefix = '', $display = true ) { return single_term_title( $prefix, $display ); @@ -1020,9 +1083,9 @@ function single_tag_title( $prefix = '', $display = true ) { * * @since 3.1.0 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ function single_term_title( $prefix = '', $display = true ) { $term = get_queried_object(); @@ -1084,9 +1147,11 @@ function single_term_title( $prefix = '', $display = true ) { * * @since 0.71 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @global WP_Locale $wp_locale + * + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ function single_month_title($prefix = '', $display = true ) { global $wp_locale; @@ -1256,11 +1321,11 @@ function get_the_archive_description() { * * @todo Properly document optional arguments as such * - * @param string $url URL to archive. - * @param string $text Archive text description. + * @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 $after Optional. * @return string HTML link content for archive. */ function get_archives_link($url, $text, $format = 'html', $before = '', $after = '') { @@ -1283,9 +1348,7 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after = * * @param string $link_html The archive HTML link content. */ - $link_html = apply_filters( 'get_archives_link', $link_html ); - - return $link_html; + return apply_filters( 'get_archives_link', $link_html ); } /** @@ -1295,6 +1358,9 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after = * * @see get_archives_link() * + * @global wpdb $wpdb + * @global WP_Locale $wp_locale + * * @param string|array $args { * Default archive links arguments. Optional. * @@ -1312,11 +1378,11 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after = * @type string $before Markup to prepend to the beginning of each link. Default empty. * @type string $after Markup to append to the end of each link. Default empty. * @type bool $show_post_count Whether to display the post count alongside the link. Default false. - * @type bool $echo Whether to echo or return the links list. Default 1|true to echo. + * @type bool|int $echo Whether to echo or return the links list. Default 1|true to echo. * @type string $order Whether to use ascending or descending order. Accepts 'ASC', or 'DESC'. * Default 'DESC'. * } - * @return string|null String when retrieving, null when displaying. + * @return string|void String when retrieving. */ function wp_get_archives( $args = '' ) { global $wpdb, $wp_locale; @@ -1438,7 +1504,6 @@ function wp_get_archives( $args = '' ) { $key = "wp_get_archives:$key:$last_changed"; if ( ! $results = wp_cache_get( $key, 'posts' ) ) { $results = $wpdb->get_results( $query ); - $cache[ $key ] = $results; wp_cache_set( $key, $results, 'posts' ); } if ( $results ) { @@ -1482,7 +1547,7 @@ function wp_get_archives( $args = '' ) { } } } elseif ( ( 'postbypost' == $r['type'] ) || ('alpha' == $r['type'] ) ) { - $orderby = ( 'alpha' == $r['type'] ) ? 'post_title ASC ' : 'post_date DESC '; + $orderby = ( 'alpha' == $r['type'] ) ? 'post_title ASC ' : 'post_date DESC, ID DESC '; $query = "SELECT * FROM $wpdb->posts $join $where ORDER BY $orderby $limit"; $key = md5( $query ); $key = "wp_get_archives:$key:$last_changed"; @@ -1533,9 +1598,16 @@ function calendar_week_mod($num) { * * @since 1.0.0 * + * @global wpdb $wpdb + * @global int $m + * @global int $monthnum + * @global int $year + * @global WP_Locale $wp_locale + * @global array $posts + * * @param bool $initial Optional, default is true. Use initial calendar names. - * @param bool $echo Optional, default is true. Set to false for return. - * @return string|null String when retrieving, null when displaying. + * @param bool $echo Optional, default is true. Set to false for return. + * @return string|void String when retrieving. */ function get_calendar($initial = true, $echo = true) { global $wpdb, $m, $monthnum, $year, $wp_locale, $posts; @@ -1624,7 +1696,7 @@ function get_calendar($initial = true, $echo = true) { } foreach ( $myweek as $wd ) { - $day_name = (true == $initial) ? $wp_locale->get_weekday_initial($wd) : $wp_locale->get_weekday_abbrev($wd); + $day_name = $initial ? $wp_locale->get_weekday_initial($wd) : $wp_locale->get_weekday_abbrev($wd); $wd = esc_attr($wd); $calendar_output .= "\n\t\t$day_name"; } @@ -1657,6 +1729,8 @@ function get_calendar($initial = true, $echo = true) { '; + $daywithpost = array(); + // Get days with posts $dayswithposts = $wpdb->get_results("SELECT DISTINCT DAYOFMONTH(post_date) FROM $wpdb->posts WHERE post_date >= '{$thisyear}-{$thismonth}-01 00:00:00' @@ -1666,8 +1740,6 @@ function get_calendar($initial = true, $echo = true) { foreach ( (array) $dayswithposts as $daywith ) { $daywithpost[] = $daywith[0]; } - } else { - $daywithpost = array(); } if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== false || stripos($_SERVER['HTTP_USER_AGENT'], 'camino') !== false || stripos($_SERVER['HTTP_USER_AGENT'], 'safari') !== false) @@ -1757,10 +1829,6 @@ function get_calendar($initial = true, $echo = true) { function delete_get_calendar_cache() { wp_cache_delete( 'get_calendar', 'calendar' ); } -add_action( 'save_post', 'delete_get_calendar_cache' ); -add_action( 'delete_post', 'delete_get_calendar_cache' ); -add_action( 'update_option_start_of_week', 'delete_get_calendar_cache' ); -add_action( 'update_option_gmt_offset', 'delete_get_calendar_cache' ); /** * Display all of the allowed tags in HTML format with attributes. @@ -1769,7 +1837,8 @@ add_action( 'update_option_gmt_offset', 'delete_get_calendar_cache' ); * attributes are supported. As well as any plugins which want to display it. * * @since 1.0.1 - * @uses $allowedtags + * + * @global array $allowedtags * * @return string HTML allowed tags entity encoded. */ @@ -1785,7 +1854,7 @@ function allowed_tags() { } $allowed .= '> '; } - return htmlentities($allowed); + return htmlentities( $allowed ); } /***** Date/Time tags *****/ @@ -1813,11 +1882,14 @@ function the_date_xml() { * * @since 0.71 * - * @param string $d Optional. PHP date format defaults to the date_format option if not specified. + * @global string|int|bool $currentday + * @global string|int|bool $previousday + * + * @param string $d Optional. PHP date format defaults to the date_format option if not specified. * @param string $before Optional. Output before the date. - * @param string $after Optional. Output after the date. - * @param bool $echo Optional, default is display. Whether to echo the date or return it. - * @return string|null Null if displaying, string if retrieving. + * @param string $after Optional. Output after the date. + * @param bool $echo Optional, default is display. Whether to echo the date or return it. + * @return string|void String if retrieving. */ function the_date( $d = '', $before = '', $after = '', $echo = true ) { global $currentday, $previousday; @@ -1844,8 +1916,6 @@ function the_date( $d = '', $before = '', $after = '', $echo = true ) { else return $the_date; } - - return null; } /** @@ -1891,14 +1961,13 @@ function get_the_date( $d = '', $post = null ) { * * @since 2.1.0 * - * @param string $d Optional. PHP date format defaults to the date_format option if not specified. + * @param string $d Optional. PHP date format defaults to the date_format option if not specified. * @param string $before Optional. Output before the date. - * @param string $after Optional. Output after the date. - * @param bool $echo Optional, default is display. Whether to echo the date or return it. - * @return string|null Null if displaying, string if retrieving. + * @param string $after Optional. Output after the date. + * @param bool $echo Optional, default is display. Whether to echo the date or return it. + * @return string|void String if retrieving. */ -function the_modified_date($d = '', $before='', $after='', $echo = true) { - +function the_modified_date( $d = '', $before = '', $after = '', $echo = true ) { $the_modified_date = $before . get_the_modified_date($d) . $after; /** @@ -2132,7 +2201,8 @@ function get_post_modified_time( $d = 'U', $gmt = false, $post = null, $translat * Display the weekday on which the post was written. * * @since 0.71 - * @uses $wp_locale + * + * @global WP_Locale $wp_locale */ function the_weekday() { global $wp_locale; @@ -2145,8 +2215,7 @@ function the_weekday() { * * @param string $the_weekday */ - $the_weekday = apply_filters( 'the_weekday', $the_weekday ); - echo $the_weekday; + echo apply_filters( 'the_weekday', $the_weekday ); } /** @@ -2157,6 +2226,10 @@ function the_weekday() { * * @since 0.71 * + * @global WP_Locale $wp_locale + * @global string|int|bool $currentday + * @global string|int|bool $previousweekday + * * @param string $before Optional Output before the date. * @param string $after Optional Output after the date. */ @@ -2363,6 +2436,40 @@ function wp_no_robots() { echo "\n"; } +/** + * Display site icon meta tags. + * + * @since 4.3.0 + * + * @link http://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() ) { + return; + } + + $meta_tags = array( + sprintf( '', esc_url( get_site_icon_url( 32 ) ) ), + sprintf( '', esc_url( get_site_icon_url( 192 ) ) ), + sprintf( '', esc_url( get_site_icon_url( 180 ) ) ), + sprintf( '', esc_url( get_site_icon_url( 270 ) ) ), + ); + + /** + * Filter the site icon meta tags, so Plugins can add their own. + * + * @since 4.3.0 + * + * @param array $meta_tags Site Icon meta elements. + */ + $meta_tags = apply_filters( 'site_icon_meta_tags', $meta_tags ); + $meta_tags = array_filter( $meta_tags ); + + foreach ( $meta_tags as $meta_tag ) { + echo "$meta_tag\n"; + } +} + /** * Whether the user should have a WYSIWIG editor. * @@ -2371,6 +2478,13 @@ function wp_no_robots() { * * @since 2.0.0 * + * @global bool $wp_rich_edit + * @global bool $is_gecko + * @global bool $is_opera + * @global bool $is_safari + * @global bool $is_chrome + * @global bool $is_IE + * * @return bool */ function user_can_richedit() { @@ -2440,9 +2554,9 @@ function wp_default_editor() { * @see wp-includes/class-wp-editor.php * @since 3.3.0 * - * @param string $content Initial content for the editor. + * @param string $content Initial content for the editor. * @param string $editor_id HTML ID attribute value for the textarea and TinyMCE. Can only be /[a-z]+/. - * @param array $settings See _WP_Editors::editor(). + * @param array $settings See _WP_Editors::editor(). */ function wp_editor( $content, $editor_id, $settings = array() ) { if ( ! class_exists( '_WP_Editors' ) ) @@ -2460,7 +2574,7 @@ function wp_editor( $content, $editor_id, $settings = array() ) { * @since 2.3.0 * * @param bool $escaped Whether the result is escaped. Default true. - * Only use when you are later escaping it. Do not use unescaped. + * Only use when you are later escaping it. Do not use unescaped. * @return string */ function get_search_query( $escaped = true ) { @@ -2498,16 +2612,16 @@ function the_search_query() { } /** - * Display the language attributes for the html tag. + * Gets the language attributes for the html tag. * * Builds up a set of html attributes containing the text direction and language * information for the page. * - * @since 2.1.0 + * @since 4.3.0 * - * @param string $doctype The type of html document (xhtml|html). + * @param string $doctype Optional. The type of html document. Accepts 'xhtml' or 'html'. Default 'html'. */ -function language_attributes($doctype = 'html') { +function get_language_attributes( $doctype = 'html' ) { $attributes = array(); if ( function_exists( 'is_rtl' ) && is_rtl() ) @@ -2527,10 +2641,27 @@ function language_attributes($doctype = 'html') { * Filter the language attributes for display in the html tag. * * @since 2.5.0 + * @since 4.3.0 Added the `$doctype` parameter. * * @param string $output A space-separated list of language attributes. + * @param string $doctype The type of html document (xhtml|html). */ - echo apply_filters( 'language_attributes', $output ); + return apply_filters( 'language_attributes', $output, $doctype ); +} + +/** + * Displays the language attributes for the html tag. + * + * Builds up a set of html attributes containing the text direction and language + * information for the page. + * + * @since 2.1.0 + * @since 4.3.0 Converted into a wrapper for get_language_attributes(). + * + * @param string $doctype Optional. The type of html document. Accepts 'xhtml' or 'html'. Default 'html'. + */ +function language_attributes( $doctype = 'html' ) { + echo get_language_attributes( $doctype ); } /** @@ -2581,26 +2712,48 @@ function language_attributes($doctype = 'html') { * * @since 2.1.0 * - * @param string|array $args Optional. Override defaults. - * @return array|string String of page links or array of page links. + * @global WP_Query $wp_query + * @global WP_Rewrite $wp_rewrite + * + * @param string|array $args { + * Optional. Array or string of arguments for generating paginated links for archives. + * + * @type string $base Base of the paginated url. Default empty. + * @type string $format Format for the pagination structure. Default empty. + * @type int $total The total amount of pages. Default is the value WP_Query's + * `max_num_pages` or 1. + * @type int $current The current page number. Default is 'paged' query var or 1. + * @type bool $show_all Whether to show all pages. Default false. + * @type int $end_size How many numbers on either the start and the end list edges. + * Default 1. + * @type int $mid_size How many numbers to either side of the current pages. Default 2. + * @type bool $prev_next Whether to include the previous and next links in the list. Default true. + * @type bool $prev_text The previous page text. Default '« Previous'. + * @type bool $next_text The next page text. Default '« Previous'. + * @type string $type Controls format of the returned value. Possible values are 'plain', + * 'array' and 'list'. Default is 'plain'. + * @type array $add_args An array of query args to add. Default false. + * @type string $add_fragment A string to append to each link. Default empty. + * @type string $before_page_number A string to appear before the page number. Default empty. + * @type string $after_page_number A string to append after the page number. Default empty. + * } + * @return array|string|void String of page links or array of page links. */ function paginate_links( $args = '' ) { global $wp_query, $wp_rewrite; - $total = ( isset( $wp_query->max_num_pages ) ) ? $wp_query->max_num_pages : 1; - $current = ( get_query_var( 'paged' ) ) ? intval( get_query_var( 'paged' ) ) : 1; + // Setting up default values based on the current URL. $pagenum_link = html_entity_decode( get_pagenum_link() ); - $query_args = array(); $url_parts = explode( '?', $pagenum_link ); - if ( isset( $url_parts[1] ) ) { - wp_parse_str( $url_parts[1], $query_args ); - $query_args = urlencode_deep( $query_args ); - } + // Get max pages and current page out of the current query, if available. + $total = isset( $wp_query->max_num_pages ) ? $wp_query->max_num_pages : 1; + $current = get_query_var( 'paged' ) ? intval( get_query_var( 'paged' ) ) : 1; - $pagenum_link = remove_query_arg( array_keys( $query_args ), $pagenum_link ); - $pagenum_link = trailingslashit( $pagenum_link ) . '%_%'; + // Append the format placeholder to the base URL. + $pagenum_link = trailingslashit( $url_parts[0] ) . '%_%'; + // URL base depends on permalink settings. $format = $wp_rewrite->using_index_permalinks() && ! strpos( $pagenum_link, 'index.php' ) ? 'index.php/' : ''; $format .= $wp_rewrite->using_permalinks() ? user_trailingslashit( $wp_rewrite->pagination_base . '/%#%', 'paged' ) : '?paged=%#%'; @@ -2616,7 +2769,7 @@ function paginate_links( $args = '' ) { 'end_size' => 1, 'mid_size' => 2, 'type' => 'plain', - 'add_args' => $query_args, // array of query args to add + 'add_args' => array(), // array of query args to add 'add_fragment' => '', 'before_page_number' => '', 'after_page_number' => '' @@ -2624,6 +2777,28 @@ function paginate_links( $args = '' ) { $args = wp_parse_args( $args, $defaults ); + if ( ! is_array( $args['add_args'] ) ) { + $args['add_args'] = array(); + } + + // Merge additional query vars found in the original URL into 'add_args' array. + if ( isset( $url_parts[1] ) ) { + // Find the format argument. + $format = explode( '?', str_replace( '%_%', $args['format'], $args['base'] ) ); + $format_query = isset( $format[1] ) ? $format[1] : ''; + wp_parse_str( $format_query, $format_args ); + + // Find the query args of the requested URL. + wp_parse_str( $url_parts[1], $url_query_args ); + + // Remove the format argument from the array of query arguments, to avoid overwriting custom format. + foreach ( $format_args as $format_arg => $format_arg_value ) { + unset( $url_query_args[ $format_arg ] ); + } + + $args['add_args'] = array_merge( $args['add_args'], urlencode_deep( $url_query_args ) ); + } + // Who knows what else people pass in $args $total = (int) $args['total']; if ( $total < 2 ) { @@ -2638,7 +2813,7 @@ function paginate_links( $args = '' ) { if ( $mid_size < 0 ) { $mid_size = 2; } - $add_args = is_array( $args['add_args'] ) ? $args['add_args'] : false; + $add_args = $args['add_args']; $r = ''; $page_links = array(); $dots = false; @@ -2720,11 +2895,13 @@ function paginate_links( $args = '' ) { * * @todo Properly document optional arguments as such * - * @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 + * @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 */ function wp_admin_css_color( $key, $name, $url, $colors = array(), $icons = array() ) { global $_wp_admin_css_colors; @@ -2744,15 +2921,17 @@ function wp_admin_css_color( $key, $name, $url, $colors = array(), $icons = arra * Registers the default Admin color schemes * * @since 3.0.0 + * + * @global string $wp_version */ function register_admin_color_schemes() { $suffix = is_rtl() ? '-rtl' : ''; - $suffix .= defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ? '' : '.min'; + $suffix .= SCRIPT_DEBUG ? '' : '.min'; wp_admin_css_color( 'fresh', _x( 'Default', 'admin color scheme' ), false, - array( '#222', '#333', '#0074a2', '#2ea2cc' ), - array( 'base' => '#999', 'focus' => '#2ea2cc', 'current' => '#fff' ) + array( '#222', '#333', '#0073aa', '#00a0d2' ), + array( 'base' => '#999', 'focus' => '#00a0d2', 'current' => '#fff' ) ); // Other color schemes are not available when running out of src @@ -2811,6 +2990,7 @@ function register_admin_color_schemes() { * @since 2.3.0 * * @param string $file file relative to wp-admin/ without its ".css" extension. + * @return string */ function wp_admin_css_uri( $file = 'wp-admin' ) { if ( defined('WP_INSTALLING') ) { @@ -2846,21 +3026,16 @@ function wp_admin_css_uri( $file = 'wp-admin' ) { * stylesheet link to that generated URL is printed. * * @since 2.3.0 - * @uses $wp_styles WordPress Styles Object * - * @param string $file Optional. Style handle name or file name (without ".css" extension) relative - * to wp-admin/. Defaults to 'wp-admin'. - * @param bool $force_echo Optional. Force the stylesheet link to be printed rather than enqueued. + * @param string $file Optional. Style handle name or file name (without ".css" extension) relative + * to wp-admin/. Defaults to 'wp-admin'. + * @param bool $force_echo Optional. Force the stylesheet link to be printed rather than enqueued. */ function wp_admin_css( $file = 'wp-admin', $force_echo = false ) { - global $wp_styles; - if ( !is_a($wp_styles, 'WP_Styles') ) - $wp_styles = new WP_Styles(); - // For backward compatibility $handle = 0 === strpos( $file, 'css/' ) ? substr( $file, 4 ) : $file; - if ( $wp_styles->query( $handle ) ) { + if ( wp_styles()->query( $handle ) ) { if ( $force_echo || did_action( 'wp_print_styles' ) ) // we already printed the style queue. Print this one immediately wp_print_styles( $handle ); else // Add to style queue @@ -2953,7 +3128,7 @@ function the_generator( $type ) { * @since 2.5.0 * * @param string $type The type of generator to return - (html|xhtml|atom|rss2|rdf|comment|export). - * @return string The HTML content for the generator. + * @return string|void The HTML content for the generator. */ function get_the_generator( $type = '' ) { if ( empty( $type ) ) { @@ -3029,7 +3204,7 @@ function get_the_generator( $type = '' ) { * * @param mixed $checked One of the values to compare * @param mixed $current (true) The other value to compare if not just true - * @param bool $echo Whether to echo or just return the string + * @param bool $echo Whether to echo or just return the string * @return string html attribute or empty string */ function checked( $checked, $current = true, $echo = true ) { @@ -3044,8 +3219,8 @@ function checked( $checked, $current = true, $echo = true ) { * @since 1.0.0 * * @param mixed $selected One of the values to compare - * @param mixed $current (true) The other value to compare if not just true - * @param bool $echo Whether to echo or just return the string + * @param mixed $current (true) The other value to compare if not just true + * @param bool $echo Whether to echo or just return the string * @return string html attribute or empty string */ function selected( $selected, $current = true, $echo = true ) { @@ -3060,8 +3235,8 @@ function selected( $selected, $current = true, $echo = true ) { * @since 3.0.0 * * @param mixed $disabled One of the values to compare - * @param mixed $current (true) The other value to compare if not just true - * @param bool $echo Whether to echo or just return the string + * @param mixed $current (true) The other value to compare if not just true + * @param bool $echo Whether to echo or just return the string * @return string html attribute or empty string */ function disabled( $disabled, $current = true, $echo = true ) { @@ -3076,10 +3251,10 @@ function disabled( $disabled, $current = true, $echo = true ) { * @since 2.8.0 * @access private * - * @param mixed $helper One of the values to compare - * @param mixed $current (true) The other value to compare if not just true - * @param bool $echo Whether to echo or just return the string - * @param string $type The type of checked|selected|disabled we are doing + * @param mixed $helper One of the values to compare + * @param mixed $current (true) The other value to compare if not just true + * @param bool $echo Whether to echo or just return the string + * @param string $type The type of checked|selected|disabled we are doing * @return string html attribute or empty string */ function __checked_selected_helper( $helper, $current, $echo, $type ) {