diff -r 34716fd837a4 -r be944660c56a wp/wp-includes/class-wp-site-query.php --- a/wp/wp-includes/class-wp-site-query.php Tue Dec 15 15:52:01 2020 +0100 +++ b/wp/wp-includes/class-wp-site-query.php Wed Sep 21 18:19:35 2022 +0200 @@ -114,8 +114,8 @@ * @param string|array $query { * Optional. Array or query string of site query parameters. Default empty. * - * @type array $site__in Array of site IDs to include. Default empty. - * @type array $site__not_in Array of site IDs to exclude. Default empty. + * @type int[] $site__in Array of site IDs to include. Default empty. + * @type int[] $site__not_in Array of site IDs to exclude. Default empty. * @type bool $count Whether to return a site count (true) or array of site objects. * Default false. * @type array $date_query Date query clauses to limit sites by. See WP_Date_Query. @@ -135,24 +135,24 @@ * @type string $order How to order retrieved sites. Accepts 'ASC', 'DESC'. Default 'ASC'. * @type int $network_id Limit results to those affiliated with a given network ID. If 0, * include all networks. Default 0. - * @type array $network__in Array of network IDs to include affiliated sites for. Default empty. - * @type array $network__not_in Array of network IDs to exclude affiliated sites for. Default empty. + * @type int[] $network__in Array of network IDs to include affiliated sites for. Default empty. + * @type int[] $network__not_in Array of network IDs to exclude affiliated sites for. Default empty. * @type string $domain Limit results to those affiliated with a given domain. Default empty. - * @type array $domain__in Array of domains to include affiliated sites for. Default empty. - * @type array $domain__not_in Array of domains to exclude affiliated sites for. Default empty. + * @type string[] $domain__in Array of domains to include affiliated sites for. Default empty. + * @type string[] $domain__not_in Array of domains to exclude affiliated sites for. Default empty. * @type string $path Limit results to those affiliated with a given path. Default empty. - * @type array $path__in Array of paths to include affiliated sites for. Default empty. - * @type array $path__not_in Array of paths to exclude affiliated sites for. Default empty. + * @type string[] $path__in Array of paths to include affiliated sites for. Default empty. + * @type string[] $path__not_in Array of paths to exclude affiliated sites for. Default empty. * @type int $public Limit results to public sites. Accepts '1' or '0'. Default empty. * @type int $archived Limit results to archived sites. Accepts '1' or '0'. Default empty. * @type int $mature Limit results to mature sites. Accepts '1' or '0'. Default empty. * @type int $spam Limit results to spam sites. Accepts '1' or '0'. Default empty. * @type int $deleted Limit results to deleted sites. Accepts '1' or '0'. Default empty. * @type int $lang_id Limit results to a language ID. Default empty. - * @type array $lang__in Array of language IDs to include affiliated sites for. Default empty. - * @type array $lang__not_in Array of language IDs to exclude affiliated sites for. Default empty. + * @type string[] $lang__in Array of language IDs to include affiliated sites for. Default empty. + * @type string[] $lang__not_in Array of language IDs to exclude affiliated sites for. Default empty. * @type string $search Search term(s) to retrieve matching sites for. Default empty. - * @type array $search_columns Array of column names to be searched. Accepts 'domain' and 'path'. + * @type string[] $search_columns Array of column names to be searched. Accepts 'domain' and 'path'. * Default empty array. * @type bool $update_site_cache Whether to prime the cache for found sites. Default true. * @type bool $update_site_meta_cache Whether to prime the metadata cache for found sites. Default true. @@ -291,25 +291,42 @@ $site_data = null; /** - * Filter the site data before the get_sites query takes place. + * Filters the site data before the get_sites query takes place. * - * Return a non-null value to bypass WordPress's default site queries. + * Return a non-null value to bypass WordPress' default site queries. * - * The expected return type from this filter depends on the value passed in the request query_vars: - * When `$this->query_vars['count']` is set, the filter should return the site count as an int. - * When `'ids' === $this->query_vars['fields']`, the filter should return an array of site IDs. - * Otherwise the filter should return an array of WP_Site objects. + * The expected return type from this filter depends on the value passed + * in the request query vars: + * - When `$this->query_vars['count']` is set, the filter should return + * the site count as an integer. + * - When `'ids' === $this->query_vars['fields']`, the filter should return + * an array of site IDs. + * - Otherwise the filter should return an array of WP_Site objects. + * + * Note that if the filter returns an array of site data, it will be assigned + * to the `sites` property of the current WP_Site_Query instance. + * + * Filtering functions that require pagination information are encouraged to set + * the `found_sites` and `max_num_pages` properties 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. * * @since 5.2.0 + * @since 5.6.0 The returned array of site data is assigned to the `sites` property + * of the current WP_Site_Query instance. * * @param array|int|null $site_data Return an array of site data to short-circuit WP's site query, * the site count as an integer if `$this->query_vars['count']` is set, * or null to run the normal queries. - * @param WP_Site_Query $this The WP_Site_Query instance, passed by reference. + * @param WP_Site_Query $query The WP_Site_Query instance, passed by reference. */ $site_data = apply_filters_ref_array( 'sites_pre_query', array( $site_data, &$this ) ); if ( null !== $site_data ) { + if ( is_array( $site_data ) && ! $this->query_vars['count'] ) { + $this->sites = $site_data; + } + return $site_data; } @@ -348,7 +365,7 @@ // If querying for a count only, there's nothing more to do. if ( $this->query_vars['count'] ) { // $site_ids is actually a count in this case. - return intval( $site_ids ); + return (int) $site_ids; } $site_ids = array_map( 'intval', $site_ids ); @@ -379,7 +396,7 @@ * @since 4.6.0 * * @param WP_Site[] $_sites An array of WP_Site objects. - * @param WP_Site_Query $this Current instance of WP_Site_Query (passed by reference). + * @param WP_Site_Query $query Current instance of WP_Site_Query (passed by reference). */ $_sites = apply_filters_ref_array( 'the_sites', array( $_sites, &$this ) ); @@ -583,7 +600,7 @@ * * @param string[] $search_columns Array of column names to be searched. * @param string $search Text being searched. - * @param WP_Site_Query $this The current WP_Site_Query instance. + * @param WP_Site_Query $query The current WP_Site_Query instance. */ $search_columns = apply_filters( 'site_search_columns', $search_columns, $this->query_vars['search'], $this ); @@ -620,7 +637,7 @@ * @since 4.6.0 * * @param string[] $pieces An associative array of site query clauses. - * @param WP_Site_Query $this Current instance of WP_Site_Query (passed by reference). + * @param WP_Site_Query $query Current instance of WP_Site_Query (passed by reference). */ $clauses = apply_filters_ref_array( 'sites_clauses', array( compact( $pieces ), &$this ) ); @@ -657,7 +674,7 @@ $this->request = "{$this->sql_clauses['select']} {$this->sql_clauses['from']} {$where} {$this->sql_clauses['groupby']} {$this->sql_clauses['orderby']} {$this->sql_clauses['limits']}"; if ( $this->query_vars['count'] ) { - return intval( $wpdb->get_var( $this->request ) ); + return (int) $wpdb->get_var( $this->request ); } $site_ids = $wpdb->get_col( $this->request );