Add documentation describing using Next handler in middlewares

[Aleksei Khudiakov]

Next handler in the pipeline passed as a second parameter to the middleware is not safe to invoke multiple times. What actually Next handler is is defined at runtime and is not guaranteed to be stateless, which can lead to undefined behavior.

For example, middleware designed to invoke Next handler second time will cause unintented side effects if Fail2Ban middleware is then registered next in the pipeline.

If handler needs to be invoked multiple times, it should be selected explicitly and injected as a direct dependency (directly or lazy way or as a proxy to a middleware pipe elsewhere, etc).

[Matthew Weier O'Phinney]

This repository has been closed and moved to laminas/laminas-stratigility; a new issue has been opened at laminas/laminas-stratigility#5.