Merge pull request #24 from krakphp/23-wrap-middleware

Wrap Middleware #23

Closes #23

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Added
+
+- wrap middleware to wrap PSR-7 style middleware #23
+- Middleware documentation
+
 ## 0.3.1 - 2017-05-02
 
 ### Added

README.md

@@ -113,6 +113,61 @@ $server->serve(function($req) {
 });
 ```
 
+### Middleware
+
+Here are several useful middleware to use within your own applications. Each middleware takes two arguments: A PSR-7 Server Request, and an HttpLink. If you want more documentation on how the Link's work, checkout the Krak\\Mw library.
+
+```php
+<?php
+
+use Psr\Http\Message\ServerRequestInterface;
+use Krak\Http\Middleware\HttpLink;
+
+function myMiddleware() {
+    return function(ServerRequestInterface $req, HttpLink $next) {
+        if (certainCondition($req)) {
+            return $next($req->withAttribute('a', '1'))->withStatusCode(404);
+        }
+
+        return $next->response(404, ['X-Header' => 'value'], 'Some body'); // can also use a php or psr-7 stream.
+    };
+}
+```
+
+#### injectRequestAttribute($name, $value)
+
+This will automatically inject an attribute with a name and the given value.
+
+#### wrap($psr7_middleware)
+
+This will wrap PSR-7 style middleware that use the request and response in the middleware parameters.
+
+```php
+<?php
+
+$mw = Krak\Http\Middleware\wrap(function($req, $resp, callable $next) {
+
+});
+```
+
+#### serveStatic($root)
+
+This will sit and will check if a file exists at the URI path. If it does, it will serve the file, else it will fall through to the next middleware.
+
+#### mount($path, $mw)
+
+Mounts a middleware on a path prefix. If the path prefix is matched, then the middleware is invoked.
+
+```php
+<?php
+
+use function Krak\Http\Middleware\{mount, serveStatic};
+
+$mw = mount('/assets', serveStatic(__DIR__ . '/path/to/assets'));
+```
+
+The above middleware will try to load files on the `/assets` uri. So `GET /assets/app.css` will return a css file content *if* `__DIR__ . /path/to/assets/app.css` exists in the filesystem.
+
 ## Tests and Examples
 
 Run tests via:

src/Middleware/mw.php

@@ -12,6 +12,15 @@ function injectRequestAttribute($name, $value) {
     };
 }
 
+/** wraps psr-7 middleware */
+function wrap($middleware) {
+    return function($req, $next) use ($middleware) {
+        return $middleware($req, $next->response(200), function($req, $resp) use ($next) {
+            return $next($req);
+        });
+    };
+}
+
 /** Serves static files over a directory. The $root is a path to physical directory
     to where the static files lie. */
 function serveStatic($root) {

test/middleware.php

@@ -2,6 +2,7 @@
 
 use Krak\Mw;
 use Krak\Http;
+use Psr\Http\Message;
 
 beforeEach(function() {
     $this->container = Krak\Cargo\container();
@@ -60,3 +61,20 @@ function($req, $next) { return $next->response(404); },
         assert($resp->getStatusCode() == 200 && (string) $resp->getBody() == "/admin/module/assets/app.css");
     });
 });
+describe('#wrap', function() {
+    it('wraps a psr-7 style middleware', function() {
+        $psr7_mw = function(Message\ServerRequestInterface $req, Message\ResponseInterface $resp, callable $next) {
+            return $next($req->withAttribute('foo', 'bar'), $resp)->withHeader('A', '1');
+        };
+        $compose = $this->container['krak.http.compose'];
+        $handler = $compose([
+            function($req, $next) {
+                return $next->response(201, [], $req->getAttribute('foo'));
+            },
+            Http\Middleware\wrap($psr7_mw)
+        ]);
+
+        $resp = $handler($this->container['request']);
+        assert($resp->getStatusCode() == 201 && (string) $resp->getBody() == 'bar' && $resp->getHeaderLine('A') == '1');
+    });
+});