wp_get_sites()

💡 云策文档标注

概述

wp_get_sites() 函数用于返回网络或多网络中的站点数组，但自 WordPress 4.6.0 起已弃用，建议使用 get_sites() 替代。该函数在大型网络（默认超过 10,000 个站点）中返回空数组，并支持多种参数筛选站点。

关键要点

函数已弃用：自 WordPress 4.6.0 起，wp_get_sites() 被标记为弃用，应改用 get_sites()。
返回数组：返回一个包含 WP_Site 数据的关联数组，每个站点的值均为字符串类型，需注意与整数比较时使用 == 而非 ===。
大型网络处理：如果 wp_is_large_network() 返回 TRUE（默认阈值 10,000 个站点），函数返回空数组，可通过 wp_is_large_network 过滤器调整。
参数支持：包括 network_id、public、archived、mature、spam、deleted、limit 和 offset，用于筛选和分页查询站点。
向后兼容性：函数内部处理了 network_id 数组和 limit 参数的转换，以保持与旧代码的兼容性。

代码示例

$args = array(
    'network_id' => null,
    'public'     => null,
    'archived'   => null,
    'mature'     => null,
    'spam'       => null,
    'deleted'    => null,
    'limit'      => 100,
    'offset'     => 0,
);
$array = wp_get_sites( $args );
print_r ($array);

注意事项

弃用警告：使用 wp_get_sites() 会触发 _deprecated_function()，建议在开发中迁移到 get_sites() 以避免未来兼容性问题。
数据类型：返回的站点数组中所有值均为字符串，比较 blog_id 等数值时需使用 == 或 !=，而非 === 或 !==。
性能考虑：在大型网络中，函数可能返回空数组，需检查 wp_is_large_network() 状态或使用替代方法。

📄 原文内容

Return an array of sites for a network or networks.

Parameters

$argsarrayoptional

Array of default arguments. Optional.

network_id int|int[]
A network ID or array of network IDs. Set to null to retrieve sites from all networks. Defaults to current network ID.
public int
Retrieve public or non-public sites. Default null, for any.
archived int
Retrieve archived or non-archived sites. Default null, for any.
mature int
Retrieve mature or non-mature sites. Default null, for any.
spam int
Retrieve spam or non-spam sites. Default null, for any.
deleted int
Retrieve deleted or non-deleted sites. Default null, for any.
limit int
Number of sites to limit the query to. Default 100.
offset int
Exclude the first x sites. Used in combination with the $limit parameter. Default 0.

Default:array()

Return

array[] An empty array if the installation is considered “large” via wp_is_large_network() . Otherwise, an associative array of WP_Site data as arrays.

If wp_is_large_network() returns TRUE, wp_get_sites() will return an empty array. By default wp_is_large_network() returns TRUE if there are 10,000 or more sites in your network. This can be filtered using the wp_is_large_network filter.

Each site’s array is composed entirely of string values, even for numeric values. This means that == or !=, not === or !==, should be used to compare [blog_id] to get_current_blog_id(), which returns an integer value.

Source

function wp_get_sites( $args = array() ) {
	_deprecated_function( __FUNCTION__, '4.6.0', 'get_sites()' );

	if ( wp_is_large_network() )
		return array();

	$defaults = array(
		'network_id' => get_current_network_id(),
		'public'     => null,
		'archived'   => null,
		'mature'     => null,
		'spam'       => null,
		'deleted'    => null,
		'limit'      => 100,
		'offset'     => 0,
	);

	$args = wp_parse_args( $args, $defaults );

	// Backward compatibility.
	if( is_array( $args['network_id'] ) ){
		$args['network__in'] = $args['network_id'];
		$args['network_id'] = null;
	}

	if( is_numeric( $args['limit'] ) ){
		$args['number'] = $args['limit'];
		$args['limit'] = null;
	} elseif ( ! $args['limit'] ) {
		$args['number'] = 0;
		$args['limit'] = null;
	}

	// Make sure count is disabled.
	$args['count'] = false;

	$_sites  = get_sites( $args );

	$results = array();

	foreach ( $_sites as $_site ) {
		$_site = get_site( $_site );
		$results[] = $_site->to_array();
	}

	return $results;
}

View all references View on Trac View on GitHub

Uses	Description
get_current_network_id()`wp-includes/load.php`	Retrieves the current network ID.
get_sites()`wp-includes/ms-site.php`	Retrieves a list of sites matching requested arguments.
get_site()`wp-includes/ms-site.php`	Retrieves site data given a site ID or site object.
wp_is_large_network()`wp-includes/ms-functions.php`	Determines whether or not we have a large network.
_deprecated_function()`wp-includes/functions.php`	Marks a function as deprecated and inform when it has been used.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.

Show 2 more Show less

Changelog

Version	Description
4.6.0	Deprecated. Use get_sites()
3.7.0	Introduced.

User Contributed Notes

Skip to note 2 content

Codex

10 years ago

Basic Example

if you specify null to the ‘network_id’ then all site infomation in the network are returned.

 null,
    'public'     => null,
    'archived'   => null,
    'mature'     => null,
    'spam'       => null,
    'deleted'    => null,
    'limit'      => 100,
    'offset'     => 0,
); 
$array = wp_get_sites( $args );
print_r ($array);
?>

Example of the array returned:

Array(
    [0] => Array(
        [blog_id] => 1
        [site_id] => 1
        [domain] => example.com
        [path] => /
        [registered] => 2013-11-08 17:56:46
        <p style="font-style:normal;font-weight:700">Last updated</p> => 2013-11-08 18:57:19
        [public] => 1
        [archived] => 0
        [mature] => 0
        [spam] => 0
        [deleted] => 0
        [lang_id] => 0
    )

    [1] => Array(
        [blog_id] => 2
        [site_id] => 1
        [domain] => example.com
        [path] => /examplesubsite/
        [registered] => 2013-11-08 18:07:22
        <p style="font-style:normal;font-weight:700">Last updated</p> => 2013-11-08 18:13:40
        [public] => 1
        [archived] => 0
        [mature] => 0
        [spam] => 0
        [deleted] => 0
        [lang_id] => 0
    )
)

If you specified ‘1’ to the ‘network_id’ then the array that include only the first element must be returned.

云策 WordPress 开发者社区

函数文档