WordPress 7.2 更新了 Abilities API,使权限、输入处理和 JSON 输出更加可预测。Abilities 可以声明每次调用都需要的能力。直接通过 PHP 调用和发送 REST 请求时,会根据能力的模式清理输入,而 JSON 结果会保留模式所声明的对象或数组结构。下面的示例说明了能力作者和集成开发者需要更改的内容。
声明必需的能力
新的 required_capabilities 注册参数接受一组非空的能力字符串。在检查权限时,WordPress 会使用 current_user_can() 检查每项能力。所有列出的能力都必须通过检查,权限回调才会运行。
对于适用于每次调用的要求,请使用此列表。例如,core/settings-get 始终需要 manage_options。其注册信息声明了该能力,并省略 permission_callback。下面的摘录展示了它的权限参数:
array(
'required_capabilities' => array( 'manage_options' ),
// No permission_callback: the capability covers every call.
);
如果权限还取决于输入,请将该检查保留在 permission_callback 中。以下能力每次调用都需要 edit_posts,然后检查用户能否编辑所请求的文章。该示例假设 my-plugin 类别已经注册:
add_action(
'wp_abilities_api_init',
static function () {
wp_register_ability(
'my-plugin/get-post-title',
array(
'label' => __( 'Get post title', 'my-plugin' ),
'description' => __( 'Read the title of a post you can edit.', 'my-plugin' ),
'category' => 'my-plugin',
'required_capabilities' => array( 'edit_posts' ),
'input_schema' => array(
'type' => 'integer',
'minimum' => 1,
),
'output_schema' => array( 'type' => 'string' ),
'permission_callback' => static function ( int $post_id ): bool {
return current_user_can( 'edit_post', $post_id );
},
'execute_callback' => static function ( int $post_id ): string {
return get_post_field( 'post_title', $post_id, 'raw' );
},
'meta' => array(
'show_in_rest' => true,
'annotations' => array( 'readonly' => true ),
),
)
);
}
);
请根据能力的要求选择权限参数:
- 如果非空的
required_capabilities列表涵盖所有权限检查,请省略permission_callback。不需要__return_true。 - 如果调用需要额外检查(例如访问特定文章),请提供回调。声明的能力会先被检查。
- 如果
required_capabilities为空或被省略,则必须提供有效的permission_callback。仅当该能力有意允许所有人执行时,才使用__return_true;否则,请提供适当的权限检查。
现有的 wp_ability_permission_result 过滤器仍会接收结果,并可以覆盖该结果,包括因缺少某项能力而导致的拒绝。
按能力筛选发现结果
集成可以通过 $ability->get_required_capabilities() 读取声明信息。该信息也会包含在 REST 发现响应中。
如需请求当前用户满足其声明要求的 Abilities:
$abilities = wp_get_abilities(
array( 'has_required_capabilities' => true )
);
REST 集合支持相同的可选筛选器:
GET /wp-json/wp-abilities/v1/abilities?has_required_capabilities=true
此筛选器不会运行权限回调或 wp_ability_permission_result 过滤器。未声明能力的 Abilities 会通过此筛选器(其他发现筛选器仍可能将其排除),而通过发现的 Ability 在处理特定输入时仍可能拒绝执行。在上面的示例中,作者可能会发现该 Ability,却无权通过它读取另一位作者的草稿。
仅声明每次调用都需要的能力。将特定输入的要求放入静态列表,可能会使有权使用其他输入执行该能力的用户无法发现它。
相关工单:#66325。
在不同执行路径中一致地准备输入
WP_Ability::prepare_input() 现在负责处理 execute() 所使用的输入准备工作:
- 规范化输入,包括在输入为
null时应用顶层模式默认值。 - 根据输入模式对其进行验证。
- 使用该模式对验证后的值进行清理。
权限回调和执行回调会收到准备后的值。在上面的示例中,$ability->execute( '123' ) 会将整数 123 传递给两个回调。模式格式也很重要:使用 format: text-field 声明的字符串会在清理期间去除其标签。
验证在清理之前运行。无效值会在类型转换或属性移除掩盖错误之前被拒绝。准备过程中发生失败会返回 WP_Error 并停止执行。
REST 执行控制器会分别准备原始请求输入,用于权限检查和执行。调用 execute() 的自定义集成可以传入原始输入,让能力(ability)负责准备。
数字输入会转换为浮点数
在直接 PHP 调用中,number 模式会将 10 这样的整数转换为浮点数 10.0,与 REST 行为一致。当回调需要整数时,请使用 integer 模式。使用 number 的回调应接受浮点数,并避免进行 is_int( $input ) 或 $input === 10 之类的检查。
其他模式转换包括:字符串 "false" 转换为布尔值 false,以及在整数数组模式下 "1,2" 转换为 array( 1, 2 )。
清理失败会中止执行
输入可能通过验证但仍会清理失败。例如,array( '1', '01' ) 包含不同的字符串,但两者都会转换为整数 1。这会触发整数数组模式的 uniqueItems: true 错误。
在 7.2 中,此失败会返回 ability_invalid_input,即使发生在嵌套字段中,也会在权限或执行回调运行之前返回。REST 端点返回 HTTP 400。当某个字段失败时,不再回退到未经清理的原始输入;否则,这种回退可能会让权限回调收到字符串 "false",而该字符串在 PHP 中为真值。
直接权限检查需要已准备的输入
check_permissions() 不会准备其输入。如果集成直接调用它,必须先调用 prepare_input(),并在出现错误时停止:
$ability = wp_get_ability( 'my-plugin/get-post-title' );
if ( null === $ability ) {
return new WP_Error( 'example_missing_ability', 'The ability is not registered.' );
}
$input = $ability->prepare_input( '123' );
if ( is_wp_error( $input ) ) {
return $input;
}
// $input is now the integer 123.
$permission = $ability->check_permissions( $input );
if ( is_wp_error( $permission ) ) {
return $permission;
}
if ( true !== $permission ) {
return new WP_Error( 'example_forbidden', 'You cannot edit this post.' );
}
// This checks permission only. To run the ability, use execute().
直接权限检查不会执行能力。要执行,请调用 execute();它会在正常生命周期中执行准备和权限检查。
仅调用 normalize_input() 并不足够:它不包含模式验证和清理。同样,validate_input() 返回的是验证结果,而不是已准备的值。
如果自定义权限检查路径已经对输入进行了规范化和验证,可以用 prepare_input() 替代这些步骤。请在调用 check_permissions() 前保留错误检查:
- $input = $ability->normalize_input( $raw_input );
+ $input = $ability->prepare_input( $raw_input );
if ( is_wp_error( $input ) ) {
return $input;
}
- $valid = $ability->validate_input( $input );
- if ( is_wp_error( $valid ) ) {
- return $valid;
- }
$permission = $ability->check_permissions( $input );
这会为自定义路径添加模式清理。请继续按照上述方式处理权限结果。
REST 控制器的 sanitize_input_for_ability() 方法在 7.2 中已弃用,并且不再注册为输入清理器。其兼容实现会原样返回输入。
相关工单:#66383。
在 JSON 中保留空对象
即使模式描述的是对象,空 PHP 数组也会编码为 []。这可能导致期望对象的客户端收到数组。
共享的 wp_prepare_json_schema_for_client() 函数可准备模式,以便在 WordPress 服务端验证之外使用。它会移除不支持的关键字,并准备嵌套模式及其现有默认值,因此适用于插件向 REST 客户端或前端公开模式的场景。在 7.2 中,其默认值处理会根据模式保留空对象:
$schema = array(
'type' => 'object',
'default' => array(),
);
echo wp_json_encode( wp_prepare_json_schema_for_client( $schema ) );
// {"type":"object","default":{}}
新的 wp_prepare_json_value_for_client() 函数会将相同的区分应用于结果值,包括嵌套属性和数组项:
$schema = array(
'type' => 'object',
'properties' => array(
'settings' => array( 'type' => 'object' ),
'items' => array(
'type' => 'array',
'items' => array( 'type' => 'object' ),
),
),
);
$result = array(
'settings' => array(),
'items' => array( array() ),
);
echo wp_json_encode( wp_prepare_json_value_for_client( $result, $schema ) );
// {"settings":{},"items":[{}]}
Abilities REST API 在准备模式和执行结果时会应用这些辅助函数,包括根级空对象和顶层列表中的对象。WordPress AI Client 也会使用输出模式准备能力结果。直接以 PHP 调用 $ability->execute() 时,仍会返回回调结果,而不会执行此 JSON 表示步骤。序列化结果的自定义传输应在编码前使用能力的输出模式准备结果。
此准备过程不会执行完整的模式验证,也不会填充缺失的默认值。它只会改变现有值的表示形式。当匹配的模式允许数组时,空数组仍为 [];同时允许对象和数组的模式不会强制将其变为 {}。
集成开发者应做的更改
能力作者应在输出模式中明确声明 type: object 或 type: array,包括空值很重要的嵌套属性。消费对象模式的客户端应预期空结果为 {}。请更新依赖在这种情况下接收到 [] 的代码。声明为数组的结果将继续使用 []。
对于自定义传输层,请在进行 JSON 编码之前立即准备成功结果。这里,$ability 是已经解析的 WP_Ability,$raw_input 是调用方的输入:
$result = $ability->execute( $raw_input );
if ( is_wp_error( $result ) ) {
return $result;
}
return wp_json_encode(
wp_prepare_json_value_for_client(
$result,
$ability->get_output_schema()
)
);
该辅助函数会保留模式的 JSON 形状;它不会授予权限或取代执行过程。请让错误走传输层的常规错误路径,而不是将其作为成功结果准备。
更新集成
请审查依赖原始 PHP 类型或未清理输入的回调。检查自定义权限检查路径是否缺少准备步骤;在使用自定义传输层时,请在序列化边界应用 JSON 准备。
支持较早 WordPress 版本的插件必须使用与相应版本匹配的注册参数,保留现有的权限回调,并对新方法和函数的使用进行防护。如果省略权限回调而改用 required_capabilities,则需要 WordPress 7.2。
核心答案
WordPress 7.2 的 Abilities API 通过 required_capabilities 声明通用权限,并统一使用 prepare_input() 验证和清理输入。权限回调与执行回调获得处理后的值,JSON 输出遵循 output_schema。
常见问题
WordPress 7.2 中 required_capabilities 与 permission_callback 应如何使用?
若所需权限适用于每次调用,请填写非空 required_capabilities 并可省略 permission_callback;若权限取决于文章等具体输入,则保留 permission_callback。列表为空或未声明时,必须提供有效权限回调。
为什么 WordPress 7.2 的 number 模式会把整数 10 转成 10.0?
Abilities API 为确保直接 PHP 调用与 REST 请求行为一致,会按模式转换 number 类型。需要整数时应使用 integer 模式,并让 number 回调接受浮点数。
调用 check_permissions() 前为什么必须先执行 prepare_input()?
check_permissions() 不会自行准备输入。prepare_input() 会应用默认值、验证并清理原始数据;失败时应立即返回 WP_Error,避免权限回调收到未经处理的值。
{“@context”:”https://schema.org”,”@type”:”Article”,”headline”:”WordPress 7.2 更新 Abilities API,统一权限检查、输入处理与 JSON 输出”,”description”:”介绍 WordPress 7.2 Abilities API 的 required_capabilities、输入准备、模式验证与清理、权限发现筛选及 REST 行为变更。”,”inLanguage”:”zh-CN”,”author”:{“@type”:”Organization”,”name”:”SEO/GEO 编辑”},”publisher”:{“@type”:”Organization”,”name”:”SEO/GEO 编辑”},”mainEntityOfPage”:{“@type”:”WebPage”,”@id”:”https://example.com/wordpress-7-2-abilities-api”}}
WordPress 7.2 更新了 Abilities API,使权限、输入处理和 JSON 输出更加可预测。Abilities 可以声明每次调用都需要的能力。直接通过 PHP 调用和发送 REST 请求时,会根据能力的模式清理输入,而 JSON 结果会保留模式所声明的对象或数组结构。下面的示例说明了能力作者和集成开发者需要更改的内容。



发表回复