search

http-interop / http-middleware

PSR-15 interfaces for HTTP Middleware
MIT License
73 stars 7 forks source link

Fix phpdocs #59

Closed schnittstabil closed 7 years ago

schnittstabil commented 7 years ago

Because @shadowhand has closed #53, I have to recreate this PR :disappointed:

@shadowhand I've implemented your suggestions in a way which I believe:

  1. solve the issues of #53
  2. unifies all the different technical terms

I've only used the already established wording:

  1. middlewares are dispatched
  2. requests and responses are processed

@shadowhand I truly believe this PR completely aligns with you intentions, hence please do not close it prematurely – maybe I/we can fix remaining issues.

Form the current README.md

3.2 Non-Goals

  • Attempting to define how middleware is dispatched.

    5.2 Delegate Design

The DelegateInterface defines a single method that accepts a request and returns a response. The delegate interface must be implemented by any middleware dispatcher that uses middleware implementing ServerMiddlewareInterface.

Obviously, dispatching a middleware does not necessarily implies the existence of a next available middleware or a next middleware component. There are too many real-world use-cases where we want to dispatch only one single middleware; hence, sticking to the current phpdoc wording would make PSR-15 less useful and does not reflect the point of view of the README.md.

Moreover PSR-15 should focus on interop of middlewares, the existence of additional middlewares in some frameworks is therefore out of scope. A middleware should only be aware of sitting between a request and a response. Using the StackPHP picture:

stackphp-lambda-middleware

Why Process and not Dispatch at DelegateInterface?

This is due to the fact, that we currently have DelegateInterface::process and not DelegateInterface::dispatch.

Why request processor?

This is also due to the fact, that we currently have DelegateInterface::process and not DelegateInterface::dispatch or DelegateInterface::handle – In my opinion, request handler sounds much better and is more common, but there is no reason to introduce another technical term. Furthermore, obviously, a standard should use as few technical terms as possible to not confuse implementers.

shadowhand commented 7 years ago

You should make this PR against fig-standards once php-fig/fig-standards#867 is merged.

schnittstabil commented 7 years ago

@shadowhand May you like to review this PR before I will create a new PR against fig-standards?