sites_pre_query
概述
sites_pre_query 是一个 WordPress 过滤器，用于在 get_sites 查询执行前拦截并修改站点数据。开发者可以通过此过滤器自定义查询逻辑，绕过默认的数据库查询。
关键要点
- 过滤器允许返回非空值以绕过 WordPress 的默认站点查询，返回类型取决于查询变量：当 $this->query_vars['count'] 设置时返回整数计数；当 'ids' === $this->query_vars['fields'] 时返回站点 ID 数组；否则返回 WP_Site 对象数组。
- 如果返回站点数据数组，它将被赋值给当前 WP_Site_Query 实例的 sites 属性。
- 建议需要分页信息的过滤函数设置 WP_Site_Query 对象的 found_sites 和 max_num_pages 属性，因为如果 WP_Site_Query 不执行数据库查询，它无法自动生成这些值。
注意事项
- 过滤器参数包括 $site_data（站点数据、计数或 null）和 $query（WP_Site_Query 实例引用）。
- 在 WordPress 5.6.0 中，返回的站点数据数组被赋值给 WP_Site_Query 的 sites 属性；此过滤器自 5.2.0 版本引入。
Filters the site data before the get_sites query takes place.
Description
Return a non-null value to bypass WordPress’ default site queries.
The expected return type from this filter depends on the value passed in the request query vars:
- When
$this->query_vars['count']is set, the filter should return the site count as an integer. - When
'ids' === $this->query_vars['fields'], the filter should return an array of site IDs. - Otherwise the filter should return an array of WP_Site objects.
Note that if the filter returns an array of site data, it will be assigned to the sites property of the current WP_Site_Query instance.
Filtering functions that require pagination information are encouraged to set the found_sites and max_num_pages properties of the WP_Site_Query object, passed to the filter by reference. If WP_Site_Query does not perform a database query, it will not have enough information to generate these values itself.
Parameters
$site_dataWP_Site[]|int[]|int|null-
Return an array of site data to short-circuit WP’s site query, the site count as an integer if
$this->query_vars['count']is set, or null to run the normal queries. $queryWP_Site_Query-
The WP_Site_Query instance, passed by reference.
Source
$site_data = apply_filters_ref_array( 'sites_pre_query', array( $site_data, &$this ) );
Changelog
| Version | Description |
|---|---|
| 5.6.0 | The returned array of site data is assigned to the sites property of the current WP_Site_Query instance. |
| 5.2.0 | Introduced. |