112 * 'meta_value', 'meta_type' and 'meta_compare' parameters. |
112 * 'meta_value', 'meta_type' and 'meta_compare' parameters. |
113 * |
113 * |
114 * @param string|array $query { |
114 * @param string|array $query { |
115 * Optional. Array or query string of site query parameters. Default empty. |
115 * Optional. Array or query string of site query parameters. Default empty. |
116 * |
116 * |
117 * @type array $site__in Array of site IDs to include. Default empty. |
117 * @type int[] $site__in Array of site IDs to include. Default empty. |
118 * @type array $site__not_in Array of site IDs to exclude. Default empty. |
118 * @type int[] $site__not_in Array of site IDs to exclude. Default empty. |
119 * @type bool $count Whether to return a site count (true) or array of site objects. |
119 * @type bool $count Whether to return a site count (true) or array of site objects. |
120 * Default false. |
120 * Default false. |
121 * @type array $date_query Date query clauses to limit sites by. See WP_Date_Query. |
121 * @type array $date_query Date query clauses to limit sites by. See WP_Date_Query. |
122 * Default null. |
122 * Default null. |
123 * @type string $fields Site fields to return. Accepts 'ids' (returns an array of site IDs) |
123 * @type string $fields Site fields to return. Accepts 'ids' (returns an array of site IDs) |
133 * an empty array, or 'none' to disable `ORDER BY` clause. |
133 * an empty array, or 'none' to disable `ORDER BY` clause. |
134 * Default 'id'. |
134 * Default 'id'. |
135 * @type string $order How to order retrieved sites. Accepts 'ASC', 'DESC'. Default 'ASC'. |
135 * @type string $order How to order retrieved sites. Accepts 'ASC', 'DESC'. Default 'ASC'. |
136 * @type int $network_id Limit results to those affiliated with a given network ID. If 0, |
136 * @type int $network_id Limit results to those affiliated with a given network ID. If 0, |
137 * include all networks. Default 0. |
137 * include all networks. Default 0. |
138 * @type array $network__in Array of network IDs to include affiliated sites for. Default empty. |
138 * @type int[] $network__in Array of network IDs to include affiliated sites for. Default empty. |
139 * @type array $network__not_in Array of network IDs to exclude affiliated sites for. Default empty. |
139 * @type int[] $network__not_in Array of network IDs to exclude affiliated sites for. Default empty. |
140 * @type string $domain Limit results to those affiliated with a given domain. Default empty. |
140 * @type string $domain Limit results to those affiliated with a given domain. Default empty. |
141 * @type array $domain__in Array of domains to include affiliated sites for. Default empty. |
141 * @type string[] $domain__in Array of domains to include affiliated sites for. Default empty. |
142 * @type array $domain__not_in Array of domains to exclude affiliated sites for. Default empty. |
142 * @type string[] $domain__not_in Array of domains to exclude affiliated sites for. Default empty. |
143 * @type string $path Limit results to those affiliated with a given path. Default empty. |
143 * @type string $path Limit results to those affiliated with a given path. Default empty. |
144 * @type array $path__in Array of paths to include affiliated sites for. Default empty. |
144 * @type string[] $path__in Array of paths to include affiliated sites for. Default empty. |
145 * @type array $path__not_in Array of paths to exclude affiliated sites for. Default empty. |
145 * @type string[] $path__not_in Array of paths to exclude affiliated sites for. Default empty. |
146 * @type int $public Limit results to public sites. Accepts '1' or '0'. Default empty. |
146 * @type int $public Limit results to public sites. Accepts '1' or '0'. Default empty. |
147 * @type int $archived Limit results to archived sites. Accepts '1' or '0'. Default empty. |
147 * @type int $archived Limit results to archived sites. Accepts '1' or '0'. Default empty. |
148 * @type int $mature Limit results to mature sites. Accepts '1' or '0'. Default empty. |
148 * @type int $mature Limit results to mature sites. Accepts '1' or '0'. Default empty. |
149 * @type int $spam Limit results to spam sites. Accepts '1' or '0'. Default empty. |
149 * @type int $spam Limit results to spam sites. Accepts '1' or '0'. Default empty. |
150 * @type int $deleted Limit results to deleted sites. Accepts '1' or '0'. Default empty. |
150 * @type int $deleted Limit results to deleted sites. Accepts '1' or '0'. Default empty. |
151 * @type int $lang_id Limit results to a language ID. Default empty. |
151 * @type int $lang_id Limit results to a language ID. Default empty. |
152 * @type array $lang__in Array of language IDs to include affiliated sites for. Default empty. |
152 * @type string[] $lang__in Array of language IDs to include affiliated sites for. Default empty. |
153 * @type array $lang__not_in Array of language IDs to exclude affiliated sites for. Default empty. |
153 * @type string[] $lang__not_in Array of language IDs to exclude affiliated sites for. Default empty. |
154 * @type string $search Search term(s) to retrieve matching sites for. Default empty. |
154 * @type string $search Search term(s) to retrieve matching sites for. Default empty. |
155 * @type array $search_columns Array of column names to be searched. Accepts 'domain' and 'path'. |
155 * @type string[] $search_columns Array of column names to be searched. Accepts 'domain' and 'path'. |
156 * Default empty array. |
156 * Default empty array. |
157 * @type bool $update_site_cache Whether to prime the cache for found sites. Default true. |
157 * @type bool $update_site_cache Whether to prime the cache for found sites. Default true. |
158 * @type bool $update_site_meta_cache Whether to prime the metadata cache for found sites. Default true. |
158 * @type bool $update_site_meta_cache Whether to prime the metadata cache for found sites. Default true. |
159 * @type array $meta_query Meta query clauses to limit retrieved sites by. See `WP_Meta_Query`. |
159 * @type array $meta_query Meta query clauses to limit retrieved sites by. See `WP_Meta_Query`. |
160 * Default empty. |
160 * Default empty. |
289 } |
289 } |
290 |
290 |
291 $site_data = null; |
291 $site_data = null; |
292 |
292 |
293 /** |
293 /** |
294 * Filter the site data before the get_sites query takes place. |
294 * Filters the site data before the get_sites query takes place. |
295 * |
295 * |
296 * Return a non-null value to bypass WordPress's default site queries. |
296 * Return a non-null value to bypass WordPress' default site queries. |
297 * |
297 * |
298 * The expected return type from this filter depends on the value passed in the request query_vars: |
298 * The expected return type from this filter depends on the value passed |
299 * When `$this->query_vars['count']` is set, the filter should return the site count as an int. |
299 * in the request query vars: |
300 * When `'ids' === $this->query_vars['fields']`, the filter should return an array of site IDs. |
300 * - When `$this->query_vars['count']` is set, the filter should return |
301 * Otherwise the filter should return an array of WP_Site objects. |
301 * the site count as an integer. |
|
302 * - When `'ids' === $this->query_vars['fields']`, the filter should return |
|
303 * an array of site IDs. |
|
304 * - Otherwise the filter should return an array of WP_Site objects. |
|
305 * |
|
306 * Note that if the filter returns an array of site data, it will be assigned |
|
307 * to the `sites` property of the current WP_Site_Query instance. |
|
308 * |
|
309 * Filtering functions that require pagination information are encouraged to set |
|
310 * the `found_sites` and `max_num_pages` properties of the WP_Site_Query object, |
|
311 * passed to the filter by reference. If WP_Site_Query does not perform a database |
|
312 * query, it will not have enough information to generate these values itself. |
302 * |
313 * |
303 * @since 5.2.0 |
314 * @since 5.2.0 |
|
315 * @since 5.6.0 The returned array of site data is assigned to the `sites` property |
|
316 * of the current WP_Site_Query instance. |
304 * |
317 * |
305 * @param array|int|null $site_data Return an array of site data to short-circuit WP's site query, |
318 * @param array|int|null $site_data Return an array of site data to short-circuit WP's site query, |
306 * the site count as an integer if `$this->query_vars['count']` is set, |
319 * the site count as an integer if `$this->query_vars['count']` is set, |
307 * or null to run the normal queries. |
320 * or null to run the normal queries. |
308 * @param WP_Site_Query $this The WP_Site_Query instance, passed by reference. |
321 * @param WP_Site_Query $query The WP_Site_Query instance, passed by reference. |
309 */ |
322 */ |
310 $site_data = apply_filters_ref_array( 'sites_pre_query', array( $site_data, &$this ) ); |
323 $site_data = apply_filters_ref_array( 'sites_pre_query', array( $site_data, &$this ) ); |
311 |
324 |
312 if ( null !== $site_data ) { |
325 if ( null !== $site_data ) { |
|
326 if ( is_array( $site_data ) && ! $this->query_vars['count'] ) { |
|
327 $this->sites = $site_data; |
|
328 } |
|
329 |
313 return $site_data; |
330 return $site_data; |
314 } |
331 } |
315 |
332 |
316 // $args can include anything. Only use the args defined in the query_var_defaults to compute the key. |
333 // $args can include anything. Only use the args defined in the query_var_defaults to compute the key. |
317 $_args = wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) ); |
334 $_args = wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) ); |
346 } |
363 } |
347 |
364 |
348 // If querying for a count only, there's nothing more to do. |
365 // If querying for a count only, there's nothing more to do. |
349 if ( $this->query_vars['count'] ) { |
366 if ( $this->query_vars['count'] ) { |
350 // $site_ids is actually a count in this case. |
367 // $site_ids is actually a count in this case. |
351 return intval( $site_ids ); |
368 return (int) $site_ids; |
352 } |
369 } |
353 |
370 |
354 $site_ids = array_map( 'intval', $site_ids ); |
371 $site_ids = array_map( 'intval', $site_ids ); |
355 |
372 |
356 if ( 'ids' === $this->query_vars['fields'] ) { |
373 if ( 'ids' === $this->query_vars['fields'] ) { |
377 * Filters the site query results. |
394 * Filters the site query results. |
378 * |
395 * |
379 * @since 4.6.0 |
396 * @since 4.6.0 |
380 * |
397 * |
381 * @param WP_Site[] $_sites An array of WP_Site objects. |
398 * @param WP_Site[] $_sites An array of WP_Site objects. |
382 * @param WP_Site_Query $this Current instance of WP_Site_Query (passed by reference). |
399 * @param WP_Site_Query $query Current instance of WP_Site_Query (passed by reference). |
383 */ |
400 */ |
384 $_sites = apply_filters_ref_array( 'the_sites', array( $_sites, &$this ) ); |
401 $_sites = apply_filters_ref_array( 'the_sites', array( $_sites, &$this ) ); |
385 |
402 |
386 // Convert to WP_Site instances. |
403 // Convert to WP_Site instances. |
387 $this->sites = array_map( 'get_site', $_sites ); |
404 $this->sites = array_map( 'get_site', $_sites ); |
581 * |
598 * |
582 * @since 4.6.0 |
599 * @since 4.6.0 |
583 * |
600 * |
584 * @param string[] $search_columns Array of column names to be searched. |
601 * @param string[] $search_columns Array of column names to be searched. |
585 * @param string $search Text being searched. |
602 * @param string $search Text being searched. |
586 * @param WP_Site_Query $this The current WP_Site_Query instance. |
603 * @param WP_Site_Query $query The current WP_Site_Query instance. |
587 */ |
604 */ |
588 $search_columns = apply_filters( 'site_search_columns', $search_columns, $this->query_vars['search'], $this ); |
605 $search_columns = apply_filters( 'site_search_columns', $search_columns, $this->query_vars['search'], $this ); |
589 |
606 |
590 $this->sql_clauses['where']['search'] = $this->get_search_sql( $this->query_vars['search'], $search_columns ); |
607 $this->sql_clauses['where']['search'] = $this->get_search_sql( $this->query_vars['search'], $search_columns ); |
591 } |
608 } |
618 * Filters the site query clauses. |
635 * Filters the site query clauses. |
619 * |
636 * |
620 * @since 4.6.0 |
637 * @since 4.6.0 |
621 * |
638 * |
622 * @param string[] $pieces An associative array of site query clauses. |
639 * @param string[] $pieces An associative array of site query clauses. |
623 * @param WP_Site_Query $this Current instance of WP_Site_Query (passed by reference). |
640 * @param WP_Site_Query $query Current instance of WP_Site_Query (passed by reference). |
624 */ |
641 */ |
625 $clauses = apply_filters_ref_array( 'sites_clauses', array( compact( $pieces ), &$this ) ); |
642 $clauses = apply_filters_ref_array( 'sites_clauses', array( compact( $pieces ), &$this ) ); |
626 |
643 |
627 $fields = isset( $clauses['fields'] ) ? $clauses['fields'] : ''; |
644 $fields = isset( $clauses['fields'] ) ? $clauses['fields'] : ''; |
628 $join = isset( $clauses['join'] ) ? $clauses['join'] : ''; |
645 $join = isset( $clauses['join'] ) ? $clauses['join'] : ''; |
655 $this->sql_clauses['limits'] = $limits; |
672 $this->sql_clauses['limits'] = $limits; |
656 |
673 |
657 $this->request = "{$this->sql_clauses['select']} {$this->sql_clauses['from']} {$where} {$this->sql_clauses['groupby']} {$this->sql_clauses['orderby']} {$this->sql_clauses['limits']}"; |
674 $this->request = "{$this->sql_clauses['select']} {$this->sql_clauses['from']} {$where} {$this->sql_clauses['groupby']} {$this->sql_clauses['orderby']} {$this->sql_clauses['limits']}"; |
658 |
675 |
659 if ( $this->query_vars['count'] ) { |
676 if ( $this->query_vars['count'] ) { |
660 return intval( $wpdb->get_var( $this->request ) ); |
677 return (int) $wpdb->get_var( $this->request ); |
661 } |
678 } |
662 |
679 |
663 $site_ids = $wpdb->get_col( $this->request ); |
680 $site_ids = $wpdb->get_col( $this->request ); |
664 |
681 |
665 return array_map( 'intval', $site_ids ); |
682 return array_map( 'intval', $site_ids ); |