Multisite: add new sites_pre_query and networks_pre_query filters to short circuit WP_Site_Query and WP_Network_Query queries.

Similar to the `posts_pre_query` filter for WP_Query added in #36687. These filters lets you short circuit the queries to return your own results.

Add a new filter `sites_pre_query` - which returns null by default. Return a non-null value to bypass WordPress's default `get_sites` queries.

Developers should note that filtering functions that require pagination information are encouraged to set the `found_sites` property of the `WP_Site_Query` object, passed to the filter by reference. If `WP_Site_Query` does not perform a database query, it will not have enough information to generate these values itself.

Add a new filter `networks_pre_query` - which returns null by default. Return a non-null value to bypass WordPress's default `get_networks` queries.

Developers should note that filtering functions that require pagination information are encouraged to set the `found_networks` property of the `WP_Network_Query` object, passed to the filter by reference. If `WP_Network_Query` does not perform a database query, it will not have enough information to generate these values itself.

Props spacedmonkey.
Fixes #45749.


Built from https://develop.svn.wordpress.org/trunk@44983


git-svn-id: http://core.svn.wordpress.org/trunk@44814 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/class-wp-network-query.php

@@ -197,6 +197,24 @@ class WP_Network_Query {
 		 */
 		do_action_ref_array( 'pre_get_networks', array( &$this ) );
 
+		$network_ids = null;
+
+		/**
+		 * Filter the sites array before the query takes place.
+		 *
+		 * Return a non-null value to bypass WordPress's default site queries.
+		 *
+		 *
+		 * @since 5.2.0
+		 *
+		 * @param array|null       $site_ids Return an array of site data to short-circuit WP's site query,
+		 *                                   or null to allow WP to run its normal queries.
+		 * @param WP_Network_Query $this     The WP_Network_Query instance, passed by reference.
+		 */
+		$network_ids = apply_filters_ref_array( 'networks_pre_query', array( $network_ids, &$this ) );
+
+		if ( null === $network_ids ) {
+
 			// $args can include anything. Only use the args defined in the query_var_defaults to compute the key.
 			$_args = wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) );
 
@@ -224,6 +242,7 @@ class WP_Network_Query {
 				$network_ids          = $cache_value['network_ids'];
 				$this->found_networks = $cache_value['found_networks'];
 			}
+		}
 
 		if ( $this->found_networks && $this->query_vars['number'] ) {
 			$this->max_num_pages = ceil( $this->found_networks / $this->query_vars['number'] );

wp-includes/class-wp-site-query.php

@@ -288,6 +288,24 @@ class WP_Site_Query {
 			$this->meta_query_clauses = $this->meta_query->get_sql( 'blog', $wpdb->blogs, 'blog_id', $this );
 		}
 
+		$site_ids = null;
+
+		/**
+		 * Filter the sites array before the query takes place.
+		 *
+		 * Return a non-null value to bypass WordPress's default site queries.
+		 *
+		 *
+		 * @since 5.2.0
+		 *
+		 * @param array|null    $site_ids Return an array of site data to short-circuit WP's site query,
+		 *                                or null to allow WP to run its normal queries.
+		 * @param WP_Site_Query $this The WP_Site_Query instance, passed by reference.
+		 */
+		$site_ids = apply_filters_ref_array( 'sites_pre_query', array( $site_ids, &$this ) );
+
+		if ( null === $site_ids ) {
+
 			// $args can include anything. Only use the args defined in the query_var_defaults to compute the key.
 			$_args = wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) );
 
@@ -315,6 +333,7 @@ class WP_Site_Query {
 				$site_ids          = $cache_value['site_ids'];
 				$this->found_sites = $cache_value['found_sites'];
 			}
+		}
 
 		if ( $this->found_sites && $this->query_vars['number'] ) {
 			$this->max_num_pages = ceil( $this->found_sites / $this->query_vars['number'] );

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.2-alpha-44982';
+$wp_version = '5.2-alpha-44983';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.