Merge 35cd8ce into c451d2e

.gitattributes

@@ -1,4 +1,4 @@
-/doc export-ignore
+/docs export-ignore
 /test export-ignore
 /.coveralls.yml export-ignore
 /.docheader export-ignore

.gitignore

@@ -1,6 +1,6 @@
 vendor/
 phpunit.xml
-doc/html/
+docs/html/
 zf-mkdoc-theme/
 clover.xml
 coveralls-upload.json

CONDUCT.md → docs/CODE_OF_CONDUCT.md

@@ -1,6 +1,6 @@
 # Contributor Code of Conduct
 
-The Zend Framework project adheres to [The Code Manifesto](http://codemanifesto.com)
+This project adheres to [The Code Manifesto](http://codemanifesto.com)
 as its guidelines for contributor interactions.
 
 ## The Code Manifesto

CONTRIBUTING.md → docs/CONTRIBUTING.md

@@ -2,46 +2,16 @@
 
 ## RESOURCES
 
-If you wish to contribute to Zend Framework, please be sure to
+If you wish to contribute to this project, please be sure to
 read/subscribe to the following resources:
 
- -  [Coding Standards](https://github.com/zendframework/zf2/wiki/Coding-Standards)
- -  [Contributor's Guide](http://framework.zend.com/participate/contributor-guide)
- -  ZF Contributor's mailing list:
-    Archives: http://zend-framework-community.634137.n4.nabble.com/ZF-Contributor-f680267.html
-    Subscribe: zf-contributors-subscribe@lists.zend.com
- -  ZF Contributor's IRC channel:
-    #zftalk.dev on Freenode.net
+ - [Coding Standards](https://github.com/zendframework/zend-coding-standard)
+ - [Forums](https://discourse.zendframework.com/c/contributors)
+ - [Slack](https://zendframework-slack.herokuapp.com)
+ - [Code of Conduct](CODE_OF_CONDUCT.md)
 
-If you are working on new features or refactoring [create a proposal](https://github.com/zendframework/zend-stratigility/issues/new).
-
-## Reporting Potential Security Issues
-
-If you have encountered a potential security vulnerability, please **DO NOT** report it on the public
-issue tracker: send it to us at [zf-security@zend.com](mailto:zf-security@zend.com) instead.
-We will work with you to verify the vulnerability and patch it as soon as possible.
-
-When reporting issues, please provide the following information:
-
-- Component(s) affected
-- A description indicating how to reproduce the issue
-- A summary of the security vulnerability and impact
-
-We request that you contact us via the email address above and give the project
-contributors a chance to resolve the vulnerability and issue a new release prior
-to any public exposure; this helps protect users and provides them with a chance
-to upgrade and/or update in order to protect their applications.
-
-For sensitive email communications, please use [our PGP key](http://framework.zend.com/zf-security-pgp-key.asc).
-
-## Documentation
-
-Documentation is in [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/),
-and rendered using [bookdown](http://bookdown.io). Please read and follow the [general documentation
-guidelines](https://github.com/zendframework/documentation/blob/master/CONTRIBUTING.md) when
-providing documentation.
-
-All new features **must** include documentation before they may be accepted and merged.
+If you are working on new features or refactoring
+[create a proposal](https://github.com/zendframework/zend-stratigility/issues/new).
 
 ## RUNNING TESTS
 
@@ -95,18 +65,6 @@ $ composer cs-fix
 If the above fixes any CS issues, please re-run the tests to ensure
 they pass, and make sure you add and commit the changes after verification.
 
-## Running License Checks
-
-File-level docblocks should follow the format demonstrated in `.docheader`. To
-check for conformity, use:
-
-```console
-$ composer license-check
-```
-
-This will flag files that are incorrect, which you can then update. Re-run the
-tool to verify your changes.
-
 ## Recommended Workflow for Contributions
 
 Your first step is to establish a public repository from which we can
@@ -198,15 +156,7 @@ To send a pull request, you have two options.
 If using GitHub, you can do the pull request from there. Navigate to
 your repository, select the branch you just created, and then select the
 "Pull Request" button in the upper right. Select the user/organization
-"zendframework" as the recipient.
-
-If using your own repository - or even if using GitHub - you can use `git
-format-patch` to create a patchset for us to apply; in fact, this is
-**recommended** for security-related patches. If you use `format-patch`, please
-send the patches as attachments to:
-
--  zf-devteam@zend.com for patches without security implications
--  zf-security@zend.com for security patches
+"zendframework" (or whatever the upstream organization is) as the recipient.
 
 #### What branch to issue the pull request against?
 
@@ -237,8 +187,3 @@ repository, we suggest doing some cleanup of these branches.
    ```console
    $ git push {username} :<branchname>
    ```
-
-
-## Conduct
-
-Please see our [CONDUCT.md](CONDUCT.md) to understand expected behavior when interacting with others in the project.

docs/ISSUE_TEMPLATE.md

@@ -0,0 +1,11 @@
+Provide a narrative description of the issue.
+
+### Code to reproduce the issue
+
+```php
+```
+
+### Expected results
+
+### Actual results
+

docs/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+Provide a narrative description of what you are trying to accomplish:
+
+- [ ] Are you fixing a bug?
+  - [ ] Detail how the bug is invoked currently.
+  - [ ] Detail the original, incorrect behavior.
+  - [ ] Detail the new, expected behavior.
+  - [ ] Base your feature on the `master` branch, and submit against that branch.
+  - [ ] Add a regression test that demonstrates the bug, and proves the fix.
+  - [ ] Add a `CHANGELOG.md` entry for the fix.
+
+- [ ] Are you creating a new feature?
+  - [ ] Why is the new feature needed? What purpose does it serve?
+  - [ ] How will users use the new feature?
+  - [ ] Base your feature on the `develop` branch, and submit against that branch.
+  - [ ] Add only one feature per pull request; split multiple features over multiple pull requests
+  - [ ] Add tests for the new feature.
+  - [ ] Add documentation for the new feature.
+  - [ ] Add a `CHANGELOG.md` entry for the new feature.
+
+- [ ] Is this related to quality assurance?
+  - [ ] Detail why the changes are necessary.
+
+- [ ] Is this related to documentation?
+  - [ ] Is it a typographical and/or grammatical fix?
+  - [ ] Is it new documentation?

docs/SUPPORT.md

@@ -0,0 +1,25 @@
+# Getting Support
+
+Zend Framework offers three support channels:
+
+- For real-time questions, use our
+  [Slack](https://zendframework-slack.herokuapp.com)
+- For detailed questions (e.g., those requiring examples) use our
+  [forums](https://discourse.zendframework.com/c/questions/expressive)
+- To report issues, use this repository's
+  [issue tracker](https://github.com/zendframework/zend-stratigility/issues/new)
+
+**DO NOT** use the issue tracker to ask questions; use Slack or the forums for
+that. Questions posed to the issue tracker will be closed.
+
+When reporting an issue, please include the following details:
+
+- A narrative description of what you are trying to accomplish.
+- The minimum code necessary to reproduce the issue.
+- The expected results of exercising that code.
+- The actual results received.
+
+We may ask for additional details: what version of the library you are using,
+and what PHP version was used to reproduce the issue.
+
+You may also submit a failing test case as a pull request.

doc/book/api.md → docs/book/api.md

@@ -10,8 +10,18 @@ has been discussed previously. Its API is:
 ```php
 namespace Zend\Stratigility;
 
+// http-interop/http-middleware 0.2:
+use Interop\Http\Middleware\DelegateInterface;
+use Interop\Http\Middleware\ServerMiddlewareInterface;
+
+// http-interop/http-middleware 0.4.1:
 use Interop\Http\ServerMiddleware\DelegateInterface;
 use Interop\Http\ServerMiddleware\MiddlewareInterface as ServerMiddlewareInterface;
+
+// http-interop/http-middleware 0.5.0:
+use Interop\Http\Server\MiddlewareInterface as ServerMiddlewareInterface;
+use Interop\Http\Server\RequestHandlerInterface as DelegateInterface;
+
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
@@ -186,7 +196,7 @@ function ($request, $response, $next) use ($bodyParser)
     );
 }
 
-// http-interop invokable:
+// http-interop/http-middleware < 0.5 invokable:
 function ($request, DelegateInterface $delegate) use ($bodyParser)
 {
     $bodyParams = $bodyParser($request);
@@ -196,6 +206,17 @@ function ($request, DelegateInterface $delegate) use ($bodyParser)
         $request->withBodyParams($bodyParams)
     );
 }
+
+// http-interop/http-middlewre 0.5.0 invokable:
+function ($request, RequestHandlerInterface $handler) use ($bodyParser)
+{
+    $bodyParams = $bodyParser($request);
+
+    // Delegate will receive the new request instance:
+    return $handler->handle(
+        $request->withBodyParams($bodyParams)
+    );
+}
 ```
 
 ### Providing an altered request and operating on the returned response:
@@ -211,7 +232,7 @@ function ($request, $response, $next) use ($bodyParser)
     return $response->withAddedHeader('Cache-Control', [
 }
 
-// http-interop invokable:
+// http-interop/http-middleware < 0.5 invokable:
 function ($request, DelegateInterface $delegate) use ($bodyParser)
 {
     $bodyParams = $bodyParser($request);
@@ -221,6 +242,17 @@ function ($request, DelegateInterface $delegate) use ($bodyParser)
         $request->withBodyParams($bodyParams)
     );
 }
+
+// http-interop/http-middleware 0.5.0 invokable:
+function ($request, RequestHandlerInterface $handler) use ($bodyParser)
+{
+    $bodyParams = $bodyParser($request);
+
+    // Provide a new request instance to the delegate:
+    return $handler->handle(
+        $request->withBodyParams($bodyParams)
+    );
+}
 ```
 
 ### Returning a response to complete the request
@@ -247,7 +279,7 @@ function ($request, $response, $next) use ($prototype)
     return $response;
 }
 
-// http-interop invokable signature:
+// http-interop/http-middleware < 0.5 invokable signature:
 function ($request, DelegateInterface $delegate) use ($prototype)
 {
     $response = $prototype->withAddedHeader('Cache-Control', [
@@ -256,6 +288,16 @@ function ($request, DelegateInterface $delegate) use ($prototype)
         's-maxage=18600',
     ]);
 }
+
+// http-interop/http-middleware 0.5.0 invokable signature:
+function ($request, RequestHandlerInterface $handler) use ($prototype)
+{
+    $response = $prototype->withAddedHeader('Cache-Control', [
+        'public',
+        'max-age=18600',
+        's-maxage=18600',
+    ]);
+}
 ```
 
 ### Delegation
@@ -270,12 +312,19 @@ If using the legacy middleware signature, invoke the `$next` argument:
 return $next($request, $response);
 ```
 
-If using a `DelegateInterface`, invoke its `process()` method:
+If using `http-interop/http-middleware` in version lower than 0.5.0,
+then the interface is `DelegateInterface`, invoke its `process()` method:
 
 ```php
 return $delegate->process($request);
 ```
 
+If using `http-interop/http-middleware` in version 0.5.0 or above,
+then the interface is `RequestHandlerInterface`, invoke its `handle()` method:
+```php
+return $handler->handle($request);
+```
+
 **Middleware should always return a response, and, if it cannot, return the
 result of delegation.**
 
@@ -395,7 +444,7 @@ Two versions exist:
 
 - `Zend\Stratigility\Middleware\CallableMiddlewareWrapper` will wrap a callable
   that defines exactly two arguments, with the second type-hinting on the
-  http-interop/http-middleware `DelegateInterface`:
+  http-interop/http-middleware `DelegateInterface` (version < 0.5):
 
   ```php
   $middleware = new CallableMiddlewareWrapper(
@@ -405,6 +454,16 @@ Two versions exist:
   );
   ```
 
+  or `RequestHandlerInterface` (version 0.5.0):
+
+  ```php
+  $middleware = new CallableMiddlewareWrapper(
+    function ($request, RequestHandlerInterface $handler) {
+        // ...
+    }
+  );
+  ```
+
 You can manually decorate callable middleware using these decorators, or simply
 let `MiddlewarePipe` do the work for you. To let `MiddlewarePipe` handle this,
 however, you _must_ compose a response prototype prior to piping middleware
@@ -417,9 +476,9 @@ http-interop/http-middleware `DelegateInterface` implementation,
 `Zend\Stratigility\Delegate\CallableDelegateDecorator`.
 
 This class can be used to wrap a callable `$next` instance for use in passing to
-an http-interop/http-middleware middleware interface `process()` method as a
-delegate; the primary use case is adapting functor middleware to work as
-http-interop middleware.
+an http-interop/http-middleware middleware interface `process()`/`handle()`
+method as a delegate; the primary use case is adapting functor middleware to
+work as http-interop middleware.
 
 As an example:
 
@@ -432,6 +491,10 @@ use Interop\Http\Middleware\ServerMiddlewareInterface;
 use Interop\Http\ServerMiddleware\DelegateInterface;
 use Interop\Http\ServerMiddleware\MiddlewareInterface as ServerMiddlewareInterface;
 
+// http-interop/http-middleware 0.5.0:
+use Interop\Http\Server\MiddlewareInterface as ServerMiddlewareInterface;
+use Interop\Http\Server\RequestHandlerInterface as DelegateInterface;
+
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use Zend\Stratigility\Delegate\CallableDelegateDecorator;
@@ -450,7 +513,12 @@ class TimestampMiddleware implements ServerMiddlewareInterface
         ServerRequestInterface $request,
         DelegateInterface $delegate
     ) {
+        // http-interop/http-middleware < 0.5
         $response = $delegate->process($request);
+
+        // http-interop/http-middleware 0.5.0
+        $response = $delegate->handle($request);
+
         return $response->withHeader('X-Processed-Timestamp', time());
     }
 }