Updates documentation to reflect changes to HalResponseFactory

Also discovered a number of other general changes that were necessary:

- Docs were still refering to http-interop; updated to PSR-15.
- Docs were detailing middleware, where request handlers were more appropriate.
- Docs were using http URIs for PHP-FIG links; updated to https.
- Added more links to FIG specifications.

Author: weierophinney

docs/book/cookbook/generating-custom-links-in-middleware.md

@@ -1,4 +1,4 @@
-# Generating custom links in middleware
+# Generating custom links in middleware and request handlers
 
 In most cases, you can rely on the `ResourceGenerator` to generate self
 relational links, and, in the case of paginated collections, pagination links.

docs/book/cookbook/generating-custom-resources.md

@@ -39,6 +39,7 @@ $resourceGenerator->addStrategy(CustomMetadata::class, $strategyInstance);
 ```
 
 You can also add your strategies via the configuration:
+
 ```php
 return [
     'zend-expressive-hal' => [
@@ -62,6 +63,7 @@ decide to write your own strategies.
 In order for the `MetadataMap` to be able to use your `CustomMetadata` you need to register 
 a factory (implementing `Zend\Expressive\Hal\Metadata\MetadataFactoryInterface`) for it.
 You can register them via the configuration:
+
 ```php
 return [
     'zend-expressive-hal' => [

docs/book/factories.md

@@ -1,32 +1,25 @@
 # Provided factories
 
 This component provides a number of factories for use with
-[PSR-11](http://www.php-fig.org/psr/psr-11/), in order to generate fully
+[PSR-11](https://www.php-fig.org/psr/psr-11/), in order to generate fully
 configured instances for your use.
 
 ## Zend\Expressive\Hal\HalResponseFactoryFactory
 
 - Registered as service: `Zend\Expressive\Hal\HalResponseFactory`
 - Generates instance of: `Zend\Expressive\Hal\HalResponseFactory`
 - Depends on:
-    - `Psr\Http\Message\ResponseInterface` service. If not present, it will
-      check if zend-diactoros is installed, and use a new `Response` instance
-      from that library; if not, it raises an exception.
-    - `Psr\Http\Message\StreamInterface` service. This service must return a
-      a callable capable of returning a `StreamInterface` instance (in other
-      words, the service returns a _factory_, and not the stream itself). If th
-      service is not present, the factory will check if zend-diactoros is
-      installed, and return a callable that returns a new `Stream` instance from
-      that library; if not, it raises an exception.
+    - `Psr\Http\Message\ResponseInterface` service. The service must resolve to
+      a PHP callable capable of generating a [PSR-7](https://www.php-fig.org/psr/psr-7/)
+      `ResponseInterface` instance; it must not resolve to a `ResponseInterface`
+      instance directly. This service is **required**, and must be supplied by
+      the application. If you are using with zend-expressive v3 and above, the
+      service will already be registered.
     - `Zend\Expressive\Hal\Renderer\JsonRenderer` service. If the service is not
       present, it instantiates an instance itself.
     - `Zend\Expressive\Hal\Renderer\XmlRenderer` service. If the service is not
       present, it instantiates an instance itself.
 
-If you want to use a different PSR-7 implementation for the response and stream,
-provide services for `Psr\Http\Message\ResponseInterface` and
-`Psr\Http\Message\StreamInterface`, as described above.
-
 ## Zend\Expressive\Hal\LinkGeneratorFactory
 
 - Registered as service: `Zend\Expressive\Hal\LinkGenerator`

docs/book/intro.md

@@ -14,7 +14,7 @@ These two tools allow you to model payloads of varying complexity.
 
 To allow providing _representations_ of these, we provide
 `Zend\Expressive\Hal\HalResponseFactory`. This factory generates a
-[PSR-7](http://www.php-fig.org/psr/psr-7/) response for the provided resource,
+[PSR-7](https://www.php-fig.org/psr/psr-7/) response for the provided resource,
 including its links and any embedded/child resources it composes.
 
 Creating link URIs by hand is error-prone, as URI schemas may change; most
@@ -150,9 +150,9 @@ MetadataMap::class => [
 
 ### Manually creating and rendering a resource
 
-The following middleware creates a `HalResource` with its associated links, and
-then manually renders it using `Zend\Expressive\Hal\Renderer\JsonRenderer`. (An
-`XmlRenderer` is also provided, but not demonstrated here.)
+The following request handler creates a `HalResource` with its associated links,
+and then manually renders it using `Zend\Expressive\Hal\Renderer\JsonRenderer`.
+(An `XmlRenderer` is also provided, but not demonstrated here.)
 
 We'll assume that `Api\Books\Repository` handles retrieving data from persistent
 storage.
@@ -161,16 +161,16 @@ storage.
 namespace Api\Books\Action;
 
 use Api\Books\Repository;
-use Interop\Http\ServerMiddleware\DelegateInterface;
-use Interop\Http\ServerMiddleware\MiddlewareInterface;
+use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 use RuntimeException;
 use Zend\Diactoros\Response\TextResponse;
 use Zend\Expressive\Hal\HalResource;
 use Zend\Expressive\Hal\Link;
 use Zend\Expressive\Hal\Renderer\JsonRenderer;
 
-class BookAction implements MiddlewareInterface
+class BookAction implements RequestHandlerInterface
 {
     /** @var JsonRenderer */
     private $renderer;
@@ -186,7 +186,7 @@ class BookAction implements MiddlewareInterface
         $this->renderer = $renderer;
     }
 
-    public function process(ServerRequestInterface $request, DelegateInterface $delegate)
+    public function handle(ServerRequestInterface $request) : ResponseInterface
     {
         $id = $request->getAttribute('id', false);
         if (! $id) {
@@ -223,28 +223,29 @@ instance. As the complexity of your objects increase, and the number of objects
 you want to represent via HAL increases, you may not want to manually generate
 them.
 
-### Middleware using the ResourceGenerator and ResponseFactory
+### Request handler using the ResourceGenerator and ResponseFactory
 
-In this next example, our middleware will compose a `Zend\Expressive\Hal\ResourceGenerator`
-instance for generating a `Zend\Expressive\Hal\HalResource` from our objects,
-and a `Zend\Expressive\Hal\HalResponseFactory` for creating a response based on
-the returned resource.
+In this next example, our request handler will compose a
+`Zend\Expressive\Hal\ResourceGenerator` instance for generating a
+`Zend\Expressive\Hal\HalResource` from our objects, and a
+`Zend\Expressive\Hal\HalResponseFactory` for creating a response based on the
+returned resource.
 
-First, we'll look at middleware that displays a single book. We'll assume that
+First, we'll look at a handler that displays a single book. We'll assume that
 `Api\Books\Repository` handles retrieving data from persistent storage.
 
 ```php
 namespace Api\Books\Action;
 
 use Api\Books\Repository;
-use Interop\Http\ServerMiddleware\DelegateInterface;
-use Interop\Http\ServerMiddleware\MiddlewareInterface;
-use Psr\Http\ServerRequestInterface;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 use RuntimeException;
 use Zend\Expressive\Hal\HalResponseFactory;
 use Zend\Expressive\Hal\ResourceGenerator;
 
-class BookAction
+class BookAction implements RequestHandlerInterface
 {
     /** @var Repository */
     private $repository;
@@ -265,7 +266,7 @@ class BookAction
         $this->responseFactory = $responseFactory;
     }
 
-    public function __invoke(ServerRequestInterface $request, DelegateInterface $delegate)
+    public function handle(ServerRequestInterface $request) : ResponseInterface
     {
         $id = $request->getAttribute('id', false);
         if (! $id) {
@@ -301,9 +302,9 @@ The generated payload might look like the following:
 }
 ```
 
-### Middleware returning a collection
+### Request handler returning a collection
 
-Next, we'll create middleware that returns a _collection_ of books. The
+Next, we'll create a request handler that returns a _collection_ of books. The
 collection will be _paginated_ (assume our repository class creates a
 `BookCollection` backed by an appropriate adapter), and use a query string
 parameter to determine which page of results to return.
@@ -312,14 +313,14 @@ parameter to determine which page of results to return.
 namespace Api\Books\Action;
 
 use Api\Books\Repository;
-use Interop\Http\ServerMiddleware\DelegateInterface;
-use Interop\Http\ServerMiddleware\MiddlewareInterface;
-use Psr\Http\ServerRequestInterface;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 use RuntimeException;
 use Zend\Expressive\Hal\HalResponseFactory;
 use Zend\Expressive\Hal\ResourceGenerator;
 
-class BooksAction
+class BooksAction implements RequestHandlerInterface
 {
     /** @var Repository */
     private $repository;
@@ -340,7 +341,7 @@ class BooksAction
         $this->responseFactory = $responseFactory;
     }
 
-    public function __invoke(ServerRequestInterface $request, DelegateInterface $delegate)
+    public function handle(ServerRequestInterface $request) : ResponseInterface
     {
         $page = $request->getQueryParams()['page'] ?? 1;
 

docs/book/links-and-resources.md

@@ -13,7 +13,7 @@ The basic building blocks of this component are links and resources:
 
 > ### PSR-13
 > 
-> zendframework/zend-expressive-hal implements [PSR-13](http://www.php-fig.org/psr/psr-13/),
+> zendframework/zend-expressive-hal implements [PSR-13](https://www.php-fig.org/psr/psr-13/),
 > which provides interfaces for relational links and collections of relational
 > links. `Zend\Expressive\Hal\Link` implements `Psr\Link\EvolvableLinkInterface`, and
 > `Zend\Expressive\Hal\HalResource` implements `Psr\Link\EvolvableLinkProviderInterface`.

docs/book/representations.md

@@ -4,9 +4,9 @@ This component provides two renderers, one each for creating JSON and XML
 payloads.
 
 Additionally, as noted in the [introduction](intro.md) examples, this component
-provides `Zend\Expressive\Hal\HalResponseFactory` for generating a PSR-7
-response containing the HAL representation. This chapter dives into that with
-more detail.
+provides `Zend\Expressive\Hal\HalResponseFactory` for generating a
+[PSR-7](https://www.php-fig.org/psr/psr-7/) response containing the HAL
+representation. This chapter dives into that with more detail.
 
 ## Renderers
 
@@ -33,13 +33,13 @@ with `json_encode()`. By default, if none are provided, it uses the value of
 `JsonRenderer::DEFAULT_JSON_FLAGS`, which evaluates to:
 
 ```php
-JSON_PRETTY_PRINT
-| JSON_UNESCAPED_SLASHES
+JSON_UNESCAPED_SLASHES
 | JSON_UNESCAPED_UNICODE
 | JSON_PRESERVE_ZERO_FRACTION
 ```
 
-This provides human-readable JSON output.
+When your application is in "debug" mode, it also adds the `JSON_PRETTY_PRINT`
+flag to the default list, in order to provide human-readable JSON output.
 
 ### XmlRenderer
 
@@ -50,13 +50,8 @@ constructor arguments at this time.
 
 `HalResponseFactory` generates a PSR-7 response containing a representation of
 the provided `HalResource` instance. In order to keep the component agnostic of
-PSR-7 implementation, the factory composes:
-
-- A PSR-7 response prototype. A zend-diactoros `Response` is used if none is
-  provided.
-- A callable capable of generating an empty, writable, PSR-7 stream instance.
-  If none is provided, a callable returning a zend-diactoros `Stream` is
-  provided.
+PSR-7 implementation, `HalResponseFactory` itself composes a callable factory
+capable of producing an empty PSR-7 response.
 
 As an example:
 
@@ -66,30 +61,21 @@ use Slim\Http\Stream;
 use Zend\Expressive\Hal\HalResponseFactory;
 
 $factory = new HalResponseFactory(
-    new Response(),
     function () {
-        return new Stream(fopen('php://temp', 'wb+'));
+        return new Response();
     }
 );
 ```
 
-> ### Streams
->
-> A factory callable is necessary for generating streams as they are usually
-> backed by PHP resources, which are not immutable. Sharing instances could
-> thus potentially lead to appending or overwriting contents!
-
-By default, if you pass no arguments to the `HalResponseFactory` constructor, it
-assumes the following:
+Additionally, the `HalResponseFactory` constructor can accept the following
+arguments, with the described defaults if none is provided:
 
-- Usage of `Zend\Diactoros\Response`.
-- A callable that returns a new `Zend\Diactoros\Stream` using `php://temp` as
-  its backing resource.
 - A `JsonRenderer` instance is created if none is provided.
 - An `XmlRenderer` instance is created if none is provided.
 
-We provide a PSR-11 compatible factory for generating the `HalResponseFactory`
-which uses zend-diactoros by default.
+We provide a [PSR-11](https://www.php-fig.org/psr/psr-11) compatible factory for
+generating the `HalResponseFactory`, described in [the factories
+chapter](factories.md#zendexpressivehalhalresponsefactoryfactory).
 
 ## Using the factory
 
@@ -153,9 +139,9 @@ if that's all the car currently has associated with it.
 
 To accommodate this, we provide two features.
 
-For links, you may pass a special attribute, `Hal\Link::AS_COLLECTION`, with a
-boolean value of `true`; when encountered, this will then be rendered as an
-array of links, even if only one link for that relation is present.
+For links, you may pass a special attribute, `Zend\Expressive\Hal\Link::AS_COLLECTION`,
+with a boolean value of `true`; when encountered, this will then be rendered as
+an array of links, even if only one link for that relation is present.
 
 ```php
 $link = new Link(

docs/book/resource-generator.md

@@ -81,7 +81,7 @@ $metadataMap->add($booksMetadata);
 
 To automate generation of the `MetadataMap`, we provide
 `Zend\Expressive\Hal\Metadata\MetadataMapFactory`. This factory may be used with any
-[PSR-11](http://www.php-fig.org/psr/psr-11/) container. It utilizes the `config`
+[PSR-11](https://www.php-fig.org/psr/psr-11/) container. It utilizes the `config`
 service, and pulls its configuration from a key named after the
 `Zend\Expressive\Hal\Metadata\MetadataMap` class.
 

mkdocs.yml

@@ -11,7 +11,7 @@ pages:
       - "Representations": representations.md
       - "Factories": factories.md
     - Cookbook:
-        - "Generating Custom Links In Middleware": cookbook/generating-custom-links-in-middleware.md
+        - "Generating Custom Links In Middleware and Request Handlers": cookbook/generating-custom-links-in-middleware.md
 site_name: Hypertext Application Language
 site_description: 'Hypertext Application Language for PSR-7 Applications'
 repo_url: 'https://github.com/zendframework/zend-expressive-hal'