PSR-7 compliance

[mschop]

Hi,

I am trying to write an integration between a framework (https://packagist.org/packages/phespro/phespro) and amphp http server.

Unfortunately amphp/http-server does not follow PSR-7 (https://www.php-fig.org/psr/psr-7/).

The class \Amp\Http\Server\Request does not implement \Psr\Http\Message\ServerRequestInterface

This prevents me from simply forwarding the request to the kernel of that framework (which would have been a no brainer).

Why does amphp/http-server not follow that standard? Are there any plans to support PSR-7 in the future?

Thanks in advance!

Best Regards
Martin

[trowski]

Hi @mschop!

This library does not follow PSR-7 because the interfaces do not fit well into a non-blocking application and do not fit into the eco-system we've created in Amp using components such as ReadableStream, designed for non-blocking consumption.

However, with fibers improving integration of sync and async code, providing an adaptor should be an easy task. I started this some time ago in trowski/psr-http-bridge with v2 of this library and intend to update it to v3 and port the library to this project.

Ideally, because requests may perform blocking actions, clients would be spread amongst a pool of worker processes. This is on our roadmap, likely in another library using amphp/cluster

[raghuveer]

interested to see PSR-7 support for Amphp http server

[mschop]

@trowski Could you maybe add more detail on why PSR-7 does not fit well into this kind of non-blocking application?

\Psr\Http\Message\ServerRequestInterface and \Psr\Http\Message\ResponseInterface use a stream for the body.

Btw. ReactPHP HTTP server uses PSR-7.

[mschop]

Idea:

I will use react/http for handling incoming http connections with my framework. Inside of my application I will use revolt/event-loop-adapter-react for being able to use the amphp.

Do you think this is a suitable approach, or are there any drawbacks on this approach?

[kelunik]

@mschop The doesn't fit well with non-blocking I/O is rather an argument of the past, it could work fine now. However, our current interface fits better with the amphp ecosystem, which has its own stream interface.

I'd be great if there was a proper stream interface PSR, but unfortunately, this was put into the HTTP PSR at that time and a bit too focused on the existing PHP SAPI.

You can of course also just use react/http and revolt/event-loop-adapter-react. It will be a different server implementation then and you'll loose features like HTTP/2 support, but that might not be too impoartant for an application server that's running behind a load balancer like Nginx.

We plan to eventually have a PSR-7 adpter on top of our current API, but we don't plan to make our API directly depend on PSR-7 here.

[mschop]

@kelunik Thank you for pointing out that react/http does not support HTTP/2. This is not ideal, but OK for now.

A PSR-7 adapter would be great 👍 .

[raghuveer]

We plan to eventually have a PSR-7 adpter on top of our current API, but we don't plan to make our API directly depend on PSR-7 here.

it will be really nice to have PSR-7 support through PSR-7 adapter

[luzrain]

Any news about PSR-7 adapter?

[mschop]

I just took a deeper look.

I thought about using the adapter approach, but IMO it's not a good idea. amphp would greatly benefit from being 100% PSR-7 compatible. I took a look at the classes / interfaces and don't see a reason, why it shouldn't be possible to become PSR-7 compatible.

The following abstract classes need the interfaces:

• \Amp\Http\HttpMessage should implement \Psr\Http\Message\MessageInterface
• \Amp\Http\HttpRequest should implement \Psr\Http\Message\RequestInterface
• \Amp\Http\HttpResponse should implement \Psr\Http\Message\ResponseInterface

Those are the primary aspects. There are a few incompatibilities, which would require a new major version of amphp/http. But none of them seems dramatic.

\Amp\Http\HttpMessage

Missing methods are:

    public function getProtocolVersion(): string;M

    public function withProtocolVersion(string $version): MessageInterface;

    public function getHeaderLine(string $name): string;

    public function withHeader(string $name, $value): MessageInterface;

    public function withAddedHeader(string $name, $value): MessageInterface;

    public function withoutHeader(string $name): MessageInterface;

    public function getBody(): StreamInterface:

    public function withBody(StreamInterface $body): MessageInterface;

The only incompatible method is:

Declaration of 'HttpMessage->getHeader(name: string)' must be compatible with 'MessageInterface->getHeader(name: string)'

getHeader

The getHeader method returns only the first occurrence of a header. PSR returns an array. This would be a BREAKING CHANGE!

But IMO the behavior of PSR is more consistent, so this would be a step forward.

getBody

The getBody method is incomatible (return type). Instead of using \Amp\ByteStream\ReadableStream one would require to use \Psr\Http\Message\StreamInterface. We could change the type to a intersection type with both. This would be backwards compatible and solve the problem but I am unsure, whether ReadableStream and StreamInterface are compatible.

\Amp\Http\HttpRequest

Missing methods are:

    public function getRequestTarget(): string;

    public function withRequestTarget(string $requestTarget): RequestInterface;

    public function withMethod(string $method): RequestInterface;

    public function withUri(PsrUri $uri, bool $preserveHost = false): RequestInterface;

\Amp\Http\HttpResponse

Missing methods are:

    public function getStatusCode(): int;

    public function withStatus(int $code, string $reasonPhrase = ''): ResponseInterface;

    public function getReasonPhrase(): string;

If I find the time, I will take a deeper look into it. @trowski How great are the chances, that you would accept PRs which directly adds the compatibility to the packages? Having only very little time, I would be even happier, if one of the maintainer would implement it ;-).

[mschop]

TL;DR: I'm retracting my earlier comment. Direct PSR-7 compliance doesn't work cleanly: amphp's ReadableStream and PSR-7's StreamInterface are semantically incompatible (async/forward-only vs sync/seekable), and partial compliance has no value since PSR-7 interop is binary. The honest options are either full compliance at the cost of buffering or adopting ReactPHP's unsafe clone-sharing convention, or sticking with the status quo and providing a separate bridge package (Symfony's model). I now think trowski's original position was correct.

---

I want to revise my earlier comment. After trying to implement the "just make HttpMessage/HttpRequest/HttpResponse implement the PSR-7 interfaces" approach, I hit a wall that I think is worth documenting here, because it changed my mind about the whole direction.

The real problem isn't the interfaces — it's the stream model

Adding MessageInterface/RequestInterface/ResponseInterface to the abstract classes is mostly mechanical. Headers, method, URI, status, protocol version — all of that maps fine (modulo a BC break on getHeader() returning an array, which I still think is acceptable).

The part that doesn't work is getBody() / withBody():

• PSR-7's StreamInterface is modeled on PHP's synchronous stream resources: seek, tell, rewind, eof, read(int $length): string. It quietly assumes the body is either rewindable or fully buffered (most implementations back it with php://temp, which spills to disk around 2 MB).
• amphp's ReadableStream is a forward-only async stream: read(?Cancellation): ?string, no seek, no position, fiber-cancellable.

The two read() signatures conflict: int $length vs ?Cancellation, and string return vs ?string return (where amphp uses null to signal EOF). With PHP 8 union types you can technically contort a single method to satisfy both typechecks, but you have to break one set of semantics to do it — e.g. collapse amphp's null-means-EOF into PSR-7's empty-string-means-EOF. So the "intersection type" idea I floated in the previous comment doesn't actually give you an object that behaves correctly for both contracts; one side always gets a degraded implementation.

That leaves three options, and all of them have real drawbacks:

1. Buffer the stream into memory (adapter approach)

Wrap the amphp body in an adapter that buffers chunks on demand to satisfy StreamInterface. This is what I prototyped.

Drawback: it throws away the streaming property that makes amphp useful in the first place. A 2 GB upload gets buffered to RAM the moment a PSR-7 consumer calls getContents() or __toString(). That's the exact failure mode non-blocking servers are built to avoid.

2. Do what ReactPHP does — convention over guarantees

ReactPHP does implement PSR-7 on top of async streams. The trick is that they don't actually solve the streaming/immutability mismatch; they just rely on convention:

• isSeekable() returns false for network-backed bodies.
• withX() follows the standard PSR-7 clone-based implementation pattern, which means the cloned wrapper holds the same body object reference (standard PHP shallow-clone behavior; nothing specific to ReactPHP, and not explicitly documented as a design choice).
• The unwritten rule is: middleware either passes the body through untouched, or replaces it entirely via withBody($newStream). Nobody does "clone a response and then read the body from both clones."

Drawback: the safety is unenforced. If a user does clone + read-from-both, they silently corrupt their own data — one clone gets bytes 0–N, the other gets N+1 onward, both think they read from the start. amphp's ForbidCloning on the client-side Response is specifically defending against this footgun, and removing it to get PSR-7 immutability working trades a real invariant for a convention.

3. What Symfony / Laravel do — don't implement PSR-7 natively at all

HttpFoundation response bodies are plain strings, fully buffered. StreamedResponse uses a callback and is explicitly not PSR-7. They bridge to PSR-7 via symfony/psr-http-message-bridge when a PSR-7 consumer needs one.

Drawback: it's not really a drawback so much as an admission that PSR-7 is a separate world you cross into deliberately, not your native data model.

Why PSR-7 itself is the bottleneck

PSR-7 was accepted in 2015, years before fibers (PHP 8.1, 2021) made async PHP mainstream. The StreamInterface reflects that era: sync read API, no cancellation, no backpressure, seek/tell as first-class operations.

The closest PHP-FIG has come to addressing async on the HTTP side is PSR-18 (HTTP client), whose meta document is explicit:

"Support for asynchronous HTTP requests is left for another future PSR."

"The reason asynchronous requests are not covered by this PSR is the lack of a common standard for Promises. Promises are sufficiently complex enough that they deserve their own specification, and should not be wrapped into this one."

"A separate interface for asynchronous requests can be defined in a separate PSR once a Promise PSR is accepted."

No Promise PSR exists, and no async-HTTP PSR is in flight. There is no "PSR-7 v3" on the roadmap. Relevant references:

• PSR-7 spec and meta document
• PSR-18 meta document — source of the quotes above
• php-fig/http-message — current latest is 2.0 (adds return-type declarations on top of 1.1's argument types); no async-aware successor
• PHP Fibers RFC — fibers exist as a language mechanism, but PHP-FIG has not (to my knowledge) published a position on using them to retrofit async semantics onto PSR-7

In other words: the interfaces we'd need to match async land cleanly (cancellation, first-class forward-only semantics, clone semantics for non-rewindable bodies, backpressure hooks) don't exist and aren't coming soon.

Revised conclusion

I'm retracting my earlier pitch. The value of PSR-7 compatibility is entirely binary: either $request instanceof RequestInterface is true and you can hand the object to any PSR-7 consumer, or it isn't and there's no point. "Compliant on headers and status but not on the body" doesn't let anyone pass an amphp Request to a PSR-7 middleware — which was the whole reason to do this. Partial compliance delivers no interoperability and only adds API surface.

So the options collapse to two honest answers:

• Full compliance, pick your poison: either buffer (lose the streaming property that makes amphp valuable), or adopt the ReactPHP convention (keep streaming, accept the silent-corruption footgun on clone-and-read). Either way implements MessageInterface holds and objects are interchangeable with PSR-7 consumers.
• Don't implement PSR-7 at all — which is where amphp already is. Users who need PSR-7 handoff use a separate, explicit adapter / converter library (same pattern as symfony/psr-http-message-bridge), so the cost is visible at the call site rather than hidden behind an interface claim.

Given that PSR-7 was designed for a sync/buffered world and there's no async-aware successor on the PHP-FIG roadmap, I now think trowski's original position was correct, and my earlier comment was wrong. The interfaces genuinely don't fit, and forcing them to fit costs more than it buys. An external bridge package is the cleaner answer.

Sorry for the noise — wanted to close the loop with a correction rather than leave the earlier comment sitting as the last word.

[Bilge]

tl;dr:

This library does not follow PSR-7 because the interfaces do not fit well into a non-blocking application