云策 WordPress 开发者社区

函数文档

wp_switch_roles_and_user()

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

概述

wp_switch_roles_and_user() 函数用于在多站点环境中切换当前站点的角色和用户能力到另一个站点。它通过更新全局 WP_Roles 实例和当前用户对象来实现站点间的权限切换。

关键要点

  • 函数接受两个必需参数：$new_site_id（新站点ID）和 $old_site_id（旧站点ID）。
  • 如果新旧站点ID相同或 init action 未触发，函数将直接返回而不执行任何操作。
  • 函数内部调用 wp_roles()->for_site($new_site_id) 和 wp_get_current_user()->for_site($new_site_id) 来切换角色和用户能力。
  • 此函数自 WordPress 4.9.0 版本引入，适用于多站点开发场景。

代码示例

wp_switch_roles_and_user( $new_site_id, $old_site_id ) {
    if ( $new_site_id === $old_site_id ) {
        return;
    }

    if ( ! did_action( 'init' ) ) {
        return;
    }

    wp_roles()->for_site( $new_site_id );
    wp_get_current_user()->for_site( $new_site_id );
}

注意事项

  • 确保在调用此函数前 init action 已触发，否则函数将提前返回。
  • 函数仅适用于 WordPress 多站点环境，用于管理不同站点间的用户权限切换。
  • 相关函数包括 WP_Roles::for_site()、wp_roles()、wp_get_current_user() 和 did_action()，开发者应熟悉这些函数的使用。
📄 原文内容

Switches the initialized roles and current user capabilities to another site.

Parameters

$new_site_idintrequired
New site ID.
$old_site_idintrequired
Old site ID.

Source

function wp_switch_roles_and_user( $new_site_id, $old_site_id ) {
	if ( $new_site_id === $old_site_id ) {
		return;
	}

	if ( ! did_action( 'init' ) ) {
		return;
	}

	wp_roles()->for_site( $new_site_id );
	wp_get_current_user()->for_site( $new_site_id );
}

View all references View on Trac View on GitHub

Uses Description
WP_Roles::for_site()wp-includes/class-wp-roles.php

Sets the site to operate on. Defaults to the current site.
wp_roles()wp-includes/capabilities.php

Retrieves the global WP_Roles instance and instantiates it if necessary.
wp_get_current_user()wp-includes/pluggable.php

Retrieves the current user object.
did_action()wp-includes/plugin.php

Retrieves the number of times an action has been fired during the current request.

Changelog

Version Description
4.9.0 Introduced.