Class: WP_Site_Query

Core class used for querying sites.


Properties

Name Type(s) Default Value Summary
request string SQL for database query.
sql_clauses array SQL query clauses.
meta_query WP_Meta_Query Metadata query container.
meta_query_clauses array Metadata query clauses.
date_query object Date query container.
query_vars array Query vars set by the user.
query_var_defaults array Default values for query vars.
sites array List of sites located by the query.
found_sites integer The amount of found sites for the current query.
max_num_pages integer The number of pages.

Methods

WP_Site_Query:: __construct( string | array $query = '' )

Sets up the site query, based on the query vars passed. Since 4.6.0. Since 4.8.0. Since 5.1.0.

Arguments

Name Type(s) Default Value Description
$query string | array

{ 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 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.
                                           Default null.
@type string       $fields                 Site fields to return. Accepts 'ids' (returns an array of site IDs)
                                           or empty (returns an array of complete site objects). Default empty.
@type int          $ID                     A site ID to only return that site. Default empty.
@type int          $number                 Maximum number of sites to retrieve. Default 100.
@type int          $offset                 Number of sites to offset the query. Used to build LIMIT clause.
                                           Default 0.
@type bool         $no_found_rows          Whether to disable the `SQL_CALC_FOUND_ROWS` query. Default true.
@type string|array $orderby                Site status or array of statuses. Accepts 'id', 'domain', 'path',
                                           'network_id', 'last_updated', 'registered', 'domain_length',
                                           'path_length', 'site__in' and 'network__in'. Also accepts false,
                                           an empty array, or 'none' to disable `ORDER BY` clause.
                                           Default 'id'.
@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 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       $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 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       $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'.
                                           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.
@type array        $meta_query             Meta query clauses to limit retrieved sites by. See `WP_Meta_Query`.
                                           Default empty.
@type string       $meta_key               Limit sites to those matching a specific metadata key.
                                           Can be used in conjunction with `$meta_value`. Default empty.
@type string       $meta_value             Limit sites to those matching a specific metadata value.
                                           Usually used in conjunction with `$meta_key`. Default empty.
@type string       $meta_type              Data type that the `$meta_value` column will be CAST to for
                                           comparisons. Default empty.
@type string       $meta_compare           Comparison operator to test the `$meta_value`. Default empty.

}


WP_Site_Query:: get_search_sql( string $string, array<mixed,string> $columns )

Used internally to generate an SQL string for searching across multiple columns. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$string string

Search string.

$columns array<mixed,string>

Array of columns to search.

Returns

string

Search SQL.


WP_Site_Query:: get_site_ids( )

Used internally to get a list of site IDs matching the query vars. Since 4.6.0.

Returns

integer | array

A single count of site IDs if a count query. An array of site IDs if a full query.


WP_Site_Query:: get_sites( )

Retrieves a list of sites matching the query vars. Since 4.6.0.

Returns

array | integer

List of WP_Site objects, a list of site ids when 'fields' is set to 'ids', or the number of sites when 'count' is passed as a query var.


WP_Site_Query:: parse_order( string $order )

Parses an 'order' query variable and cast it to 'ASC' or 'DESC' as necessary. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$order string

The 'order' query variable.

Returns

string

The sanitized 'order' query variable.


WP_Site_Query:: parse_orderby( string $orderby )

Parses and sanitizes 'orderby' keys passed to the site query. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$orderby string

Alias for the field to order by.

Returns

string | false

Value to used in the ORDER clause. False otherwise.


WP_Site_Query:: parse_query( string | array $query = '' )

Parses arguments passed to the site query with default query parameters. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$query string | array

Array or string of WP_Site_Query arguments. See WP_Site_Query::__construct().


WP_Site_Query:: query( string | array $query )

Sets up the WordPress query for retrieving sites. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$query string | array

Array or URL query string of parameters.

Returns

array | integer

List of WP_Site objects, a list of site ids when 'fields' is set to 'ids', or the number of sites when 'count' is passed as a query var.


WP_Site_Query:: set_found_sites( )

Populates found_sites and max_num_pages properties for the current query if the limit clause was used. Since 4.6.0.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.