README

利用swagger文档来处理路由的PHP微框架。

安装

建议您使用Composer来安装talus。

$ composer require avalanche-development/talus

talus需要PHP 5.6或更高版本。

使用

这个微框架使用swagger-router-middleware来解析和了解提供的swagger文档。它还使用peel http异常和crash-pad来标准化错误响应。要实例化talus，您需要以数组的形式提供swagger文档。

$talus = new AvalancheDevelopment\Talus\Talus([..swagger..]);

解析的swagger信息可通过请求上的swagger属性访问。在您的应用程序中，您可以像这样访问这些信息。

function ($request, $response) {
  $someParameter = $request->getAttribute('swagger')['params']['someParameter'];
}

控制器

控制器通过swagger规范中的operationId附加到路由上。每个操作都应该有一个唯一的operationId，这将通知talus要调用哪个控制器。控制器必须是可调用的，并具有function ($request, $response)接口。

$talus->addController('getThing', function ($request, $response) {
  // get that thing
});

$talus->addController('getComplexThing', function ($request, $response) use ($db) {
  return (new Controller($db))->getComplexThing($request, $response);
});

中间件

中间件可以添加到堆栈中，并按添加的顺序执行。需要注意的是，首先执行的中件将是swagger-router-middleware（它将提供包含许多好东西的swagger属性），最后执行的中件将是提供的控制器可调用项。

$talus->addMiddleware(function ($request, $response, $next) {
  // do something
  return $next($request, $response);
});

错误处理

在堆栈中抛出的任何异常，包括路由错误和请求体解析失败，将被捕获并传递到错误处理器。其中一些异常实现了HttpErrorInterface peel，这使得它们更容易处理。默认的错误处理器crash-pad将处理这些并返回标准响应，尽管您可以完全自定义。

$talus->setErrorHandler(function ($request, $response, $exception) {
  // do something with that exception
  return $response;
});

建议您在控制器内部抛出异常，特别是peel异常，而不是尝试自己处理错误。这将保持标准。

执行

一旦设置好控制器，添加了中间件并自定义了错误处理器，剩下的就是运行应用程序。这将遍历中间件堆栈并执行适当的控制器，然后遍历中间件并输出提供的响应对象。如果在过程中出现任何问题，错误处理器应捕获它们并返回相关的错误消息。

$talus = new AvalancheDevelopment\Talus\Talus([..swagger..]);

$talus->addController(..callback..);
$talus->addMiddleware(..callback..);

$talus->run();

文档路由

这是swagger-router-middleware的一个特性。如果检测到标准的'文档路由'（路径为/api-docs），则立即跳过堆栈的其余部分，并将swagger规范作为json返回。json_encode错误将抛出一个标准的\Exception。

测试

要执行测试套件，您需要phpunit（以及安装带有开发依赖项的包）。

$ phpunit

许可证

talus遵循MIT许可证。有关更多信息，请参阅许可证文件。