--- a/wp/wp-includes/query.php Tue Oct 22 16:11:46 2019 +0200
+++ b/wp/wp-includes/query.php Tue Dec 15 13:49:49 2020 +0100
@@ -5,7 +5,7 @@
* The query API attempts to get which part of WordPress the user is on. It
* also provides functionality for getting URL query information.
*
- * @link https://codex.wordpress.org/The_Loop More information on The Loop.
+ * @link https://developer.wordpress.org/themes/basics/the-loop/ More information on The Loop.
*
* @package WordPress
* @subpackage Query
@@ -17,7 +17,7 @@
* @since 1.5.0
* @since 3.9.0 The `$default` argument was introduced.
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @param string $var The variable key to retrieve.
* @param mixed $default Optional. Value to return if the query variable is not set. Default empty.
@@ -35,7 +35,7 @@
*
* @since 3.1.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @return object Queried object.
*/
@@ -51,7 +51,7 @@
*
* @since 3.1.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @return int ID of the queried object.
*/
@@ -65,7 +65,7 @@
*
* @since 2.2.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @param string $var Query variable key.
* @param mixed $value Query variable value.
@@ -88,10 +88,10 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @param array|string $query Array or string of WP_Query arguments.
- * @return array List of post objects.
+ * @return WP_Post[]|int[] Array of post objects or post IDs.
*/
function query_posts( $query ) {
$GLOBALS['wp_query'] = new WP_Query();
@@ -107,7 +107,7 @@
*
* @since 2.3.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
* @global WP_Query $wp_the_query Copy of the global WP_Query instance created during wp_reset_query().
*/
function wp_reset_query() {
@@ -121,7 +121,7 @@
*
* @since 3.0.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*/
function wp_reset_postdata() {
global $wp_query;
@@ -146,9 +146,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for an existing archive page.
*/
function is_archive() {
global $wp_query;
@@ -170,10 +170,11 @@
*
* @since 3.1.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param string|array $post_types Optional. Post type or array of posts types to check against.
- * @return bool
+ * @param string|string[] $post_types Optional. Post type or array of posts types
+ * to check against. Default empty.
+ * @return bool Whether the query is for an existing post type archive page.
*/
function is_post_type_archive( $post_types = '' ) {
global $wp_query;
@@ -195,10 +196,11 @@
*
* @since 2.0.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param int|string|array|object $attachment Attachment ID, title, slug, or array of such.
- * @return bool
+ * @param int|string|int[]|string[] $attachment Optional. Attachment ID, title, slug, or array of such
+ * to check against. Default empty.
+ * @return bool Whether the query is for an existing attachment page.
*/
function is_attachment( $attachment = '' ) {
global $wp_query;
@@ -223,10 +225,11 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param mixed $author Optional. User ID, nickname, nicename, or array of User IDs, nicknames, and nicenames
- * @return bool
+ * @param int|string|int[]|string[] $author Optional. User ID, nickname, nicename, or array of such
+ * to check against. Default empty.
+ * @return bool Whether the query is for an existing author archive page.
*/
function is_author( $author = '' ) {
global $wp_query;
@@ -251,10 +254,11 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param mixed $category Optional. Category ID, name, slug, or array of Category IDs, names, and slugs.
- * @return bool
+ * @param int|string|int[]|string[] $category Optional. Category ID, name, slug, or array of such
+ * to check against. Default empty.
+ * @return bool Whether the query is for an existing category archive page.
*/
function is_category( $category = '' ) {
global $wp_query;
@@ -279,10 +283,11 @@
*
* @since 2.3.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param mixed $tag Optional. Tag ID, name, slug, or array of Tag IDs, names, and slugs.
- * @return bool
+ * @param int|string|int[]|string[] $tag Optional. Tag ID, name, slug, or array of such
+ * to check against. Default empty.
+ * @return bool Whether the query is for an existing tag archive page.
*/
function is_tag( $tag = '' ) {
global $wp_query;
@@ -311,11 +316,15 @@
*
* @since 2.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param string|array $taxonomy Optional. Taxonomy slug or slugs.
- * @param int|string|array $term Optional. Term ID, name, slug or array of Term IDs, names, and slugs.
- * @return bool True for custom taxonomy archive pages, false for built-in taxonomies (category and tag archives).
+ * @param string|string[] $taxonomy Optional. Taxonomy slug or slugs to check against.
+ * Default empty.
+ * @param int|string|int[]|string[] $term Optional. Term ID, name, slug, or array of such
+ * to check against. Default empty.
+ * @return bool Whether the query is for an existing custom taxonomy archive page.
+ * True for custom taxonomy archive pages, false for built-in taxonomies
+ * (category and tag archives).
*/
function is_tax( $taxonomy = '', $term = '' ) {
global $wp_query;
@@ -337,9 +346,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for an existing date archive.
*/
function is_date() {
global $wp_query;
@@ -363,9 +372,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for an existing day archive.
*/
function is_day() {
global $wp_query;
@@ -387,10 +396,11 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param string|array $feeds Optional feed types to check.
- * @return bool
+ * @param string|string[] $feeds Optional. Feed type or array of feed types
+ * to check against. Default empty.
+ * @return bool Whether the query is for a feed.
*/
function is_feed( $feeds = '' ) {
global $wp_query;
@@ -408,9 +418,9 @@
*
* @since 3.0.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for a comments feed.
*/
function is_comment_feed() {
global $wp_query;
@@ -441,9 +451,9 @@
*
* @since 2.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool True, if front of site.
+ * @return bool Whether the query is for the front page of the site.
*/
function is_front_page() {
global $wp_query;
@@ -474,9 +484,9 @@
* @since 1.5.0
*
* @see is_front_page()
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool True if blog view homepage, otherwise false.
+ * @return bool Whether the query is for the blog homepage.
*/
function is_home() {
global $wp_query;
@@ -504,9 +514,9 @@
*
* @since 5.2.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for the Privacy Policy page.
*/
function is_privacy_policy() {
global $wp_query;
@@ -528,9 +538,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for an existing month archive.
*/
function is_month() {
global $wp_query;
@@ -558,9 +568,10 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param int|string|array $page Optional. Page ID, title, slug, or array of such. Default empty.
+ * @param int|string|int[]|string[] $page Optional. Page ID, title, slug, or array of such
+ * to check against. Default empty.
* @return bool Whether the query is for an existing single page.
*/
function is_page( $page = '' ) {
@@ -575,7 +586,7 @@
}
/**
- * Determines whether the query is for paged results and not for the first page.
+ * Determines whether the query is for a paged result and not for the first page.
*
* For more information on this and similar theme functions, check out
* the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
@@ -583,9 +594,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for a paged result.
*/
function is_paged() {
global $wp_query;
@@ -607,9 +618,9 @@
*
* @since 2.0.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for a post or page preview.
*/
function is_preview() {
global $wp_query;
@@ -623,13 +634,13 @@
}
/**
- * Is the query for the robots file?
+ * Is the query for the robots.txt file?
*
* @since 2.1.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for the robots.txt file.
*/
function is_robots() {
global $wp_query;
@@ -643,6 +654,26 @@
}
/**
+ * Is the query for the favicon.ico file?
+ *
+ * @since 5.4.0
+ *
+ * @global WP_Query $wp_query WordPress Query object.
+ *
+ * @return bool Whether the query is for the favicon.ico file.
+ */
+function is_favicon() {
+ global $wp_query;
+
+ if ( ! isset( $wp_query ) ) {
+ _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
+ return false;
+ }
+
+ return $wp_query->is_favicon();
+}
+
+/**
* Determines whether the query is for a search.
*
* For more information on this and similar theme functions, check out
@@ -651,9 +682,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for a search.
*/
function is_search() {
global $wp_query;
@@ -683,9 +714,10 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param int|string|array $post Optional. Post ID, title, slug, or array of such. Default empty.
+ * @param int|string|int[]|string[] $post Optional. Post ID, title, slug, or array of such
+ * to check against. Default empty.
* @return bool Whether the query is for an existing single post.
*/
function is_single( $post = '' ) {
@@ -715,10 +747,12 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @param string|array $post_types Optional. Post type or array of post types. Default empty.
- * @return bool Whether the query is for an existing single post of any of the given post types.
+ * @param string|string[] $post_types Optional. Post type or array of post types
+ * to check against. Default empty.
+ * @return bool Whether the query is for an existing single post
+ * or any of the given post types.
*/
function is_singular( $post_types = '' ) {
global $wp_query;
@@ -740,9 +774,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for a specific time.
*/
function is_time() {
global $wp_query;
@@ -764,9 +798,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for a trackback endpoint call.
*/
function is_trackback() {
global $wp_query;
@@ -788,9 +822,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is for an existing year archive.
*/
function is_year() {
global $wp_query;
@@ -812,9 +846,9 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is a 404 error.
*/
function is_404() {
global $wp_query;
@@ -832,9 +866,9 @@
*
* @since 4.4.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool Whether we're in an embedded post or not.
+ * @return bool Whether the query is for an embedded post.
*/
function is_embed() {
global $wp_query;
@@ -856,14 +890,14 @@
*
* @since 3.3.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool Whether the query is the main query.
*/
function is_main_query() {
if ( 'pre_get_posts' === current_filter() ) {
$message = sprintf(
- /* translators: 1: pre_get_posts 2: WP_Query->is_main_query() 3: is_main_query() 4: link to codex is_main_query() page. */
+ /* translators: 1: pre_get_posts, 2: WP_Query->is_main_query(), 3: is_main_query(), 4: Link to codex is_main_query() page. */
__( 'In %1$s, use the %2$s method, not the %3$s function. See %4$s.' ),
'<code>pre_get_posts</code>',
'<code>WP_Query->is_main_query()</code>',
@@ -882,13 +916,13 @@
*/
/**
- * Whether current WordPress query has results to loop over.
+ * Determines whether current WordPress query has posts to loop over.
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool True if posts are available, false if end of the loop.
*/
function have_posts() {
global $wp_query;
@@ -904,7 +938,7 @@
*
* @since 2.0.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @return bool True if caller is within loop, false if loop hasn't started or ended.
*/
@@ -918,7 +952,7 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*/
function rewind_posts() {
global $wp_query;
@@ -930,7 +964,7 @@
*
* @since 1.5.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*/
function the_post() {
global $wp_query;
@@ -942,13 +976,13 @@
*/
/**
- * Whether there are comments to loop over.
+ * Determines whether current WordPress query has comments to loop over.
*
* @since 2.2.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
- * @return bool
+ * @return bool True if comments are available, false if no more comments.
*/
function have_comments() {
global $wp_query;
@@ -960,7 +994,7 @@
*
* @since 2.2.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @return object
*/
@@ -978,7 +1012,7 @@
*/
function wp_old_slug_redirect() {
if ( is_404() && '' !== get_query_var( 'name' ) ) {
- // Guess the current post_type based on the query vars.
+ // Guess the current post type based on the query vars.
if ( get_query_var( 'post_type' ) ) {
$post_type = get_query_var( 'post_type' );
} elseif ( get_query_var( 'attachment' ) ) {
@@ -996,7 +1030,7 @@
$post_type = reset( $post_type );
}
- // Do not attempt redirect for hierarchical post types
+ // Do not attempt redirect for hierarchical post types.
if ( is_post_type_hierarchical( $post_type ) ) {
return;
}
@@ -1041,7 +1075,7 @@
return;
}
- wp_redirect( $link, 301 ); // Permanent redirect
+ wp_redirect( $link, 301 ); // Permanent redirect.
exit;
}
}
@@ -1057,15 +1091,15 @@
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $post_type The current post type based on the query vars.
- * @return int $id The Post ID.
+ * @return int The Post ID.
*/
function _find_post_by_old_slug( $post_type ) {
global $wpdb;
$query = $wpdb->prepare( "SELECT post_id FROM $wpdb->postmeta, $wpdb->posts WHERE ID = post_id AND post_type = %s AND meta_key = '_wp_old_slug' AND meta_value = %s", $post_type, get_query_var( 'name' ) );
- // if year, monthnum, or day have been specified, make our query more precise
- // just in case there are multiple identical _wp_old_slug values
+ // If year, monthnum, or day have been specified, make our query more precise
+ // just in case there are multiple identical _wp_old_slug values.
if ( get_query_var( 'year' ) ) {
$query .= $wpdb->prepare( ' AND YEAR(post_date) = %d', get_query_var( 'year' ) );
}
@@ -1092,7 +1126,7 @@
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $post_type The current post type based on the query vars.
- * @return int $id The Post ID.
+ * @return int The Post ID.
*/
function _find_post_by_old_date( $post_type ) {
global $wpdb;
@@ -1113,7 +1147,7 @@
$id = (int) $wpdb->get_var( $wpdb->prepare( "SELECT post_id FROM $wpdb->postmeta AS pm_date, $wpdb->posts WHERE ID = post_id AND post_type = %s AND meta_key = '_wp_old_date' AND post_name = %s" . $date_query, $post_type, get_query_var( 'name' ) ) );
if ( ! $id ) {
- // Check to see if an old slug matches the old date
+ // Check to see if an old slug matches the old date.
$id = (int) $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->posts, $wpdb->postmeta AS pm_slug, $wpdb->postmeta AS pm_date WHERE ID = pm_slug.post_id AND ID = pm_date.post_id AND post_type = %s AND pm_slug.meta_key = '_wp_old_slug' AND pm_slug.meta_value = %s AND pm_date.meta_key = '_wp_old_date'" . $date_query, $post_type, get_query_var( 'name' ) ) );
}
}
@@ -1127,7 +1161,7 @@
* @since 1.5.0
* @since 4.4.0 Added the ability to pass a post ID to `$post`.
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @param WP_Post|object|int $post WP_Post instance or Post ID/object.
* @return bool True when finished.
@@ -1147,7 +1181,7 @@
*
* @since 5.2.0
*
- * @global WP_Query $wp_query Global WP_Query instance.
+ * @global WP_Query $wp_query WordPress Query object.
*
* @param WP_Post|object|int $post WP_Post instance or Post ID/object.
* @return array|bool Elements of post, or false on failure.