Download the PHP package drupflare/stream-http without Composer

🌐 stream-http

An https:// stream wrapper for PHP builds that have no sockets

file_get_contents('https://...') works in a PHP-in-wasm runtime. The caller supplies the fetch; the package needs no sockets, no cURL, no OpenSSL transport and no framework.

📋 Table of Contents

• Install
• Quick Start
• Fetch Contract
• Registering From the Host
• Out of Scope
• API
• Reading Response Metadata
• Testing
• Related Repositories
• License

📥 Install

🚀 Quick Start

Nothing else is needed. fopen(), fread(), fseek(), feof(), filesize(), file_exists() and stream_get_contents() all work from that point on, for both http:// and https://.

🔌 Fetch Contract

One callable and two array shapes are the entire integration surface.

The request the wrapper builds:

The reply it accepts:

body is required, not defaulted to ''. A default would make a transport that omitted the field look like an empty 204.

🥇 Registering From the Host

A stream wrapper has to exist before any code that uses one runs. A service container is built too late for that, so a service provider or a module hook is the wrong place. In the project this was extracted from, registration happens from the JavaScript host, in worker/src/drupal/site-php.ts, around the HttpsStreamWrapper::register() call in the boot script, before Drupal's kernel exists.

🚫 Out of Scope

• It does not stream. The whole body is fetched on open and served from memory, because PHP's stream_read() is synchronous and a real streaming read would have to suspend the interpreter mid-call. A build without suspension can only fetch-then-read.
• It does not write. A write would be a POST with no way to signal completion through the stream API, so a non-r mode is refused by name and stream_write() returns 0.
• url_stat() spends no request. PHP stats speculatively, and a HEAD per stat would cost a request each time, so file_exists() answers "yes, unknown size" and filesize() on a URL nobody opened reads 0. That trade-off is pinned by an assertion rather than left to be rediscovered.

🧭 API

Why both a constructor and a static registrar. PHP constructs a registered wrapper with no arguments (stream_wrapper_register() takes the class name, not an instance), so a constructor-only design cannot work for the registered path. The static registrar is the production route; the constructor parameter is the escape hatch that makes the class drivable directly, which is how the suite exercises it without touching the wrapper registry at all.

📇 Reading Response Metadata

PHP populates $http_response_header only for its own http wrapper, and a userland wrapper cannot set it. What PHP does give you is the wrapper instance itself:

[!NOTE] This method is not called stream_metadata. That name belongs to the streamWrapper prototype, where PHP invokes it as stream_metadata(string $path, int $option, mixed $value) for touch(), chmod() and chown(). A 0-argument method under that name is an ArgumentCountError waiting for the first caller who touches an http:// path.

Every byte moves through the injected callable, so anything the wrapper cannot do refuses with a reason rather than returning a plausible empty result. A silent '' or false out of a stream function cannot be told apart from a real empty response.

PHP discards the warning text, so the reason is also readable afterwards:

Every one of these is refused by name and covered by the suite:

An explicitly empty body ('body' => '') opens normally, which is the control that keeps the six malformed-reply assertions from being vacuous.

🧪 Testing

The suite injects a recording fetch, so every request the wrapper builds is inspected and every malformed reply is scripted. No socket, no server, no wasm runtime.

A stream wrapper is resolved by method name at runtime: rename stream_read and PHP never calls it, with no error anywhere. The suite therefore drives the class through fopen(), fread() and fseek() wherever it can, rather than calling methods directly.

🔗 Related Repositories

📄 License

MIT (c) Gregory Mitchell 2026. See LICENSE.