Stdlib: pfsockopen() — persistent TCP socket streams (ext/standard/fsock.c parity)

[PurHur]

Category

stdlib | runtime

Status (expanded 2026-06-07 — implementation-ready)

Maintainer probe on master (Docker php-compiler:22.04-dev):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php -r "var_dump(function_exists(\"pfsockopen\"), function_exists(\"fsockopen\"), function_exists(\"stream_socket_client\"));"'
# bool(false) bool(false) bool(true)  — persistent opener missing; non-persistent fsockopen also absent

Workers should implement pfsockopen() on top of the existing stream_socket_client() / socket stream layer rather than new C in runtime/.

Problem

pfsockopen(string $hostname, int $port, …): resource|false opens a persistent socket stream reused across requests (CGI/FPM) or long-running scripts. Non-persistent fsockopen() is tracked in #3202; pfsockopen() is a separate php-src entry point with persistent handle caching in the stream layer.

function_exists('pfsockopen') is false under bin/vm.php.

php-src reference

• php/php-src ext/standard/fsock.c — PHP_FUNCTION(pfsockopen), php_network_connect_socket_to_host with persistent flag
• php/php-src main/streams/streams.c — php_stream_popen, persistent list keyed by proto://host:port

Repro (failure today)

<?php
$errno = 0;
$errstr = '';
$fp = @pfsockopen('127.0.0.1', 9, $errno, $errstr, 1);
var_export(is_resource($fp));
echo "\n";
if (is_resource($fp)) {
    fclose($fp);
}

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php -r "var_dump(function_exists(\"pfsockopen\"));"
php bin/vm.php repro.php
'

Runtime	Result
Zend	function_exists → true; stream resource or false + populated $errno/$errstr
This compiler VM	undefined function fatal

Scope (this repo)

Module	Path	Notes
Persistent registry	lib/VM/StreamRegistry.php or extend stream layer	process-lifetime map host:port → handle
Builtin	ext/standard/pfsockopen.php	delegate connect to shared socket helper
Shared TCP	reuse #3202 / stream_socket_client() internals	do not fork separate connect code
Registration	ext/standard/Module.php
JIT/AOT	VM-first v1; document deferral in matrix
Tests	test/compliance/cases/stdlib/pfsockopen.phpt	discard port 9 or loopback mock
php-in-php	keep stream tables in PHP (#5343 stream registry migration)	no phpc_stream.c growth

Done when

• function_exists('pfsockopen') true on VM
• Repro returns stream resource or false with $errno/$errstr like Zend
• Second call with same host/port reuses handle until fclose() (Zend subset)
• ./script/ci-fast.sh --filter pfsockopen green
• docs/capabilities.md row added

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter pfsockopen'

Dependencies

• Stdlib: fsockopen() / stream_socket_client() — TCP/UDP sockets (streams parity) #3202 — fsockopen() base (shared connect path)
• php-in-php: stream handle registry — delete phpc_stream.c (~1059 lines), FILE* table in ext/standard #5343 — stream handle registry PHP migration
• North star: Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492

[PurHur]

claim: PHP Compiler STD Lib — starting this run

[PurHur]

Merged via #7957

Implementation: ext/standard/pfsockopen.php delegates to host \pfsockopen() and adopts into VmFs; VmFs host-resource refcounting ensures duplicate persistent handles fclose() safely.

Verification (Docker):

vendor/bin/phpunit --filter PfsockopenBuiltinTest  # OK (2 tests, 4 assertions)
vendor/bin/phpunit --filter stream_socket_client_context  # OK (refcount regression)
php bin/vm.php -r 'var_dump(function_exists("pfsockopen"));'  # bool(true)