wp_register_core_abilities()

💡 云策文档标注

概述

wp_register_core_abilities() 函数用于注册 WordPress 核心的默认能力（abilities），这些能力通过 Abilities API 提供站点信息、用户信息和环境信息的获取功能。函数返回 void，主要面向开发者扩展或集成能力系统。

关键要点

注册三个核心能力：'core/get-site-info'（获取站点信息）、'core/get-user-info'（获取用户信息）和 'core/get-environment-info'（获取环境信息）。
每个能力包含标签、描述、类别、输入输出模式、执行回调和权限回调等配置。
能力使用 wp_register_ability() 注册，依赖于 get_bloginfo()、wp_get_current_user()、wp_get_environment_type() 等核心函数。
权限控制：站点和环境信息能力要求 manage_options 权限，用户信息能力要求用户已登录。
输出模式遵循 JSON Schema 规范，确保数据结构的类型安全和一致性。

代码示例

// 示例：调用 wp_register_core_abilities() 注册核心能力
wp_register_core_abilities();

// 之后可通过 Abilities API 使用这些能力，例如获取站点信息
$site_info = apply_filters( 'wp_ability_execute', 'core/get-site-info', array( 'fields' => array( 'name', 'url' ) ) );

注意事项

此函数在 WordPress 6.9.0 版本引入，需确保版本兼容性。
能力注册后，可通过 wp_ability_execute 过滤器或相关 API 调用执行。
输出模式中的 additionalProperties 设置为 false，限制额外属性，增强安全性。
环境信息能力中的 db_server_info 依赖于 wpdb::db_server_info() 方法，需检查其可用性。

📄 原文内容

Registers the default core abilities.

Return

void

Source

function wp_register_core_abilities(): void {
	$category_site = 'site';
	$category_user = 'user';

	$site_info_properties = array(
		'name'        => array(
			'type'        => 'string',
			'description' => __( 'The site title.' ),
		),
		'description' => array(
			'type'        => 'string',
			'description' => __( 'The site tagline.' ),
		),
		'url'         => array(
			'type'        => 'string',
			'description' => __( 'The site home URL.' ),
		),
		'wpurl'       => array(
			'type'        => 'string',
			'description' => __( 'The WordPress installation URL.' ),
		),
		'admin_email' => array(
			'type'        => 'string',
			'description' => __( 'The site administrator email address.' ),
		),
		'charset'     => array(
			'type'        => 'string',
			'description' => __( 'The site character encoding.' ),
		),
		'language'    => array(
			'type'        => 'string',
			'description' => __( 'The site language locale code.' ),
		),
		'version'     => array(
			'type'        => 'string',
			'description' => __( 'The WordPress version.' ),
		),
	);
	$site_info_fields     = array_keys( $site_info_properties );

	wp_register_ability(
		'core/get-site-info',
		array(
			'label'               => __( 'Get Site Information' ),
			'description'         => __( 'Returns site information configured in WordPress. By default returns all fields, or optionally a filtered subset.' ),
			'category'            => $category_site,
			'input_schema'        => array(
				'type'                 => 'object',
				'properties'           => array(
					'fields' => array(
						'type'        => 'array',
						'items'       => array(
							'type' => 'string',
							'enum' => $site_info_fields,
						),
						'description' => __( 'Optional: Limit response to specific fields. If omitted, all fields are returned.' ),
					),
				),
				'additionalProperties' => false,
				'default'              => array(),
			),
			'output_schema'       => array(
				'type'                 => 'object',
				'properties'           => $site_info_properties,
				'additionalProperties' => false,
			),
			'execute_callback'    => static function ( $input = array() ) use ( $site_info_fields ): array {
				$input = is_array( $input ) ? $input : array();
				$requested_fields = ! empty( $input['fields'] ) ? $input['fields'] : $site_info_fields;

				$result = array();
				foreach ( $requested_fields as $field ) {
					$result[ $field ] = get_bloginfo( $field );
				}

				return $result;
			},
			'permission_callback' => static function (): bool {
				return current_user_can( 'manage_options' );
			},
			'meta'                => array(
				'annotations'  => array(
					'readonly'    => true,
					'destructive' => false,
					'idempotent'  => true,
				),
				'show_in_rest' => true,
			),
		)
	);

	wp_register_ability(
		'core/get-user-info',
		array(
			'label'               => __( 'Get User Information' ),
			'description'         => __( 'Returns basic profile details for the current authenticated user to support personalization, auditing, and access-aware behavior.' ),
			'category'            => $category_user,
			'output_schema'       => array(
				'type'                 => 'object',
				'required'             => array( 'id', 'display_name', 'user_nicename', 'user_login', 'roles', 'locale' ),
				'properties'           => array(
					'id'            => array(
						'type'        => 'integer',
						'description' => __( 'The user ID.' ),
					),
					'display_name'  => array(
						'type'        => 'string',
						'description' => __( 'The display name of the user.' ),
					),
					'user_nicename' => array(
						'type'        => 'string',
						'description' => __( 'The URL-friendly name for the user.' ),
					),
					'user_login'    => array(
						'type'        => 'string',
						'description' => __( 'The login username for the user.' ),
					),
					'roles'         => array(
						'type'        => 'array',
						'description' => __( 'The roles assigned to the user.' ),
						'items'       => array(
							'type' => 'string',
						),
					),
					'locale'        => array(
						'type'        => 'string',
						'description' => __( 'The locale string for the user, such as en_US.' ),
					),
				),
				'additionalProperties' => false,
			),
			'execute_callback'    => static function (): array {
				$current_user = wp_get_current_user();

				return array(
					'id'            => $current_user->ID,
					'display_name'  => $current_user->display_name,
					'user_nicename' => $current_user->user_nicename,
					'user_login'    => $current_user->user_login,
					'roles'         => $current_user->roles,
					'locale'        => get_user_locale( $current_user ),
				);
			},
			'permission_callback' => static function (): bool {
				return is_user_logged_in();
			},
			'meta'                => array(
				'annotations'  => array(
					'readonly'    => true,
					'destructive' => false,
					'idempotent'  => true,
				),
				'show_in_rest' => false,
			),
		)
	);

	wp_register_ability(
		'core/get-environment-info',
		array(
			'label'               => __( 'Get Environment Info' ),
			'description'         => __( 'Returns core details about the site's runtime context for diagnostics and compatibility (environment, PHP runtime, database server info, WordPress version).' ),
			'category'            => $category_site,
			'output_schema'       => array(
				'type'                 => 'object',
				'required'             => array( 'environment', 'php_version', 'db_server_info', 'wp_version' ),
				'properties'           => array(
					'environment'    => array(
						'type'        => 'string',
						'description' => __( 'The site's runtime environment classification (can be one of these: production, staging, development, local).' ),
						'enum'        => array( 'production', 'staging', 'development', 'local' ),
					),
					'php_version'    => array(
						'type'        => 'string',
						'description' => __( 'The PHP runtime version executing WordPress.' ),
					),
					'db_server_info' => array(
						'type'        => 'string',
						'description' => __( 'The database server vendor and version string reported by the driver.' ),
					),
					'wp_version'     => array(
						'type'        => 'string',
						'description' => __( 'The WordPress core version running on this site.' ),
					),
				),
				'additionalProperties' => false,
			),
			'execute_callback'    => static function (): array {
				global $wpdb;

				$env          = wp_get_environment_type();
				$php_version  = phpversion();
				$db_server_info  = '';
				if ( method_exists( $wpdb, 'db_server_info' ) ) {
					$db_server_info = $wpdb->db_server_info() ?? '';
				}
				$wp_version   = get_bloginfo( 'version' );

				return array(
					'environment'    => $env,
					'php_version'    => $php_version,
					'db_server_info' => $db_server_info,
					'wp_version'     => $wp_version,
				);
			},
			'permission_callback' => static function (): bool {
				return current_user_can( 'manage_options' );
			},
			'meta'                => array(
				'annotations'  => array(
					'readonly'    => true,
					'destructive' => false,
					'idempotent'  => true,
				),
				'show_in_rest' => true,
			),
		)
	);
}

View all references View on Trac View on GitHub

Uses	Description
wp_register_ability()`wp-includes/abilities-api.php`	Registers a new ability using the Abilities API. It requires three steps:
wp_get_environment_type()`wp-includes/load.php`	Retrieves the current environment type.
wpdb::db_server_info()`wp-includes/class-wpdb.php`	Returns the raw version string of the database server.
get_user_locale()`wp-includes/l10n.php`	Retrieves the locale of a user.
wp_get_current_user()`wp-includes/pluggable.php`	Retrieves the current user object.
current_user_can()`wp-includes/capabilities.php`	Returns whether the current user has the specified capability.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
is_user_logged_in()`wp-includes/pluggable.php`	Determines whether the current visitor is a logged in user.
get_bloginfo()`wp-includes/general-template.php`	Retrieves information about the current site.

Show 4 more Show less

Changelog

Version	Description
6.9.0	Introduced.

云策 WordPress 开发者社区

函数文档

wp_register_core_abilities()

概述

关键要点

代码示例

注意事项

Return

Source

Changelog

函数文档

概述

关键要点

代码示例

注意事项

Return

Source

Related

Changelog