README

PHP microframework that leverages swagger documentation to handle routing.

Installation

It's recommended that you use Composer to install talus.

$ composer require avalanche-development/talus

talus requires PHP 5.6 or newer.

Usage

This microframework uses swagger-router-middleware to parse and understand a provided swagger documentation. It also uses peel http exceptions and crash-pad to standardize error responses. To instantiate talus, you'll need to provide the swagger document in the form of an array.

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

The parsed swagger information is available via the swagger attribute on the request. In your application, you can access this information like so.

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

Controllers

Controllers are attached to routes by the operationId in the swagger spec. Each operation should have a unique operationId, and this will inform talus which controller to invoke. Controllers must be callable and have a function ($request, $response) interface.

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

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

Middleware

Middleware can be added onto the stack and will be executed in the order they are added. As a note, the first executed piece of middleware will always be swagger-router-middleware (which will give you a swagger attribute with all sorts of goodies in it) and the last executed piece will always be the provided controller callable.

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

Error Handling

Any exceptions thrown during the stack, which includes routing errors and request body parsing failures, will be caught and passed through to the error handler. Some of these exceptions implement HttpErrorInterface peel, making them easier to deal with. The default error handler crash-pad provided will handle this and return a standard response, though you can totally roll your own.

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

It is recommended that you throw exceptions, especially peel ones, within your controllers instead of trying to handle the error yourself. This will keep things standardized.

Execution

Once the controllers are set, middleware is stacked on, and error handler is customized, all that's left to do is to run the app. This will walk through the middleware stack and execute the appropriate controller, then walk back through middleware and output the provided response object. If there are any problems along the way the error handler should capture them and return a relevant error message.

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

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

$talus->run();

Documentation Route

This is a feature of swagger-router-middleware. If the standard 'documentation route' is detected (path of /api-docs), the rest of the stack is immediately skipped and the swagger spec is returned as json. An error with json_encode will throw a standard \Exception.

Tests

To execute the test suite, you'll need phpunit (and to install package with dev dependencies).

$ phpunit

License

talus is licensed under the MIT license. See License File for more information.

avalanche-development / talus

Maintainers

Details