README

Perique - Route

用于以更简单的方式注册 WP Rest 路由的库。

为什么？

注册 WP Rest 路由可能非常简单，也可能因为数组格式而令人沮丧。Perique Route 库允许以更简单的方式注册单个路由和组。

设置

要安装，您可以使用 composer

$ composer require pinkcrab/perique-route

您需要在启动时将 Registration_Middleware 添加到 App 中。我们提供了一个静态方法来处理依赖注入。

// @file: plugin.php

$app_factory->module( \PinkCrab\Route\Module\Route::class );

一旦您将路由中间件添加到注册过程，所有扩展 Route_Controller 的类都将被处理，并注册所有定义的路由。

要创建一个路由控制器，只需扩展 Route_Controller 并返回所有路由和组的数组。控制器使用 DI 容器构建，因此可以传递所有依赖项。

class Some_Route extends Route_Controller {

    // @required
    protected $namespace = 'acme/v1';

    // @optional, access to constructor, so allows for full DI.
    protected $some_service;
    protected function __construct(Service $service){
        $this->some_service = $service;
    }

    // @required
    protected function define_routes( Route_Factory $factory): array {
        return [
            // Factory allows for get,post,delete,patch,put requests.
            $factory->get('/users', [$this->some_service, 'list_users' ]),
            $factory->post('/users', [$this->some_service, 'new_user' ]),
            
            // Create your groups using the group builder.
            $factory->group_builder('/users/{id}', function( Route_Group $group) : Route_Group {
                // Define the GET method.
                $group->get([$this->some_service, 'show_user'])
                    ->argument( // Define the argument proprties as per WP API
                        Integer_Type::on('id')
                            ->validate('is_numeric')
                            ->sanitization('absint')
                            ->required()
                    );

                // Define the DELETE method.
                $group->delete([$this->some_service, 'delete_user'])
                    ->authentication('some_extra_check_for_delete');

                // Define group wide authentication (applied to both routes).
                $group->authentication([$this->some_service, 'check_api_key_in_header']);

                return $group;
            })
        ];
    }

}

一旦您设置了 Route_Controller，只需将类传递给 registration 数组即可，它将与 Perique 一起加载。

//file: config/registration.php
return [
    ...other classes
    Some_Route::class,
];

路由

每个路由都必须作为 Route Model 的一部分进行定义，这些可以手动创建或使用提供的 Route_Factory（这是 Route_Controller 操作的方式。）

路由模型

路由模型有 4 个必须定义的属性，即 $method、$route、$callback 和 $namespace。路由和方法通过构造函数传递，但命名空间必须手动设置。

根据 WP Api 标准，路由中的所有参数都必须定义，这通过 Arguments 对象处理，详细说明如下。

所有属性都定义为 protected，应通过提供的方法进行处理。

$route = new Route('POST', 'route/path');
$route->namespace('the-thing/v1');
$route->callback(function( WP_REST_Request $request ) {
    // Do the things
});

还可以定义一个 authentication 回调。

$route->authentication(function(WP_REST_Request $request): bool{
    return something_check($request);
});

路由文档

• Route::namespace()
• Route::authentication()
• Route::callback()
• Route::argument()
• Route::with_method()

Route_Group

与单个路由模型类似，Route_Group 允许以类似的过程创建具有公共端点路由和某些功能的关联路由。同样，最好使用提供的 Route_Factory，但以下将说明如何手动创建 Route_Group（核心方法的使用方式相同）。

$group = new Route_Group('my_endpoints/v2','route/');
$group->authentication('shared_group_auth')
$group->get('some_callable')
    ->authentication('additional_auth_for_get_only');
$group->post('some_other_callable');

然后创建一个组，其中所有分配的路由都将使用上述命名空间和路由创建。

阅读组文档

设置器

• Route_Group::post()
• Route_Group::get()
• Route_Group::patch()
• Route_Group::put()
• Route_Group::delete()
• Route_Group::authentication()
• Route_Group::argument()

Route_Factory

由于大多数时间您都会创建具有固定命名空间的端点，因此有一个工厂可以用于为创建的每个路由填充此命名空间，同时提供一个干净、流畅的 API，可以用于在数组中创建路由并返回值。

$factory = new Route_Factory('my_endpoints/v2');
$get = $factory->get('/endpoint', 'some_callable');
$post = $factory->get('/endpoint_2', 'some_other_callable');

上述两个端点都将使用 my_endpoints/v2 命名空间创建。

方法助手

在 Route_Factory 上有一系列助手方法，可以轻松地将方法添加到现有命名空间。

$route = $factory->get('the/route/{name}', [$this, 'some_callback_for_get']);
$route = $factory->post('the/route/{name}', [$this, 'some_callback_for_post']);
$route = $factory->put('the/route/{name}', [$this, 'some_callback_for_put']);
$route = $factory->patch('the/route/{name}', [$this, 'some_callback_for_patch']);
$route = $factory->delete('the/route/{name}', [$this, 'some_callback_for_delete']);

甚至可以在同一路由周围创建一个组。

$group = $factory->group_builder('the/route/{name}', function(Route_Group $group){
    $group->get([$this, 'some_callback_for_get']);
    $group->post([$this, 'some_callback_for_post']);
    $group->delete([$this, 'some_callback_for_delete']);
    $group->put([$this, 'some_callback_for_put']);
    $group->path([$this, 'some_callback_for_path']);
});

路由控制器

定义路由最简单的方式是扩展 Route_Controller 抽象类。这可以通过一个预定义的 protected ?string $namespace; 属性和一个定义路由/组的函数来实现，该函数为 abstract protected function define_routes( Route_Factory $factory): array

请参见上面的示例

手动创建路由

如果您不想使用上面的路由控制器，则需要创建一个 Route_Manager 类的实例，并将您的路由或组添加到管理器中，然后在调用 rest_init 钩子之前执行管理器。

$manager = new Route_Manager(
    new WP_Rest_Registrar(),
    new Hook_Loader()
);

// Add routes and groups
$manager->from_route(new Route(...));
$manager->from_group(new Route_Group(...));

// Dispatch
$manager->execute();

当调用 execute() 时，它将创建 rest_init 钩子，因此无需执行 add_action(...)

旧版本

• 对于 Perique 1.4.* 使用 Route 1.0.*
• 对于 Perique 1.0 - 1.3.* 使用 Route 0.1.*

变更日志

• 2.0.1 更新依赖项和扩展测试以覆盖 WP6.3 & WP6.4
• 2.0.0 支持 Perique 2.0
• 1.0.1 更新说明/文档
• 1.0.0 更新 WP6.1 的开发测试依赖项，移除 Utils 并用 FunctionConstructors 替换，并更新文档以使用 construct_registration_middleware() 而不是提供构建的 Middleware 实例。
• 0.1.2 更新 WP6.0 的开发测试依赖项
• 0.1.1 升级到 PinkCrab Collection Dependency 的 0.2.0 版本
• 0.1.0 初始版本