PSR-N: HTTP Middleware

middleware-meta.md

PSR-N Meta Document

1. Summary

---

The purpose of this PSR is to provide an interface that defines the formal method signature of a PSR-7 compliant HTTP middleware component.

2. Why Bother?

---

Agreeing on a formal middleware interface eliminates several problems and provides a number of benefits:

• Provides a formal standard for middleware developers to commit to.
• Eliminates duplication of identical (or near-identical) interfaces defined by various frameworks.
• Avoids minor discrepancies in method signatures.
• Enables any middleware component to run under any middleware framework.

The latter is arguably a moot point, as most PSR-7 compliant middleware already complies with the near-identical method signature expected by most major frameworks - however, compliance with a formal PSR helps middleware and framework vendors to formally certify compliance.

3. Scope

---

3.1 Goals

• Provide a Composer package with a formal interface definition.
• Comply with the already widely-adopted informal standard.

3.2 Non-Goals

• TODO

4. Approaches

---

4.1 Chosen Approach

The formal interface is based on a widely-adopted informal standard used by several existing projects.

Examples of existing middleware components:

• https://github.com/oscarotero/psr7-middlewares

Examples of existing frameworks:

• http://relayphp.com/
• http://stackphp.com/
• https://github.com/mindplay-dk/middleman

The over-arching goal and the main advantage of this approach, is hopefully short-term, widespread, easily-implemented adoption of the formal interface by projects that consume or provide middleware components.

5. People

---

5.1 Editor(s)

• Rasmus Schultz, rasmus@mindplay.dk

5.2 Sponsors

• TODO

5.3 Contributors

• TODO

6. Votes

---

• **Entrance Vote: ** http://groups.google.com...
• Acceptance Vote: http://groups.google.com...

7. Relevant Links

---

Relevant links in chronological order:

• Formative Conversation

See section 4.1 for links to relevant middleware components and frameworks.

8. Errata

---

None.

middleware.md

HTTP Middleware

This document describes a common standard for HTTP middleware components using PSR-7 compliant HTTP messages.

HTTP middleware has been an important concept on other web development platforms for a good number of years, and since the inception of PSR-7 has been growing increasingly popular in the PHP world.

An informal (de-facto) standard for the signature of middleware components is already widely in use, and this PSR serves to provide a formal definition in the form of a common standard interface for middleware components.

The interface described in this document is an abstraction of an individual middleware component.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. Specification

An HTTP middleware component is an individual component participating, together with other middleware components, in the processing of an incoming HTTP Request and the creation of a resulting HTTP Response, e.g. Psr\Http\Message\RequestInterface and Psr\Http\Message\ResponseInterface respectively, as defined by PSR-7.

Middleware components MUST implement this interface.

Middleware consumers (e.g. frameworks and middleware stacks) MUST type-hint any method accepting middleware component(s) as arguments formally as callable, and informally as Psr\Middleware\MiddlewareInterface, e.g. using php-doc tags - for example:

/**
 * @param \Psr\Middleware\MiddlewareInterface $middleware
 */
public function push(callable $middleware)
{
    // ...
}

TODO

2. Interfaces

TODO

MiddlewareDelegateInterface.php

<?php

namespace Psr\Middleware;

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

/**
 * This interface defines the formal method common to HTTP Middleware components.
 */
interface MiddlewareDelegateInterface
{
    /**
     * @param RequestInterface  $request  the request
     * @param ResponseInterface $response the response
     * 
     * @return ResponseInterface
     */
    public function __invoke(RequestInterface $request, ResponseInterface $response)
}

ServerMiddlewareInterface.php

<?php

namespace Psr\Middleware;

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

/**
 * This interface defines the formal method common to HTTP Middleware components.
 */
interface ServerMiddlewareInterface
{
    /**
     * @param ServerRequestInterface               $request  the request
     * @param ResponseInterface                    $response the response
     * @param callable|MiddlewareDelegateInterface $next     delegate function to dispatch the next middleware component
     *
     * @return ResponseInterface
     */
    public function __invoke(RequestInterface $request, ResponseInterface $response, callable $next);
}