README

Phapi relies heavily on middleware. Almost everything is a middleware: routing, content negotiation and many other things.

Why middleware?

The benefits are many. Middleware are easy to replace and from a performance perspective they can, if implemented right, bypass a lot of code that doesn't need to run in specific circumstances, for example, if a client hits their rate limit there is no point in executing routing, dispatching etc.

Installation

The package is installed by default by the Phapi framework. Installing the package to use is separately can be done by using composer:

$ composer require phapi/pipeline:1.*

Usage

Attaching a new middleware to the pipeline are done by using the pipe() method.

<?php
$pipeline = new Phapi\Middleware\Pipeline();
$pipeline->pipe(new Middleware\Cors());

Please note that middleware's will be called in the order they are attached.

A middleware CAN implement the Middleware Interface, but MUST be callable. All middleware WILL be called with three parameters: Request, Response and Next. A middleware should invoke the $next variable and pass the $request, $response and $next parameters. A middleware must also return a response.

Once the queue is empty the resulted response instance will be returned.

Error handling

Implementing the ErrorMiddleware interface enables the pipeline to be able to handle errors. The middleware must take care of the error handling and call the prepareErrorQueue() method. This will trigger a reset in the pipeline and only the middleware added before (usually serializer middleware and a middleware sending the response to the client) the ErrorMiddleware will be called.

Create your own middleware class

Middleware requires a request and a response and a callback ($next) that is called if the middleware allows further middleware to process the request. If a middleware doesn't need or desire to allow further processing it should not call the callback ($next) and should instead return a response. Note that $next can be null.

The main task of a middleware is to process an incoming request and/or the response. The middleware must accept a request and a response (PSR-7 compatible) instance and do something with them.

The middleware must pass a request and a response to the ($next) callback and finally either return the response from the ($next) callback or by modifying the response before returning it.

Examples:

<?php
  public function __invoke(
    Request $request,
    Response $response,
    callable $next)
  {
      // Do something ...

      return $next($request, $response, $next);
  }

OR

<?php
  public function __invoke(
    Request $request,
    Response $response,
    callable $next)
  {
      // Do something ...

      $response = $next($request, $response, $next);

      // Modify response ...

      return $response;
  }

If the middleware should break the pipeline, example: the client hit the rate limit, it should return a response instead of invoking $next.

Example:

<?php
  public function __invoke(
    Request $request,
    Response $response,
    callable $next)
  {
      if ($this->tooManyRequests()) {
        // Set appropriate headers and body

        // Return response
        return $response;
      }

      return $next($request, $response, $next);
  }

Dependency Injection Container

If you implement a method named setContainer() the pipeline will call that method and provide the Dependency Injector Container that can be used in the __invoke() method.

Example:

<?php
  public function setContainer($container)
  {
    $this->container = $container;
  }

Complete example

Here is a complete example of how a middleware should look. Use this example as a starting point when you wan't to write your own middleware.

<?php

namespace Phapi\Middleware\Example;

use Phapi\Contract\Di\Container;
use Phapi\Contract\Middleware\Middleware;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

/**
 * Eample middleware
 *
 * @category Phapi
 * @package  Phapi\Middleware\Example
 * @author   Peter Ahinko <peter@ahinko.se>
 * @license  MIT (http://opensource.org/licenses/MIT)
 * @link     https://github.com/phapi/middleware-example
 */
class Example implements Middleware
{

    /**
     * Dependency injection container
     *
     * @var Container
     */
    private $container;

    /**
     * Set dependency injection container
     *
     * @param Container $container
     */
    public function setContainer(Container $container)
    {
        $this->container = $container;
    }

    /**
     * Invoking the middleware
     *
     * @param ServerRequestInterface $request
     * @param ResponseInterface $response
     * @param callable $next
     * @return ResponseInterface $response
     */
    public function __invoke(ServerRequestInterface $request, ResponseInterface $response, callable $next = null)
    {
        // Do something ...

        // Call next middleware
        $response = $next($request, $response, $next);

        // Do something with the response ...

        // Return the response
        return $response;
    }
}

License

Phapi Middleware Pipeline is licensed under the MIT License - see the license.md file for details

Contribute

Contribution, bug fixes etc are always welcome.