Provides all documentation!

Author: weierophinney

README.md

@@ -3,7 +3,19 @@
 [![Build Status](https://secure.travis-ci.org/zendframework/zend-httphandlerrunner.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-httphandlerrunner)
 [![Coverage Status](https://coveralls.io/repos/github/zendframework/zend-httphandlerrunner/badge.svg?branch=master)](https://coveralls.io/github/zendframework/zend-httphandlerrunner?branch=master)
 
-This library provides ...
+This library provides utilities for:
+
+- Emitting [PSR-7](https://www.php-fig.org/psr/psr-7) responses.
+- Running [PSR-15](https://www.php-fig.org/psr/psr-15) server request handlers,
+  which involves marshaling a PSR-7 `ServerRequestInterface`, handling
+  exceptions due to request creation, and emitting the response returned by the
+  composed request handler.
+
+The `RequestHandlerRunner` will be used in the bootstrap of your application to
+fire off the `RequestHandlerInterface` representing your application.
+
+If you are developing an async application, you will more than likely not want
+to use this package.
 
 ## Installation
 

docs/book/emitters.md

@@ -0,0 +1,127 @@
+# Emitters
+
+Emitters are used to _emit_ a [PSR-7](https://www.php-fig.org/psr/psr-7)
+response. This should generally happen when running under a traditional PHP
+server API that uses output buffers, such as Apache or php-fpm.
+
+Emitters are described by `Zend\HttpHandlerRunner\Emitter\EmitterInterface`:
+
+```php
+use Psr\Http\Message\ResponseInterface;
+
+interface EmitterInterface
+{
+    public function emit(ResponseInterface $response) : bool;
+}
+```
+
+Typically, such emitters will perform the following:
+
+- Emit a response status line.
+- Emit all response headers.
+- Emit the response body.
+
+(The first two items may be swapped in order; many SAPIs allow emitting multiple
+status lines, and will use the last one present. As such, most implementations
+will emit the status line after the headers to ensure the correct one is emitted
+by the SAPI.)
+
+The `emit()` method allows returning a boolean. This value can be checked to
+determine if the emitter was able to emit the response. This capability is used
+by the provided `EmitterStack` to allow composing multiple emitters that can
+introspect the response to determine whether or not they are capable of emitting
+it.
+
+## SapiEmitter
+
+`Zend\HttpHandlerRunner\Emitter\SapiEmitter` accepts the response instance, and
+uses the built-in PHP function `header()` to emit both the headers as well as
+the status line. It then uses `echo` to emit the response body.
+
+Internally, it also does a number of verifications:
+
+- If headers have been previously sent, it will raise an exception.
+- If output has been previously sent, it will raise an exception.
+
+These are performed in order to ensure the integrity of the response emitted.
+
+It also filters header names to normalize them; this is done in part to ensure
+that if multiple headers of the same name are emitted, the SAPI will report them
+correctly.
+
+This emitter can _always_ handle a response, and thus _always_ returns true.
+
+## SapiStreamEmitter
+
+`Zend\HttpHandlerRunner\Emitter\SapiStreamEmitter` behaves similarly to the
+`SapiEmitter`, with two key differences:
+
+- It allows emitting a a _content range_, if a `Content-Range` header is
+  specified in the response.
+- It will iteratively emit a range of bytes from the response, based on the
+  buffer length provided to the emitter during construction. This is
+  particularly useful when returning _files_ or _downloads_.
+
+The emitter accepts an integer argument to the constructor, indicating the
+maximum buffer length; by default, this is 8192 bytes.
+
+This emitter can _always_ handle a response, and thus _always_ returns true.
+
+## EmitterStack
+
+`Zend\HttpHandlerRunner\Emitter\EmitterStack` allows providing a
+last-in-first-out (LIFO) stack of emitters instead of a single emitter. If an
+emitter is incapable of handling the response and returns `false`, the stack
+will move to the next emitter. If an emitter returns `true`, the stack
+short-circuits and immediately returns.
+
+The `EmitterStack` extends `SplStack`, and thus allows you to add emitters using
+any of the methods that class defines; we recommend adding them in LIFO order
+using `push()`:
+
+```php
+$stack->push($last);
+$stack->push($second);
+$stack->push($first);
+```
+
+### Conditionally using the SapiStreamEmitter
+
+The `SapiStreamEmitter` is capable of emitting any response. However, for
+in-memory responses, you may want to use the more efficient `SapiEmitter`. How
+can you do this?
+
+One way is to check for response artifacts that indicate a file download, such
+as the `Content-Disposition` or `Content-Range` headers; if those headers are
+not present, you could return `false` from the emitter, and otherwise continue.
+You could achieve this by decorating the `SapiStreamEmitter`:
+
+```php
+$sapiStreamEmitter = new SapiStreamEmitter($maxBufferLength);
+$conditionalEmitter = new class ($sapiStreamEmitter) implements EmitterInterface {
+    private $emitter;
+
+    public function __construct(EmitterInterface $emitter)
+    {
+        $this->emitter = $emitter;
+    }
+
+    public function emit(ResponseInterface) : bool
+    {
+        if (! $response->hasHeader('Content-Disposition')
+            && ! $response->hasHeader('Content-Range')
+        ) {
+            return false;
+        }
+        return $this->emitter->emit($response);
+    }
+};
+
+$stack = new EmitterStack();
+$stack->push(new SapiEmitter());
+$stack->push($conditionalEmitter);
+```
+
+In this way, you can have the best of both worlds, using the memory-efficient
+`SapiStreamEmitter` for large file downloads or streaming buffers, and the
+general-purpose `SapiEmitter` for everything else.

docs/book/intro.md

@@ -1,3 +1,15 @@
 # zend-httphandlerrunner
 
-This component provides ...
+This component provides  utilities for:
+
+- Emitting [PSR-7](https://www.php-fig.org/psr/psr-7) responses.
+- Running [PSR-15](https://www.php-fig.org/psr/psr-15) server request handlers,
+  which involves marshaling a PSR-7 `ServerRequestInterface`, handling
+  exceptions due to request creation, and emitting the response returned by the
+  composed request handler.
+
+The `RequestHandlerRunner` will be used in the bootstrap of your application to
+fire off the `RequestHandlerInterface` representing your application.
+
+If you are developing an async application, you will more than likely not want
+to use this package.

docs/book/runner.md

@@ -0,0 +1,85 @@
+# The Request Handler Runner
+
+`Zend\HttpHandlerRunner\RequestHandlerRunner` can be used to _run_ a
+[PSR-15](https://www.php-fig.org/psr/psr-15) `RequestHandlerInterface` instance.
+By this, we mean:
+
+- Marshal a server request instance.
+- Handle exceptions due to marshaling the server request instance.
+- Pass the request to the composed request handler.
+- Pass the response generated by the request handler to the composed [emitter](emitters.md)
+
+The runner takes four constructor arguments, in the following order:
+
+- A `Psr\Http\Server\RequestHandlerInterface` instance.
+- A `Zend\HttpHandlerRunner\Emitter\EmitterInterface` instance.
+- A PHP callable to generate a `Psr\Http\Message\ServerRequestInterface` instance.
+- A PHP callable that can generate a `Psr\Http\Message\ResponseInterface`
+  instance given a PHP `Throwable` generated by the server request factory
+  from the third argument.
+
+Once constructed, you may call the method `run()`:
+
+```php
+$runner->run();
+```
+
+## Server request factory
+
+The `$serverRequestFactory` argument to the constructor may be any PHP callable
+that accepts no arguments (or all optional arguments), and which returns a
+[PSR-7](https://www.php-fig.org/psr/psr-7) `ServerRequestInterface` instance.
+
+As an example, using [zend-diactoros](https://docs.zendframework.com/zend-diactoros):
+
+```php
+use Zend\Diactoros\ServerRequestFactory;
+
+$serverRequestFactory = [ServerRequestFactory::class, 'fromGlobals'];
+```
+
+Alternately, a [PSR-17 (proposed specification for HTTP message
+factories)](https://github.com/php-fig/fig-standards/tree/a6abdeb44a060d80925c95714f39854c510e879f/proposed/http-factory) factory may be used:
+
+```php
+use HttpInterop\Implementation\ServerRequestFactory;
+
+$serverRequestFactory = function () use ($_SERVER, $factory) {
+    return $factory->createServerRequestFromArray($_SERVER);
+};
+```
+
+## Server request error response generator
+
+In rare cases, the server request factory may raise a PHP `Throwable` or
+`Exception`. In those cases, the runner still needs to generate a response to
+emit.
+
+The server request error response generator argument to the
+`RequestHandlerRunner` constructor may be any PHP callable that accepts a PHP
+`Throwable` argument, and which returns a PSR-7 `ResponseInterface` instance.
+
+As an example, [zend-stratigility](https://docs.zendframework.com/zend-stratigility/)
+provides the class `Zend\Stratigility\Middleware\ErrorResponseGenerator`, which
+is typically used with its `ErrorHandler` to generate a response. It can be
+re-purposed if we curry in empty server request and response instances as
+follows:
+
+```php
+use Throwable;
+use Zend\Diactoros\Response;
+use Zend\Diactoros\ServerRequest;
+use Zend\Stratigility\Middleware\ErrorResponseGenerator;
+
+$errorResponseGenerator = function (Throwable $e) {
+    $generator = new ErrorResponseGenerator();
+    return $generator($e, new ServerRequest(), new Response());
+};
+```
+
+## Request handlers
+
+Request handlers MUST implement `Psr\Http\Server\RequestHandlerInterface`.
+Additionally, for best results, they MUST provide their own error and exception
+handling, to ensure that a response is returned and the runner is able to emit a
+response.

docs/book/usage.md

@@ -0,0 +1,36 @@
+# Installation and Usage
+
+To install this package, run the following [composer](https://getcomposer.org)
+command:
+
+```bash
+$ composer require zendframework/zend-httphandlerrunner
+```
+
+The package provides both [emitters](emitters.md) and the [request handler
+runner](runner.md), and these are generally used within the bootstrap of your
+application.
+
+We recommend using a dependency injection container to define your various
+instances, including the [PSR-15](https://www.php-fig.org/psr/psr-15) request
+handler representing your application, the response emitter, the server request
+factory, the server request error response generator, potentially, the runner
+itself.
+
+The example below instantiates the runner manually by pulling its dependencies
+from a configured [PSR-11](https://www.php-fig.org/psr/psr-11) container.
+
+```php
+use Zend\HttpHandlerRunner\Emitter\EmitterStack;
+use Zend\HttpHandlerRunner\RequestHandlerRunner;
+
+$container = require 'config/container.php';
+
+$runner = new RequestHandlerRunner(
+    $container->get(ApplicationRequestHandler::class),
+    $container->get(EmitterStack::class),
+    $container->get('ServerRequestFactory'),
+    $container->get('ServerRequestErrorResponseGenerator')
+);
+$runner->run();
+```

mkdocs.yml

@@ -3,6 +3,10 @@ site_dir: docs/html
 pages:
     - index.md
     - Introduction: intro.md
+    - Usage: usage.md
+    - Reference:
+      - "Request Handler Runner": runner.md
+      - Emitters: emitters.md
 site_name: zend-httphandlerrunner
 site_description: 'Execute PSR-15 RequestHandlerInterface instances and emit responses they generate.'
 repo_url: 'https://github.com/zendframework/zend-httphandlerrunner'