README

使用完整的JSON Schema验证器来验证WP REST API请求。

WordPress自带一个验证器，rest_validate_request_arg()，支持JSON Schema规范的有限子集。此库允许在编写端点模式时使用完整的JSON Schema规范，配置简单。

此库依赖于justinrainbow/json-schema包进行实际的模式验证。这仅仅是两者之间的桥梁。

要求

PHP 5.3+
WordPress 4.5+

安装

composer require ironbound/wp-rest-api-schema-validator

使用

使用您的REST路由namespace和一个本地化字符串数组初始化一个Middleware实例。此中间件应在触发rest_api_init钩子之前初始化。例如，plugins_loaded。

此外，模式必须具有顶层上的title属性。此标题应在版本化命名空间内是唯一的。

$middleware = new \IronBound\WP_REST_API\SchemaValidator\Middleware( 'namespace/v1', [
  'methodParamDescription' => __( 'HTTP method to get the schema for. If not provided, will use the base schema.', 'text-domain' ),
  'schemaNotFound'         => __( 'Schema not found.', 'text-domain' ),
] );
$middleware->initialize();

就这样！

高级

GET和DELETE请求

与GET或DELETE请求一起传递的查询参数将根据注册路由时传递的args选项进行验证。

技术细节

在rest_api_init#100上，中间件将遍历提供的命名空间中注册的路由。默认的WordPress核心验证和清理函数将被禁用。

模式验证将在rest_dispatch_request#10钩子上执行。

将返回匹配WP_REST_Request格式的WP_Error对象。主要是错误代码为rest_missing_callback_param或rest_invalid_param，响应状态代码为400，以及详细的错误信息在data.params中。

对于缺少的参数，data.params将包含缺少的参数名称列表。对于无效的参数，一个参数名称到特定验证错误消息的映射。

过程式验证

在绝大多数情况下，应使用JSON Schema定义配置验证。但是，这并不总是情况。例如，验证用户名是否已被占用需要调用数据库，而这些调用在模式定义中是不可能复制的。在这些情况下，仍然可以提供validate_callback并在JSON Schema验证之前执行。

return [
    '$schema'    => 'https://json-schema.fullstack.org.cn/schema#',
    'title'      => 'users',
    'type'       => 'object',
    'properties' => [
        'username' => [
            'description' => __( 'Login name for the user.', 'text-domain' ),
            'type'        => 'string',
            'context'     => [ 'view', 'edit', 'embed' ],
            'arg_options' => [
                'validate_callback' => function( $value ) {
                    return ! username_exists( $value );
                },
            ],   
        ],
    ],
];

可变模式

在大多数情况下，模式文档应与给定端点上的所有HTTP方法相同。在罕见的情况下，如果提供了单独的模式文档，则可以为该HTTP方法提供路由参数的schema选项。单独的模式文档的title必须与基本模式相同。

register_rest_route( 'namespace/v1', 'route', [
    [
        'methods'  => 'GET',
        'callback' => [ $this, 'get_item' ],
        'args'     => $this->get_endpoint_args_for_item_schema( 'GET' ),
    ],
    [
        'methods'  => 'POST',
        'callback' => array( $this, 'create_item' ),
         // See WP_REST_Controller::get_endpoint_args_for_item_schema() for reference.
        'args'     => $this->get_endpoint_args_for_post_schema(),
        'schema'   => [ $this, 'get_public_item_post_schema' ],
    ],
    [
        'methods'  => 'PUT',
        'callback' => [ $this, 'update_item' ],
        'args'     => $this->get_endpoint_args_for_item_schema( 'PUT' ),
    ],
    'schema' => [ $this, 'get_public_item_schema' ],
] );

重用模式

JSON Schema提供了一个利用引用模式文档进行验证的机制。此包允许您通过使用Middleware::get_url_for_schema( $title )方法实现此功能。

例如，此模式将根据标题为card的模式文档验证card属性。

[
    '$schema'    => 'https://json-schema.fullstack.org.cn/schema#',
    'title'      => 'transaction',
    'type'       => 'object',
    'properties' => [
        'card' => [
            '$ref' => $middleware->get_url_for_schema( 'card' )   
        ],
    ],
];

但是，如果没有/cards路由？或者需要更通用的模式？在这种情况下，可以使用共享模式。

$middleware->add_shared_schema( [
    '$schema'    => 'https://json-schema.fullstack.org.cn/schema#',
    'title'      => 'card',
    'type'       => 'object',
    'properties' => [
        'card_number' => [
            'type'    => 'string',
            'pattern' => '^[0-9]{11,19}$',
        ],
        'exp_year'  => [ 'type' => 'integer' ],
        'exp_month' => [ 
            'type' => 'integer',
            'minimum' => 1,
            'maximum' => 12,
         ],
    ],
] );

模式路由

在所有路由都已注册后，中间件将注册其自己的路由。

namespace/v1/schemas/(?P<title>[\S+])

此路由返回给定标题的纯架构文档。要获取给定HTTP方法的架构，请将所需的 uppercase HTTP 方法传递给 method 查询参数。

GET https://example.org/wp-json/namespace/v1/schemas/transaction?method=POST

ironbound / wp-rest-api-schema-validator

维护者

详情