[REVIEW] PSR-15 Server Request Handlers

[Matthew Weier O'Phinney]

As of today, we formally begin the REVIEW phase of the proposed PSR-15
(HTTP Server Request Handlers) specification. The proposed
specification is in the fig-standards repository at the following
locations:

- Specification:
https://github.com/php-fig/fig-standards/blob/52a479b55f5c235ab44aed2254de7ef1f085982e/proposed/http-handlers/request-handlers.md
- Metadocument:
https://github.com/php-fig/fig-standards/blob/52a479b55f5c235ab44aed2254de7ef1f085982e/proposed/http-handlers/request-handlers-meta.md

During the review phase, acceptable changes to the specification
included wording, typographical fixes, and clarifications. If you feel
major changes are necessary, please bring your arguments to the list
under this thread. Woody Gilk, the Editor of the specification, will
be final arbiter on what changes we will include. If any major changes
are considered, we will return to the draft phase.

The review period will end no sooner than 1 January 2017 at 11:59pm.
At that time, if the working group can demonstrate two viable trial
implementations, and no need for major changes, I will call for an
Acceptance Vote.

--
Matthew Weier O'Phinney
mweiero...@gmail.com
https://mwop.net/

[Rivera, John]

First typographical correction!

In the class-level comment for the RequestHandlerInterface, there’s an missing ‘d’ in ‘… methods require_ to use …’ :)

> --
> You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAJp_myVtpqXE%3D2L6JcqY%3DFac4N2gQzwZnTz%2B6PV0tu6nzDyO5Q%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.

[Matthew Weier O'Phinney]

John -

Thanks! Can you please send a pull request?

> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/3E2FF89C-AE72-497A-8F4E-8B912D410969%40buffalo.edu.

> For more options, visit https://groups.google.com/d/optout.

[Hari K T]

I have send a PR to update the Interface so that throws Exception . https://github.com/php-fig/fig-standards/pull/975

One thing I would like to bring is about splitting the current PSR-15 into two .

RequestHandlerInterface and MiddlewareInterface as the repos are split into two.

https://github.com/http-interop/http-server-handler
https://github.com/http-interop/http-server-middleware

I think we can all agree to make this happen, so that it will not make the editors and working group and everyone participated in the PSR not consuming or dragging the PSR.

Thank you.

Hari K T

You can ring me : +91 9388 75 8821

http://harikt.com , https://github.com/harikt , http://www.linkedin.com/in/harikt , http://www.xing.com/profile/Hari_KT

Skype  : kthari85

Twitter : harikt

>> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@googlegroups.com.

>> To post to this group, send email to php...@googlegroups.com.
>> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAJp_myVtpqXE%3D2L6JcqY%3DFac4N2gQzwZnTz%2B6PV0tu6nzDyO5Q%40mail.gmail.com.
>> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@googlegroups.com.

> To post to this group, send email to php...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/3E2FF89C-AE72-497A-8F4E-8B912D410969%40buffalo.edu.
> For more options, visit https://groups.google.com/d/optout.



--
Matthew Weier O'Phinney
mweiero...@gmail.com
https://mwop.net/

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.

To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAJp_myXXJJ%2B5r1GYxjdRyd6hcQ_zvOPBCTd1zc7Tg5rchte1%2BQ%40mail.gmail.com.

[Jonathan Jefferies]

https://github.com/php-fig/fig-standards/blob/master/proposed/http-handlers/request-handlers.md#13-generating-responses

I wonder if it's best to not mention PSR-17 in the actual specification, so you don't have to deprecate or change this one if PSR-17 doesn't pass or becomes deprecated?
Could that section be moved to the meta document?

Maybe each PSR could have a "Related PSRs" section in the meta document?

Sorry if you've already discussed this before.

Jonathan

[Matthew Weier O'Phinney]

Hi, Hari!

Comments inline below.

On Tue, Dec 5, 2017 at 10:38 PM, Hari K T <ktha...@gmail.com> wrote:
> I have send a PR to update the Interface so that throws Exception .
> https://github.com/php-fig/fig-standards/pull/975

I've read through that thread. I think the distinction Woody is trying
to understand is whether you (or others on the thread) are implying
there should be an exception type regarding a "failure to understand
the request", or if a request handler should allow bubbling up domain
exceptions. My read of what Woody is saying is that domain logic
should of course be allowed to raise exceptions, but how a consumer of
a handler should handle those is outside the scope of the
specification.

As an author of a middleware framework, the assumption we've had all
along is that any class in the application can potentially throw an
exception. As such, we provide exception handler middleware to ensure
we're able to log errors as well as return an application response.

My feeling on this is: if the specification doesn't explicitly mention
a method can or cannot throw an exception, then it's up to the
implementation to decide what may or may not be exceptional behavior.
In the case of request handlers, I think that's particularly
important, as what constitutes a "valid request" may vary widely (does
the path need to match criteria? do certain attributes need to be
present? etc.), and, most likely, they will be doing domain-specific
processing that may not indicate an "invalid request", but could
result in exceptional behavior as well.

So, my take is: I don't particularly think we should add language
around exceptions here, as becoming *more* specific may actually lead
to too narrow of an interpretation of what is considered acceptable
behavior for an implementation.

> One thing I would like to bring is about splitting the current PSR-15 into
> two .
>
> RequestHandlerInterface and MiddlewareInterface as the repos are split into
> two.
>
> https://github.com/http-interop/http-server-handler
> https://github.com/http-interop/http-server-middleware
>
> I think we can all agree to make this happen, so that it will not make the
> editors and working group and everyone participated in the PSR not consuming
> or dragging the PSR.

This idea has been raised a few times, and, no, we cannot all agree to
make this happen.

This particular proposal set out to standardize *middleware*. While
doing that, an argument was made that what we were calling a
"delegate" also had more general utility and could potentially be
coded to directly. This led to the most recent round of changes, where
we renamed the DelegateInterface to RequestHandlerInterface (and also
renamed the method defined from "process" to "handle"), and changed
the namespace from Psr\Http\ServerMiddleware to the more general
Psr\Http\Server.

We chose as a working group to honor the idea that the
RequestHandlerInterface has its own general utility by splitting the
two interfaces into separate packages, with the MiddlewareInterface
package *depending* on the RequestHandlerInterface package (as the
middleware signature *consumes* a request handler). This allows
developers to code directly to the request handler interface without
requiring the middleware interface; those who want to consume the
primary target of the specification, the MiddlewareInterface, still
have all definitions in place in order to create their
implementations.

An argument has been made that splitting the interfaces into discrete
packages may lead to confusion: a package claiming to implement PSR-15
now has to indicate which interface(s) they implement. To be blunt:
this will always be the case when there are multiple interfaces
defined in a specification. With PSR-7, we have league/uri
implementing ONLY the UriInterface. For quite some time, Guzzle did
not implement ServerRequestInterface or UploadedFileInterface. Were
these PSR-7 implementations? Absolutely. They also clearly indicate
what part(s) of the specification they implement within their
documentation.

With PSR-15, there's a strong liklihood that a developer may only
implement MiddlewareInterface or RequestHandlerInterface -
particularly in packages that provide middleware implementation(s)
(such as the php-middleware project), or in packages such as Diactoros
(where we will likely update our Server class to implement the
RequestHandlerInterface). Shipping the interfaces as separate packages
means that the latter can depend only on the RequestHandlerInterface
package, which clearly signals what it implements. Packages that
depend on the MiddlewareInterface package will need to document what
they implement — which would be true even if the interfaces were
defined in separate specifications!

Additionally, splitting the RequestHandlerInterface into a separate
proposal means delaying this proposal for a minimum of another 3
months, and likely longer, which impacts the libraries that are
already attempting to track the proposal and provide implementations.
This affects the users of those implementations, as they have
uncertainty around what interface(s) to code against, and face
potential for migrations in the future.
This proposal is already stable; it has been floated for around two
years, and the basic workflow has not changed in over a year. It's
literally two interfaces, defining a single method apiece. Delaying it
longer to accommodate a few people who want more granular proposals,
when it's already about as granular as you can get, does a disservice
to those already coding against it.

Defining both interfaces in a single specification but shipping them
as separate packages is a quite reasonable compromise.

[Hari K T]

Hi Mathew,

Thank you for the detailed answer.

Not a native English speaker, so I don't know if I can convince you or others about the same.

Writing inline.

I understand your concern about creating a specific exception.

For me the wordings

> A request handler MAY throw an exception if request conditions prevent it from producing a response. The type of exception is not defined.

https://github.com/php-fig/fig-standards/blob/fd9a7669b1b0966fd2fb44d68a3485a1603561f1/proposed/http-handlers/request-handlers.md#11-request-handlers

are confusing when the interface not having @throws in the doc blocks .

Eg : If you look at the current doc blocks some of us are using @inherit .

You may argue this is application level  and so it is to the application developer to make the changes to doc blocks.

I wanted to express what I felt .

I believe we all make some conditions to make it better, so why not the group can make some adjustments to the law ?

Are we very strict on this ? Can't the voting members and working group all agree to give a number for this specific issue ? ( Mutual agreements ? )

I don't want to or love to make a delay, I do understand your concern for I have been using Zend-expressive and following some of the discussions around the issue.

 

This affects the users of those implementations, as they have
uncertainty around what interface(s) to code against, and face
potential for migrations in the future.

I understand.

 

This proposal is already stable; it has been floated for around two
years, and the basic workflow has not changed in over a year. It's
literally two interfaces, defining a single method apiece. Delaying it
longer to accommodate a few people who want more granular proposals,
when it's already about as granular as you can get, does a disservice
to those already coding against it.

Defining both interfaces in a single specification but shipping them
as separate packages is a quite reasonable compromise.

Sure.

[Larry Garfield]

On Tuesday, December 5, 2017 11:49:43 AM CST Matthew Weier O'Phinney wrote:
> As of today, we formally begin the REVIEW phase of the proposed PSR-15
> (HTTP Server Request Handlers) specification. The proposed
> specification is in the fig-standards repository at the following
> locations:
>
> - Specification:
> https://github.com/php-fig/fig-standards/blob/52a479b55f5c235ab44aed2254de7e
> f1f085982e/proposed/http-handlers/request-handlers.md - Metadocument:
> https://github.com/php-fig/fig-standards/blob/52a479b55f5c235ab44aed2254de7e
> f1f085982e/proposed/http-handlers/request-handlers-meta.md

*puts on CC member hat*

Commentary as I come across it:

1.1:
* "as defined by PSR-7". We should learn from PSR-1's PSR-0 reference and say
something like "as defined by PSR-7 or subsequent replacement PSRs."
Although... Hm, there's no guarantee of exact compatibility there as these are
interfaces, not just text. Open to input on this one.

* "The type of exception is not defined." - As other specs have done, I'd
prefer to see an exception interface that must be included. The exception can
be whatever, I suppose, but having an interface to look for to see if it's a
handler error is consistent with what other specs have done.

1.2:
* "An middleware". Middleware begins with a consonant, so it should be "A
middleware".

1.3:
* I am not sure how I feel about the PSR-17 mention here. Clearly I agree
with the concept, but referencing a still not-passed PSR feels dangerous.
Other CC folks, your thoughts?

1.4:
* :thumbs up emoji:

2:
* Shouldn't the docblock first lines be single-line? I'm totally fine with a
much longer description block but the first line should be a short single-line
statement.

Meta document:

6.2:
* "external requests are typically..." External requests is a wonky word to
use here. All requests come from something external; that's the whole point.
"Outbound requests" seems more descriptive.

Otherwise, the Metadoc looks awesome!

What I feel is missing is how one would assemble the handler and middleware.
My first thought looking at the interfaces and descriptions is "wait, so a
middleware can only take a request handler, so that means I can only stack one
level deep? That's kinda pointless, unless an object implements both, in which
case, erm, how's that work?"

I know that the WG has discussed the assembly process to death already and has
a good sense of how the pieces "should" be assembled, but from reading the
specs I cannot determine what that is. Even if it's just a "one possible way"
in the metadoc, there should be some guidance for how one actually leverages
the interfaces in practice, although something in the spec itself would be
helpful as well.

As that would not change the spec, just clarify it, I don't believe that would
necessitate coming out of Review state. The other comments above are all
fairly minor.

(Recall that under FIG 3 the Review state is more of a "beta", not an "RC", so
larger changes than typos are fine as long as BC is more or less maintained.
Nothing noted above should have any BC implications.)

Overall: Aside from that additional guidance, this looks really well done.
Nice work, everyone. Once we can get some better guidance included in one or
the other documents this would have my vote for passage.

--Larry Garfield

[John Porter]

I have kept out of this for a while now as I have had life things that felt more important to deal with, but I have to chime in again for my own sanity at least.

Please understand that as an outsider to this group, and someone who has not been involved in the process for this proposal at all, it just does not make sense.

When it was a DelegateInterface, and even now as a RequestHandlerInterface, it does not state what it is doing. Code should state the purpose it has, and 'handling a request' is not the purpose of an implementor of this interface; at least not as far as I can see. It is expected to return a response, so wouldn't a name describing that be more fitting?

When I first read the name change, I assumed that it meant that any class I write (like a route class) is supposed to implement this to be used in a middleware, that I would have to choose for each middleware which class to use to create a response object. I hope that I am wrong and think that is the case.

That got me thinking then, well, what is it? What is it supposed to do? How do I implement something like that? Basically the same questions I've asked of this proposal from the start.

I know you have all been round the houses on this, but I have to tell you that good code is supposed to be intuitive. Good interfaces should be too. This proposal still confuses me since the first day I saw it. The only decent way to explain this I fear, is to implement it, and then if there is an implementation, why would anyone do it another way? Ambiguous design like this is a big problem in software, and I feel that this proposal is making this a reality for the FIG.

[Woody Gilk]

On Sun, Dec 10, 2017 at 3:49 PM, John Porter <jo...@designermonkey.co.uk> wrote:

When I first read the name change, I assumed that it meant that any class I write (like a route class) is supposed to implement this to be used in a middleware, that I would have to choose for each middleware which class to use to create a response object. I hope that I am wrong and think that is the case.

That got me thinking then, well, what is it? What is it supposed to do? How do I implement something like that? Basically the same questions I've asked of this proposal from the start.

I'm a little surprised that this isn't intuitive. Perhaps that is a failing of the meta document?

The request handler is the "final" processing that will determine what response is suitable for a given request. Within a middleware stack, this typically means passing the request off to the next middleware as many times as necessary, until domain gateway is reached and actually handles the request. It is not expected that users will need to implement the request handler, since it is typically part of a given middleware dispatching system.

You might want to take a look at an implementation of PSR-15 such as Zend Expressive or https://github.com/northwoods/broker

Hopefully this clarifies things.

--
Woody Gilk
http://about.me/shadowhand

[Matthew Weier O'Phinney]

Thanks for the thorough review, Larry!

Comments inline.

On Sun, Dec 10, 2017 at 2:09 PM, Larry Garfield <la...@garfieldtech.com> wrote:
> On Tuesday, December 5, 2017 11:49:43 AM CST Matthew Weier O'Phinney wrote:
>> As of today, we formally begin the REVIEW phase of the proposed PSR-15
>> (HTTP Server Request Handlers) specification. The proposed
>> specification is in the fig-standards repository at the following
>> locations:
>>
>> - Specification:
>> https://github.com/php-fig/fig-standards/blob/52a479b55f5c235ab44aed2254de7e
>> f1f085982e/proposed/http-handlers/request-handlers.md - Metadocument:
>> https://github.com/php-fig/fig-standards/blob/52a479b55f5c235ab44aed2254de7e
>> f1f085982e/proposed/http-handlers/request-handlers-meta.md
>
> *puts on CC member hat*
>
> Commentary as I come across it:
>
> 1.1:
> * "as defined by PSR-7". We should learn from PSR-1's PSR-0 reference and say
> something like "as defined by PSR-7 or subsequent replacement PSRs."
> Although... Hm, there's no guarantee of exact compatibility there as these are
> interfaces, not just text. Open to input on this one.

Considering that this specification consumes PSR-7 _specifically_ (the
packages depend on it, and the interfaces code against the interfaces
defined in PSR-7), I think referencing it makes sense here,
particularly as there is no guarantee that a replacement would be
compatible.

> * "The type of exception is not defined." - As other specs have done, I'd
> prefer to see an exception interface that must be included. The exception can
> be whatever, I suppose, but having an interface to look for to see if it's a
> handler error is consistent with what other specs have done.

This was a deliberate decision, and we should likely document it.

The reason is pretty straight-forward: both middleware and request
handlers may work with other class instances and/or PHP internals
which might raise exceptions. We do not want to dictate a design
whereby a developer implementing either interface is now required to
catch any such exception and re-cast it, as doing so convolutes usage
of PHP exception handlers and/or application-level exception handlers.

(Additionally, middleware can often be used to _provide_ such
exception handling; see Slim and Expressive for examples!)

We _could_ document some common solutions to exception handling if you
would like; I personally feel it is likely beyond the scope of the
specification, however.

> 1.2:
> * "An middleware". Middleware begins with a consonant, so it should be "A
> middleware".

Could you provide a pull request for this change, please?

> 1.3:
> * I am not sure how I feel about the PSR-17 mention here. Clearly I agree
> with the concept, but referencing a still not-passed PSR feels dangerous.
> Other CC folks, your thoughts?

I tend to agree here. I think we can also make a clarification change
here that is not substantive. How about something like this:

It is RECOMMENDED that any middleware or request handler that
generates a response will either compose a prototype of a PSR-7
ResponseInterface or a factory capable of generating a
`ResponseInterface` instance in order to prevent dependence on a
specific HTTP message implementation.

Woody, thoughts? If there is general agreement, I'll create a pull request.

> 1.4:
> * :thumbs up emoji:
>
> 2:
> * Shouldn't the docblock first lines be single-line? I'm totally fine with a
> much longer description block but the first line should be a short single-line
> statement.

The proposed PSR-5 section 5.1 states, "A Summary MUST contain an
abstract of the "Structural Element" defining the purpose. It is
RECOMMENDED for Summaries to span a single line or at most two but not
more than that."

As such, the only one that violates that is the class-level docblock
for MiddlewareInterface. Considering it is only a RECOMMENDATION, and
not a requirement (MUST), it's debatable whether we need to change it.

Since any such changes would be clarifications only, I'm willing to
entertain pull requests, however.

> Meta document:
>
> 6.2:
> * "external requests are typically..." External requests is a wonky word to
> use here. All requests come from something external; that's the whole point.
> "Outbound requests" seems more descriptive.

Again, a PR would be great. :)

> Otherwise, the Metadoc looks awesome!
>
> What I feel is missing is how one would assemble the handler and middleware.
> My first thought looking at the interfaces and descriptions is "wait, so a
> middleware can only take a request handler, so that means I can only stack one
> level deep? That's kinda pointless, unless an object implements both, in which
> case, erm, how's that work?"
>
> I know that the WG has discussed the assembly process to death already and has
> a good sense of how the pieces "should" be assembled, but from reading the
> specs I cannot determine what that is. Even if it's just a "one possible way"
> in the metadoc, there should be some guidance for how one actually leverages
> the interfaces in practice, although something in the spec itself would be
> helpful as well.

Considering the follow-up from John Porter, this seems to be a common
point needing clarification. I'll see if I can work up something for
the metadocument later today.

> As that would not change the spec, just clarify it, I don't believe that would
> necessitate coming out of Review state. The other comments above are all
> fairly minor.
>
> (Recall that under FIG 3 the Review state is more of a "beta", not an "RC", so
> larger changes than typos are fine as long as BC is more or less maintained.
> Nothing noted above should have any BC implications.)
>
> Overall: Aside from that additional guidance, this looks really well done.
> Nice work, everyone. Once we can get some better guidance included in one or
> the other documents this would have my vote for passage.

[Woody Gilk]

On Mon, Dec 11, 2017 at 10:15 AM, Matthew Weier O'Phinney
<mweiero...@gmail.com> wrote:
>
> > 1.3:
> > * I am not sure how I feel about the PSR-17 mention here. Clearly I agree
> > with the concept, but referencing a still not-passed PSR feels dangerous.
> > Other CC folks, your thoughts?
>
> I tend to agree here. I think we can also make a clarification change
> here that is not substantive. How about something like this:
>
> It is RECOMMENDED that any middleware or request handler that
> generates a response will either compose a prototype of a PSR-7
> ResponseInterface or a factory capable of generating a
> `ResponseInterface` instance in order to prevent dependence on a
> specific HTTP message implementation.
>
> Woody, thoughts? If there is general agreement, I'll create a pull request.

That seems like a reasonable compromise.

> >
> > What I feel is missing is how one would assemble the handler and middleware.
> > My first thought looking at the interfaces and descriptions is "wait, so a
> > middleware can only take a request handler, so that means I can only stack one
> > level deep? That's kinda pointless, unless an object implements both, in which
> > case, erm, how's that work?"
> >
> > I know that the WG has discussed the assembly process to death already and has
> > a good sense of how the pieces "should" be assembled, but from reading the
> > specs I cannot determine what that is. Even if it's just a "one possible way"
> > in the metadoc, there should be some guidance for how one actually leverages
> > the interfaces in practice, although something in the spec itself would be
> > helpful as well.
>
> Considering the follow-up from John Porter, this seems to be a common
> point needing clarification. I'll see if I can work up something for
> the metadocument later today.

I think this has been clarified by open PRs on Github.

[Larry Garfield]

On Tue, Dec 12, 2017, at 03:41 PM, Woody Gilk wrote:
> On Mon, Dec 11, 2017 at 10:15 AM, Matthew Weier O'Phinney
> <mweiero...@gmail.com> wrote:
> >
> > > 1.3:
> > > * I am not sure how I feel about the PSR-17 mention here. Clearly I agree
> > > with the concept, but referencing a still not-passed PSR feels dangerous.
> > > Other CC folks, your thoughts?
> >
> > I tend to agree here. I think we can also make a clarification change
> > here that is not substantive. How about something like this:
> >
> > It is RECOMMENDED that any middleware or request handler that
> > generates a response will either compose a prototype of a PSR-7
> > ResponseInterface or a factory capable of generating a
> > `ResponseInterface` instance in order to prevent dependence on a
> > specific HTTP message implementation.
> >
> > Woody, thoughts? If there is general agreement, I'll create a pull request.
>
> That seems like a reasonable compromise.

That resolves the issue nicely, I agree.

> > > What I feel is missing is how one would assemble the handler and middleware.
> > > My first thought looking at the interfaces and descriptions is "wait, so a
> > > middleware can only take a request handler, so that means I can only stack one
> > > level deep? That's kinda pointless, unless an object implements both, in which
> > > case, erm, how's that work?"
> > >
> > > I know that the WG has discussed the assembly process to death already and has
> > > a good sense of how the pieces "should" be assembled, but from reading the
> > > specs I cannot determine what that is. Even if it's just a "one possible way"
> > > in the metadoc, there should be some guidance for how one actually leverages
> > > the interfaces in practice, although something in the spec itself would be
> > > helpful as well.
> >
> > Considering the follow-up from John Porter, this seems to be a common
> > point needing clarification. I'll see if I can work up something for
> > the metadocument later today.
>
> I think this has been clarified by open PRs on Github.

Will discuss further on the PR, but I'm looking for something more
substantial than just a line or two.

I think that PR also missed a few of the typos I mentioned, so I'm not
sure which I should file PRs for. :-)

--Larry Garfield

[Woody Gilk]

On Tue, Dec 12, 2017 at 5:12 PM, Larry Garfield <la...@garfieldtech.com> wrote:
> On Tue, Dec 12, 2017, at 03:41 PM, Woody Gilk wrote:
>> On Mon, Dec 11, 2017 at 10:15 AM, Matthew Weier O'Phinney
>> <mweiero...@gmail.com> wrote:
>> >
>> > > 1.3:
>> > > * I am not sure how I feel about the PSR-17 mention here. Clearly I agree
>> > > with the concept, but referencing a still not-passed PSR feels dangerous.
>> > > Other CC folks, your thoughts?
>> >
>> > I tend to agree here. I think we can also make a clarification change
>> > here that is not substantive. How about something like this:
>> >
>> > It is RECOMMENDED that any middleware or request handler that
>> > generates a response will either compose a prototype of a PSR-7
>> > ResponseInterface or a factory capable of generating a
>> > `ResponseInterface` instance in order to prevent dependence on a
>> > specific HTTP message implementation.
>> >
>> > Woody, thoughts? If there is general agreement, I'll create a pull request.
>>
>> That seems like a reasonable compromise.
>
> That resolves the issue nicely, I agree.

Thanks for the word smithing, Larry. This has now been incorporated
into https://github.com/php-fig/fig-standards/pull/987

>> > > What I feel is missing is how one would assemble the handler and middleware.
>> > > My first thought looking at the interfaces and descriptions is "wait, so a
>> > > middleware can only take a request handler, so that means I can only stack one
>> > > level deep? That's kinda pointless, unless an object implements both, in which
>> > > case, erm, how's that work?"
>> > >
>> > > I know that the WG has discussed the assembly process to death already and has
>> > > a good sense of how the pieces "should" be assembled, but from reading the
>> > > specs I cannot determine what that is. Even if it's just a "one possible way"
>> > > in the metadoc, there should be some guidance for how one actually leverages
>> > > the interfaces in practice, although something in the spec itself would be
>> > > helpful as well.
>> >
>> > Considering the follow-up from John Porter, this seems to be a common
>> > point needing clarification. I'll see if I can work up something for
>> > the metadocument later today.
>>
>> I think this has been clarified by open PRs on Github.
>
> Will discuss further on the PR, but I'm looking for something more
> substantial than just a line or two.

:+1: Continuing the discussion on the PR.

> I think that PR also missed a few of the typos I mentioned, so I'm not
> sure which I should file PRs for. :-)

I'll review again, I thought I had them all.