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.
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.

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.

}


WP_Site_Query:: get_search_sql( string $string, array $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

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 on top of the latest WordPress API changes, developer tool updates, security alerts and more.