Remove statements about how middlewares are dispatched.

[schnittstabil]

The statements are out of scope of this PSR, because they describe how middlewares are dispatched and are intended to dictate implementation details of middleware dispatching systems. These are declared non-goals as stated at 3.2:

3.2 Non-Goals

• Attempting to define how middleware is dispatched.

Fixes #54

[jschreuder]

You don't define how something is dispatched by requiring an interface implementation. All that sentence does is require a system that works with this PSR to be fully functional. But it doesn't dictate how it functions. As such that non-goal doesn't put those statements out of scope.

Personally I'd rather have it say it must provide an implementation instead of must be implemented, but in practice that's just nitpicking.

[schnittstabil]

Both sentences are clearly intended to dictate implementation details:

The delegate interface must be implemented by any middleware dispatcher that uses middleware implementing ServerMiddlewareInterface.

The implementation of delegate should be defined within middleware dispatching systems.

I.e. no one else is allowed to implement the DelegateInterface, only dispatchers and only packages which intention is to dispatch middlewares.

Therefore, only from the wording, we cannot have highly specialized delegate composer packages – prohibiting these is a declared non-goal.

I'm not advocating for callable or similar here. I'm only advocating for reusable delegates.

[schnittstabil]

You don't define how something is dispatched by requiring an interface implementation. All that sentence does is require a system that works with this PSR to be fully functional.

Because of the MiddlewareInterface::process signature and the 5.1 Middleware Design paragraph, it is already obvious to the reader:

• that a DelegateInterface implementation is required,
• a dispatcher have to provide a DelegateInterface instance somehow,
• why such an instance is needed
• and how it is used by a middleware.

Thus, the two sentences I'm suggesting to remove, are superfluous regarding to the Why an interface implementation is required? question.

[shadowhand]

Declaring where the interfaces should be used is not the same as declaring how middleware is dispatched. What may be obvious to you is not necessarily obvious to others. The documentation you are suggesting to remove provides explanation for why the DelegateInterface exists.

[schnittstabil]

Declaring where the interfaces [the DelegateInterface] should be used is not the same as declaring how middleware is dispatched.

It is not about where it is used, it is about where it is implemented – that's something totally different.

@shadowhand Well, anyway, the real questions are:

1. Do you think, the current version does not dictate where the DelegateInterface must be implemented?
2. Does the current version allow reusable DelegateInterface implementations (e.g. composer packages)?
3. Or the other way arround: Must delegate classes labeled efficiently as @internal?