PSR-7 evolution proposal for parameter and return type declarations

Skip to first unread message

Matthew Weier O'Phinney

Feb 27, 2023, 2:54:31 PM2/27/23
Hi, all!

This proposal has been a long time coming: formal addition of parameter and return type declarations for PSR-7.

I'd like to thank GitHub user @stilch for creating the patches and being patient enough to wait almost two years for me to get around to testing, reviewing, and creating the proposal.

In sum, this a proposal following our PSR Evolution bylaws ( to update PSR-7 to:

- Create a version 1.1 of the interfaces that adds parameter type declarations (see
- Create a version 2.0 of the interfaces that adds return type declarations (see

The PSR-7 spec changes can be found here:

I have tested the changes against the PSR-7 integration test suite, Diactoros, and a variety of real-world applications. For consumers, generally no changes are necessary; applications I had "just worked". For implementers, the primary change is that a fair amount of code used to validate parameter input can be removed, though in order to comply with the spec, they must also ensure that they add return type hints at the minimum for a new MAJOR version (this is documented as part of the Evolution by-laws anyways). Assuming passage of the specification, Diactoros, at the very least, can be updated within a day as I've already got patches prepared for new minor and major versions, and the changes result in a net removal of code, and fewer errors flagged by Psalm. I consider this a net win!

The other ecosystem concern will be PSR-15, PSR-17, and PSR-18. Each of these consumes PSR-7, so at the minimum, they will need to release new minor versions that allow usage of either ^1.0 or ^2.0 of the psr/http-message package. I've already notified Woody Gilk so he can track the updates.

At this point, I'm opening a 2 week comment period before calling a vote.


Woody Gilk

Feb 27, 2023, 3:16:53 PM2/27/23
As editor of PSR-15 and PSR-17, I am strongly in favor of these changes and will start work to update these PSRs when (if) the vote passes.
Woody Gilk (he/him)

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
To view this discussion on the web visit

Matthew Weier O'Phinney

Mar 6, 2023, 3:27:40 PM3/6/23
REMINDER: Discussion period ends this coming Monday, March 13, after which I'll open the vote with the CC.

We've had a few rounds of discussion and a few comments, mostly around the choice of PHP version constraints. I'm going both simultaneously less restrictive (allowing PHP 7 versions, as there are LTS versions of PHP in the ecosystem — some advocated for jumping directly to 8) and more restrictive (not doing a >= 8 constraint, but instead ^8.0, as compatibility with a new major is not guaranteed).

Please review the PRs and let me know early if you see anything glaring that should be changed before voting.
Reply all
Reply to author
0 new messages