云策 WordPress 开发者社区

钩子文档

rest_request_before_callbacks

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

概述

rest_request_before_callbacks 是一个 WordPress REST API 钩子，用于在请求匹配到注册路由后、执行回调前过滤响应。它允许插件进行额外的验证或修改，但不会在认证失败或路由不匹配时触发。

关键要点

  • 钩子类型：过滤器（filter），用于修改 REST API 响应。
  • 触发时机：请求初始化并匹配到注册路由后，但在执行回调函数之前。
  • 参数：$response（响应对象，如 WP_REST_Response 或 WP_Error）、$handler（路由处理器数组）、$request（WP_REST_Request 对象）。
  • 限制：不会在认证失败或路由不匹配的请求中调用。
  • 用途：常用于权限检查、请求验证或响应预处理。

代码示例

function wpdocs_authorize_api_requests( $response, $handler, WP_REST_Request $request ) {
    $routes = array(
        '/wp/v2/posts',
        '/wp/v2/pages',
    );

    if ( ! $request->get_header( 'authorization' ) ) {
        return new WP_Error( 'authorization', 'Unauthorized access.', array( 'status' => 401 ) );
    }

    if ( !in_array( 'administrator', wp_get_current_user()->roles ) || ! in_array( $request->get_route(), $routes ) ) {
        return new WP_Error( 'forbidden', 'Access forbidden.', array( 'status' => 403 ) );
    }

    return $response;
}
add_filter( 'rest_request_before_callbacks', 'wpdocs_authorize_api_requests', 10, 3 );

注意事项

  • 确保在函数中正确处理 $response 参数，避免破坏原始响应逻辑。
  • 注意钩子不会在认证失败时触发，因此需结合其他钩子进行完整安全控制。
  • 代码示例中的条件逻辑需根据实际需求调整，例如角色检查和路由匹配。
📄 原文内容

Filters the response before executing any REST API callbacks.

Description

Allows plugins to perform additional validation after a request is initialized and matched to a registered route, but before it is executed.

Note that this filter will not be called for requests that fail to authenticate or match to a registered route.

Parameters

$responseWP_REST_Response|WP_HTTP_Response|WP_Error|mixed
Result to send to the client.
Usually a WP_REST_Response or WP_Error.
$handlerarray
Route handler used for the request.
$requestWP_REST_Request
Request used to generate the response.

Source

$response = apply_filters( 'rest_request_before_callbacks', $response, $handler, $request );

View all references View on Trac View on GitHub

Used by Description
WP_REST_Server::respond_to_request()wp-includes/rest-api/class-wp-rest-server.php

Dispatches the request to the callback handler.

Changelog

Version Description
4.7.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    pixelandgrain


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Here is the code I have used to authenticate each request and limit route access using allowed routes set in an array

    /**
 * Callback function to authorize each api requests
 * 
 * @see WP_REST_Request
 * 
 * @param                  $response
 * @param                  $handler
 * @param WP_REST_Request $request
 *
 * @return mixed|WP_Error
 */
function wpdocs_authorize_api_requests( $response, $handler, WP_REST_Request $request ) {
    // allowed routes
    $routes = array(
        '/wp/v2/posts',
        '/wp/v2/pages',
    );

    // check if authorization header is set
    if ( ! $request->get_header( 'authorization' ) ) {
        return new WP_Error( 'authorization', 'Unauthorized access.', array( 'status' => 401 ) );
    }

    // check for certain role and allowed route
    if ( !in_array( 'administrator', wp_get_current_user()->roles || ! in_array( $request->get_route(), $routes ) ) {
        return new WP_Error( 'forbidden', 'Access forbidden.', array( 'status' => 403 ) );
    }

    return $response;

}
// authorize each requests
add_filter( 'rest_request_before_callbacks', 'wpdocs_authorize_api_requests', 10, 3 );