README

基于 PSR-7、PSR-14 和 PSR-15 最佳实践标准的超轻量级 REST API 服务器。

REST API 服务器不是一个独立的程序，而是你的 PSR-15 服务器请求处理器和中间件的 宿主。你可以将服务器作为你自己的应用程序中的一个模块使用，或者扩展它来创建自定义 API 服务器。

如何使用

创建新的 REST API 服务器实例

use Peroks\ApiServer\Server;
$server = new Server();

处理服务器请求

REST API 服务器本身只提供一个方法：它接收一个 PSR-7 服务器请求 并返回一个 PSR-7 响应。

use Peroks\ApiServer\Server;
use GuzzleHttp\Psr7\ServerRequest;

$server   = new Server();
$request  = new ServerRequest( 'POST', '/test', [], 'Hello World' );
$response = $server->handle( $request );

此服务器本身不处理任何请求，它只是将请求分配给已注册的请求处理器和中间件，并返回它们的响应。

注册 API 端点

为了注册一个 API 端点，你首先需要创建自己的 PSR-15 服务器请求处理器。你可以在这里找到一个用于测试目的的非常简单的实现示例： TestHandler.php。

使用 Endpoint 包装器来设置端点的 路由（服务器路径）和 HTTP 方法，以及你的 PSR-15 服务器请求 处理器。

route 和 action 属性被添加到请求中作为保留请求 属性： __route 和 __action。处理器可以使用这些属性将服务器请求映射到函数。

use Peroks\ApiServer\Server;
use Peroks\ApiServer\Endpoint;

$server  = new Server();
$handler = new YourRequestHandler();

$server->registry->addEndpoint( new Endpoint( [
    'route'   => '/test',           // Endpoint route (server path)
    'method'  => Endpoint::POST,    // Endpoint http method
    'action'  => 'echo',            // Endpoint action
    'handler' => $handler,          // PSR-15 server request handler
] ) );

你可以检查是否已注册端点，获取它并删除它。

if( $server->registry->hasEndpoint( '/test', 'POST' ) ) {
    $endpoint = $server->registry->getEndpoint( '/test', 'POST' );
    $endpoint = $server->registry->removeEndpoint( '/test', 'POST' );
}

你还可以获取所有已注册端点的数组。

$array = $server->registry->getEndpoints();

注册服务器中间件

服务器中间件用于修改或监控服务器请求或响应。典型的示例是用于 授权、日志记录 和 缓存 的中间件。

为了注册服务器中间件，你首先需要创建自己的 PSR-15 服务器中间件。你可以在这里找到一个用于测试目的的非常简单的实现示例： TestMiddleware.php。

使用 Middleware 包装器来提供中间件的 id 和你的 PSR-15 服务器中间件 实例（两者都是必需的）。id 可以是任何字符串，用于标识已注册的中间件条目。在许多情况下，中间件类名是一个不错的选择。

use Peroks\ApiServer\Server;
use Peroks\ApiServer\Middleware;

$server     = new Server();
$middleware = new YourMiddleware();

$server->registry->addMiddleware( new Middleware( [
    'id'       => YourMiddleware::class,
    'name'     => 'Middleware instance for testing',
    'priority' => 20, // default is 50.
    'instance' => $middleware,
] ) );

如果你稍后想要检查中间件是否已注册，获取或删除中间件，你需要这个已注册的 id，例如

if( $server->registry->hasMiddleware( YourMiddleware::class ) ) {
    $middleware = $server->registry->getMiddleware( YourMiddleware::class );
    $middleware = $server->registry->removeMiddleware( YourMiddleware::class );
}

你还可以获取所有已注册中间件条目的数组。

$array = $server->registry->getMiddlewareEntries();

注册事件监听器

除了中间件，你还可以注册 事件监听器 来挂钩执行流程并修改数据。

使用监听器包装器来为监听器提供id、type和callback函数（所有都是必需的）。id可以是任何标识已注册事件监听器的字符串。

在这个示例中，我们在处理请求之前将授权头添加到所有请求中，请求可能会被中间件或请求处理器处理和拒绝。

use Peroks\ApiServer\Server;
use Peroks\ApiServer\Listener;
use Peroks\ApiServer\Event;

$server   = new Server();
$callback = function( Event $event ): void {
    $event->data->request = $event->data->request->withHeader( 'authorization', 'yes' );
};

$server->registry->addListener( new Listener( [
    'id'       => 'set-authorization',
    'type'     => 'server/request',
    'callback' => $callback,
] ) );

如果您以后想检查事件监听器是否已注册，或者获取或删除监听器，则需要该已注册的id，例如

if( $server->registry->hasListener( 'set-authorization' ) ) {
    $listener = $server->registry->getListener( 'set-authorization' );
    $listener = $server->registry->removeListener( 'set-authorization' );
}

您还可以获取所有注册的事件监听器的数组。

$array = $server->registry->getListeners();