README

Rapid是基于Express.js启发的PSR-7/中间件调度器。Rapid的唯一外部依赖是PSR-7 Psr\HttpMessage接口。Rapid需要PHP 7.0或更高版本。

安装

$ composer require offers/rapid

创建您的应用程序

$application = new Rapid\Application();
// add middlewares here
$application->run();

定义中间件

Rapid接受几个值来表示中间件。Rapid期望将中间件作为参数的任何地方，都可以使用以下任何一种方法

传递实例

如果传递实例，您的实例应实现Rapid\MiddlewareInterface。此方法在需要为依赖注入自定义实例化实例时很有用。

$application->use(new ExampleMiddleware());

传递类名

如果中间件不需要任何自定义实例化，则可以传递类名。除非系统确实需要使用该给定的中间件，否则您的类将不会被实例化。

$application->use(ExampleMiddleware::class);

传递闭包

具有与Rapid\MiddlewareInterface兼容签名的闭包也可以使用。类型提示参数是可选的，但建议使用。

$application->use(function(ServerRequestInterface $request, ResponseInterface $response, callable $next) {
    
});

使用中间件工厂

Rapid\Application可选地接受一个callable，用于在指定类名时生成中间件。此调用可以负责按您的需要进行连接和依赖注入。工厂应是一个接受一个参数（一个类名）并返回适当连接的中间件的callable。提供了一个方便的接口Radpid\MiddlewareFactoryInterface，但不是必需的。

$application->setMiddlewareFactory($factory);

组合和路由中间件

中间件按在您的应用程序引导中定义的顺序从上到下评估。中间件可以应用于每个请求，或使用传统的路由方法应用于\Psr\HttpMessage\ServerRequestInterface的实例。所有中间件都将针对每个请求进行检查，并且允许和鼓励多个匹配。

将中间件应用于每个请求

$application = new Rapid\Application();
$application->use(new ExampleMiddleware());

基于方法和简单路径匹配中间件

$application->get("/test", TestMiddleware::class);

基于任何方法和简单路径匹配中间件

$application->all("/test", TestMiddleware::class);

基于任何方法和简单路径匹配中间件

$application->all("/test", TestMiddleware::class);

将一组中间件应用于给定的路径

$application->get("/test", [TestMiddleware::class, ExampleMiddleware::class]);

将中间件应用于同一路由上的多个方法

$application->route(["POST", "PUT"], "/test", TestMiddleware::class);

将不同的中间件应用于同一路由上的不同方法

$application->get("/test", GetMiddleware::class);
$application->post("/test", PostMiddleware::class);

路由

Rapid包含一个内置的路由器/ URL匹配器。

以下列方式注明的特殊操作符之外的以/开头的URL被视为与请求路径的精确字符串匹配。在下面的示例中，如果请求URI的路径正好是/test，则将调用GetMiddleware。

$application->get("/test", GetMiddleware::class);

以下列方式注明的特殊操作符之外的以/开头的URL与系统生成的正则表达式匹配。带有{}的路径段被视为变量，这些段值的值将设置为请求对象的属性。在下面的示例中，请求路径为/test/myslug会导致请求属性slug被设置为myslug。

$application->get("/test/{slug}", GetMiddleware::class);

在任何路径前缀的末尾，可以添加一个特殊标记 {?}，将路径匹配的剩余部分视为 Rails 风格的键值路由。在以下示例中，请求路径 /test/param1/value1/param2/value2 将导致请求属性 param1 和 param2 分别被设置为 value1 和 value2。 注意：此路由匹配0个或多个选项，因此它也将匹配 /test

$application->get("/test{?}", GetMiddleware::class);

被反引号包围的路径规范被视为正则表达式，并按原样传递给 preg_match()。如果正则表达式匹配，则将 $matches 数组设置为请求属性。

$application->get("`/test.*?`", GetMiddleware::class);

使用自定义路由匹配器

Rapid 支持使用自定义的 callable 进行路由匹配。这在需要查询数据库以确定路由是否匹配的情况下可能很有用。该可调用函数应接受一个参数，一个 \Psr\HttpMessage\RequestInterface，并返回 false（不匹配）或一个 \Psr\HttpMessage\RequestInterface，这可能就是它传入的实例，或者一个它已装饰了必要属性的修改后的实例。提供了一个方便的接口 Rapid\RouteMatcherInterface，但不是必需的。

$application->get(function($request) {
    if ($request->getUri()->getPath = "/complex-logic") {
        return $request;    
    }
    return false;    
}, DataBackedMiddleware::class);

使用中间件管道

Rapid\Application 对象上的方便方法实际上是底层容器对象 Rapid\MiddlewarePipe 的代理。在引导时，可以使用中间件管道直接获得更多的灵活性和可重用性。

使用单个中间件创建一个新的中间件管道并使用它

$pipe = new \Radid\MiddlewarePipe(RunAlwaysMiddleware::class);
$application->use($pipe);

使用多个中间件创建一个新的中间件管道

$pipe = new \Radid\MiddlewarePipe([RunAlwaysMiddleware::class, AnotherMiddleware::class]);
$application->use($pipe);

将中间件添加到现有的管道中

$pipe = new \Radid\MiddlewarePipe();
$myMiddleware = new MyMiddleware();
$pipe->pipe($myMiddleware);

中间件管道也完全支持路由。管道方法也将接受一个闭包。在闭包内部，您可以使用与应用程序对象上的方便方法相同的语法。

$pipe = new \Radid\MiddlewarePipe();
$pipe->pipe(function() {
    $this->use(MiddlewareOne::class);
    $this->get('/prefix', PrefixMiddleware::class);
});

使用管道进行组织的一个更具体的例子。中间件管道可以替换任何使用中间件的地方。

$publicPipe = new \Radid\MiddlewarePipe();
$publicPipe->pipe(function() {
   $this->get("/", HomepageMiddleware::class);
   $this->get("/login", LoginMiddleware::class);
});
$application->use($publicPipe);

$privateDirectoryPipe = (new Rapid\MiddlewarePipe())->pipe(function() {
    $this->get("/user", (new MiddlewarePipe)->pipe(function() {
        $this->use(AuthMiddleware::class);
        $this->get("/user/dashboard", DashBoardMiddleware::class);
        $this->get("/user/settings", SettingsMiddleware::class);    
    }));
});
$application->use($privateDirectoryPipe);

处理错误

Rapid 错误处理器也被定义为中间件。错误中间件具有略微不同的签名，并在其自己的 Rapid\Middleware\ErrorMiddlewareInterface 中描述。错误处理中间件的第一个参数是一个 Throwable。

Rapid 在其调度周期中捕获 Throwable，因此 PHP 7.x 的 Error 抛出也会被捕获，并由这些中间件处理。在调用第一个错误中间件之前，Rapid 将将 Throwable 作为属性设置在 $request 上，并根据适用情况将 $response 状态代码更改为 404 或 500。Rapid 包括2个用于路由问题的特殊 Exceptions： Rapid\Exception\MethodNotAllowedException 和 Rapid\Exception\NoRouteMatchException。

$application->use(ErrorMiddleware::class);

扩展基本应用程序

Rapid\Application 本身是一个非常简单的类。它提供了一个空的 init() 方法，该方法将用于引导目的。默认构造函数故意不带参数，假设它很可能会被覆盖。假设用户会想扩展基本应用程序类，并在 init() 方法中实现所有中间件引导，并使用依赖注入容器等参数覆盖构造函数，以便在 init() 中使用。