云策 WordPress 开发者社区

函数文档

wp_prepare_site_data()

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

概述

wp_prepare_site_data() 函数用于准备站点数据，以便插入或更新到数据库中。它处理数据验证、标准化和兼容性，确保数据符合数据库要求。

关键要点

  • 函数接受三个参数：$data（关联数组，站点数据）、$defaults（数组，数据默认值）和 $old_site（WP_Site 对象或 null，用于更新操作）。
  • 返回一个数组（准备就绪的站点数据）或 WP_Error 对象（如果验证失败）。
  • 函数内部维护向后兼容性，将 'site_id' 映射到 'network_id'，并过滤数据以仅包含允许的字段。
  • 提供了两个 Hook：'wp_normalize_site_data' 过滤器用于标准化数据，'wp_validate_site_data' 动作用于验证数据。
  • 该函数在 WordPress 5.1.0 版本中引入，被 wp_insert_site() 和 wp_update_site() 调用。

代码示例

function wp_prepare_site_data( $data, $defaults, $old_site = null ) {
    // 维护向后兼容性
    if ( isset( $data['site_id'] ) ) {
        if ( ! empty( $data['site_id'] ) && empty( $data['network_id'] ) ) {
            $data['network_id'] = $data['site_id'];
        }
        unset( $data['site_id'] );
    }

    // 应用过滤器标准化数据
    $data = apply_filters( 'wp_normalize_site_data', $data );

    // 定义允许的数据字段并过滤
    $allowed_data_fields = array( 'domain', 'path', 'network_id', 'registered', 'last_updated', 'public', 'archived', 'mature', 'spam', 'deleted', 'lang_id' );
    $data = array_intersect_key( wp_parse_args( $data, $defaults ), array_flip( $allowed_data_fields ) );

    // 初始化错误对象并触发验证动作
    $errors = new WP_Error();
    do_action( 'wp_validate_site_data', $errors, $data, $old_site );

    if ( ! empty( $errors->errors ) ) {
        return $errors;
    }

    // 准备数据库字段
    $data['site_id'] = $data['network_id'];
    unset( $data['network_id'] );

    return $data;
}

注意事项

  • 开发者应确保传递给 $data 的参数符合 wp_insert_site() 文档中描述的可能数据字段。
  • 使用 'wp_validate_site_data' 动作时，插件应通过 WP_Error::add() 方法向 $errors 对象添加验证错误。
  • 函数处理数据时，会合并 $data 和 $defaults，并仅保留 $allowed_data_fields 中定义的字段。
📄 原文内容

Prepares site data for insertion or update in the database.

Parameters

$dataarrayrequired
Associative array of site data passed to the respective function.
See wp_insert_site() for the possibly included data.
$defaultsarrayrequired
Site data defaults to parse $data against.
$old_siteWP_Site|nulloptional
Old site object if an update, or null if an insertion.

Default:null

Return

array|WP_Error Site data ready for a database transaction, or WP_Error in case a validation error occurred.

Source

function wp_prepare_site_data( $data, $defaults, $old_site = null ) {

	// Maintain backward-compatibility with `$site_id` as network ID.
	if ( isset( $data['site_id'] ) ) {
		if ( ! empty( $data['site_id'] ) && empty( $data['network_id'] ) ) {
			$data['network_id'] = $data['site_id'];
		}
		unset( $data['site_id'] );
	}

	/**
	 * Filters passed site data in order to normalize it.
	 *
	 * @since 5.1.0
	 *
	 * @param array $data Associative array of site data passed to the respective function.
	 *                    See <a href="https://developer.wordpress.org/reference/functions/wp_insert_site/">wp_insert_site()</a> for the possibly included data.
	 */
	$data = apply_filters( 'wp_normalize_site_data', $data );

	$allowed_data_fields = array( 'domain', 'path', 'network_id', 'registered', 'last_updated', 'public', 'archived', 'mature', 'spam', 'deleted', 'lang_id' );
	$data                = array_intersect_key( wp_parse_args( $data, $defaults ), array_flip( $allowed_data_fields ) );

	$errors = new WP_Error();

	/**
	 * Fires when data should be validated for a site prior to inserting or updating in the database.
	 *
	 * Plugins should amend the `$errors` object via its `WP_Error::add()` method.
	 *
	 * @since 5.1.0
	 *
	 * @param WP_Error     $errors   Error object to add validation errors to.
	 * @param array        $data     Associative array of complete site data. See <a href="https://developer.wordpress.org/reference/functions/wp_insert_site/">wp_insert_site()</a>
	 *                               for the included data.
	 * @param WP_Site|null $old_site The old site object if the data belongs to a site being updated,
	 *                               or null if it is a new site being inserted.
	 */
	do_action( 'wp_validate_site_data', $errors, $data, $old_site );

	if ( ! empty( $errors->errors ) ) {
		return $errors;
	}

	// Prepare for database.
	$data['site_id'] = $data['network_id'];
	unset( $data['network_id'] );

	return $data;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_normalize_site_data’, array $data )

Filters passed site data in order to normalize it.

do_action( ‘wp_validate_site_data’, WP_Error $errors, array $data, WP_Site|null $old_site )

Fires when data should be validated for a site prior to inserting or updating in the database.

Uses Description
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.
WP_Error::__construct()wp-includes/class-wp-error.php

Initializes the error.

Show 2 moreShow less

Used by Description
wp_insert_site()wp-includes/ms-site.php

Inserts a new site into the database.
wp_update_site()wp-includes/ms-site.php

Updates a site in the database.

Changelog

Version Description
5.1.0 Introduced.