云策 WordPress 开发者社区

函数文档

get_sites()

查看官方原文 ↗
💡 云策文档标注

概述

get_sites() 函数用于检索匹配指定参数的站点列表，基于 WP_Site_Query 类实现。它返回 WP_Site 对象数组、站点 ID 数组或站点数量，具体取决于参数设置。

关键要点

  • 函数接受可选参数 $args，可以是数组或字符串，用于指定查询条件，参考 WP_Site_Query::__construct()。
  • 返回值类型可变：默认返回 WP_Site 对象数组；当 'fields' 设为 'ids' 时返回站点 ID 数组；当 'count' 作为查询变量时返回站点数量。
  • 自 WordPress 4.6.0 引入，替代了已弃用的 wp_get_sites() 函数，注意返回类型从数组变为对象数组。
  • 默认限制返回前 100 个站点，可通过 'number' 参数调整，设置为 0 可获取所有站点，但 -1 无效。
  • 参数 'limit' 在 wp_get_sites() 中自动转换为 'number'，但在 get_sites() 中需直接使用 'number'。

代码示例

// 获取所有站点（WordPress 4.6+）
if ( function_exists('get_sites') && class_exists('WP_Site_Query') ) {
    $sites = get_sites();
    foreach ( $sites as $site ) {
        switch_to_blog( $site->blog_id );
        // 执行操作
        restore_current_blog();
    }
}

// 使用参数限制返回站点数量
$args = array(
    'number' => 420,
);
$blog_list = get_sites( $args );

// 将站点对象转换为数组以访问属性
$subsites = get_sites();
foreach ( $subsites as $subsite ) {
    $subsite_id = get_object_vars($subsite)["blog_id"];
    $subsite_name = get_blog_details($subsite_id)->blogname;
    echo 'Site ID/Name: ' . $subsite_id . ' / ' . $subsite_name . 'n';
}

注意事项

  • 从 wp_get_sites() 迁移时，注意返回类型差异：get_sites() 返回对象数组，而非多维数组，循环时需使用对象属性（如 $site->blog_id）或 get_object_vars() 转换。
  • 参数 'number' 默认值为 100，若不指定可能只影响前 100 个站点，需根据需求调整。
  • 函数在 WordPress 4.8.0 中新增了 'lang_id'、'lang__in' 和 'lang__not_in' 参数，用于语言过滤。
📄 原文内容

Retrieves a list of sites matching requested arguments.

Description

See also

Parameters

$argsstring|arrayoptional
Array or string of arguments. See WP_Site_Query::__construct() for information on accepted arguments.

Default:array()

Return

WP_Site[]|int[]|int 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.

Source

function get_sites( $args = array() ) {
	$query = new WP_Site_Query();

	return $query->query( $args );
}

View all references View on Trac View on GitHub

Uses Description
WP_Site_Query::__construct()wp-includes/class-wp-site-query.php

Sets up the site query, based on the query vars passed.
Used by Description
get_oembed_response_data_for_url()wp-includes/embed.php

Retrieves the oEmbed response data for a given URL.
WP_Network::get_main_site_id()wp-includes/class-wp-network.php

Returns the main site ID for the network.
WP_MS_Sites_List_Table::prepare_items()wp-admin/includes/class-wp-ms-sites-list-table.php

Prepares the list of sites for display.
WP_Importer::set_blog()wp-admin/includes/class-wp-importer.php
get_blogs_of_user()wp-includes/user.php

Gets the sites a user belongs to.
wp_update_network_site_counts()wp-includes/ms-functions.php

Updates the network-wide site count.
wp_get_sites()wp-includes/ms-deprecated.php

Return an array of sites for a network or networks.
domain_exists()wp-includes/ms-functions.php

Checks whether a site name is already taken.
get_blog_id_from_url()wp-includes/ms-functions.php

Gets a blog’s numeric ID from its URL.
get_site_by_path()wp-includes/ms-load.php

Retrieves the closest matching site object by its domain and path.
get_id_from_blogname()wp-includes/ms-blogs.php

Retrieves a site’s ID given its (subdomain or directory) slug.

Show 6 moreShow less

Changelog

Version Description
4.8.0 Introduced the 'lang_id', 'lang__in', and 'lang__not_in' parameters.
4.6.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    Lance Cleveland


    You must log in to vote on the helpfulness of this noteVote results for this note: 9You must log in to vote on the helpfulness of this note

    Also good to know… get_sites now returns an OBJECT not a named array.

    A code example that may help:

    // WordPress 4.6
//
if ( function_exists( 'get_sites' ) && class_exists( 'WP_Site_Query' ) ) {
	$sites = get_sites();
	foreach ( $sites as $site ) {
		switch_to_blog( $site->blog_id );
                // do something
		restore_current_blog();
	}
	return;
}

// WordPress < 4.6
//
if ( function_exists( 'wp_get_sites' ) ) {
	$sites = wp_get_sites();
	foreach ( $sites as $site ) {
		switch_to_blog( $site['blog_id'] );
                // do something
		restore_current_blog();
	}
	return;
}

  2. Skip to note 6 content


    mkormendy


    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

    Beware, using get_sites() as a drop-in for wp_get_sites() may not produce results as expected.

    PHP Fatal error: Cannot use object of type WP_Site as array in /path/to/code/that/uses/get_sites/method/file.php

    It’s true that get_sites() returns an array, however, it produces an array of sites as objects. This is different from wp_get_sites(), which used to produce a multidimensional array of the sites, with their properties in a secondary array dimension (simply an array of site arrays with that site’s properties).

    If you’re attempting to loop through the sites to get the properties of each site with get_sites() , you’ll need to convert each site object to an array using get_object_vars( object ) http://www.php.net/manual/en/function.get-object-vars.php.

    See the example below noting the use of get_object_vars on line three:

    $subsites = get_sites();
foreach( $subsites as $subsite ) {
  $subsite_id = get_object_vars($subsite)["blog_id"];
  $subsite_name = get_blog_details($subsite_id)->blogname;
  echo 'Site ID/Name: ' . $subsite_id . ' / ' . $subsite_name . 'n';
}

    This should return the following list of sites:

    Site ID/Name: 1 / SiteNameOne
    Site ID/Name: 2 / SiteNameTwo
    Site ID/Name: 3 / SiteNameThree

  3. Skip to note 7 content


    Lance Cleveland


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    wp_get_sites() ‘limit’ argument is now ‘number’.

    wp_get_sites() converted this to $args[‘number’] for you, get_sites() does not appear to handle this parameter name conversion for you.

    Reference: https://developer.wordpress.org/reference/functions/wp_get_sites/