[PHP-WASM] Expose sendmail stdin as a live event stream

[bgrgicak]

PHP can write a message to sendmail through mail(), popen(), or proc_open(), but PHP-WASM has no reusable transport for observing those bytes. This adds a sendmail-compatible null transport. It never delivers mail. It emits sendmail.spawned with raw stdin as a live ReadableStream<Uint8Array>.

Registration is explicit:

import { sendmailSpawnHandler } from '@php-wasm/util';

php.setCommandSpawnHandler('sendmail', sendmailSpawnHandler(php));
php.addEventListener('sendmail.spawned', async (event) => {
	if (event.type !== 'sendmail.spawned') {
		return;
	}
	const rawMessage = await new Response(event.stdin).arrayBuffer();
	// Parse or relay rawMessage.
});

The event fires with the first stdin chunk, before PHP finishes writing. The transport stays alive until stdin closes. Empty input exits with EX_TEMPFAIL and emits no event. Input above 20 MB errors the stream and exits with status 1. Cancelling the stream stops delivery to that reader but keeps draining stdin, so PHP can finish writing and receive the transport's exit status. There is no backpressure to PHP; a slow listener may buffer the full message.

Node tests cover mail(), proc_open(), delayed input, empty and oversized input, and runtime rotation. Browser tests cover live delivery to multiple listeners and cancellation while PHP continues writing.

This PR does not install the transport by default. #4063 installs it in remote Playground instances.

#4064 provides the marked stdin event transport and per-listener streams used here.

[akirk]

I think it'd be easier to find the code that mimicks sendmail if we put it into a spawn-handlers/sendmail.ts with the filename reflecting the command it pretends to be.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds deterministic outbound email capture for PHP-WASM by intercepting sendmail spawns and emitting email.received events, with WordPress boot registering the handler by default.

Changes:

• Introduces a sendmail command-specific spawn handler that buffers stdin and dispatches an email.received event.
• Adds per-command spawn handler routing in PHP (generic vs command-specific precedence; survives runtime rotation).
• Adds Node + WordPress integration tests covering capture behavior, error paths, and runtime rotation.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/playground/wordpress/src/test/email-capture.spec.ts	Adds a WordPress-level test asserting wp_mail() triggers email.received.
packages/playground/wordpress/src/boot.ts	Registers the sendmail command-specific spawn handler during WordPress boot.
packages/php-wasm/util/src/lib/spawn-handlers/sendmail.ts	Implements the sendmail spawn handler and defines PHPEmailReceivedEvent.
packages/php-wasm/util/src/lib/index.ts	Exports sendmail handler APIs and moves byte-concat exports to a dedicated module.
packages/php-wasm/util/src/lib/concat-bytes.ts	Adds reusable byte/ArrayBuffer concatenation helpers.
packages/php-wasm/universal/src/lib/universal-php.ts	Extends the PHPEvent union to include PHPEmailReceivedEvent.
packages/php-wasm/universal/src/lib/php.ts	Adds dispatcher-based spawn routing with command-specific overrides.
packages/php-wasm/universal/src/lib/php.spec.ts	Adds unit test coverage for the new spawn routing behavior.
packages/php-wasm/universal/src/lib/index.ts	Re-exports PHPEmailReceivedEvent type for consumers.
packages/php-wasm/node/src/test/php-email-capture.spec.ts	Adds Node runtime tests for sendmail capture, size limits, and runtime rotation.
packages/php-wasm/node/project.json	Registers the new Node test file in project test targets.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.