Stdlib: get_include_path() / set_include_path() / restore_include_path() — include path stack (bootstrap)

[PurHur]

Category

stdlib | bootstrap

Problem

Zend maintains an include_path stack used by include/require and stream_resolve_include_path(). This compiler resolves literal includes via #475 / deploy root, but does not implement the standard functions to read or mutate include_path — breaking Composer-style bootstraps and php.ini parity probes.

Verified 2026-06-05: function_exists('get_include_path') → false on bin/vm.php; stream_resolve_include_path() also missing (#6051).

php-src reference

• php/php-src ext/standard/basic_functions.c — PHP_FUNCTION(get_include_path), PHP_FUNCTION(set_include_path), PHP_FUNCTION(restore_include_path)
• php/php-src main/php_open_temporary_file.c — PG(include_path) stack
• php/php-src ext/standard/streams.c — stream_resolve_include_path() (see Stdlib: stream_resolve_include_path() — include_path filename resolution missing (ext/standard/streams.c) #6051)

Repro (failure today)

<?php
foreach (['get_include_path', 'set_include_path', 'restore_include_path'] as $fn) {
    echo $fn, '=', function_exists($fn) ? 'yes' : 'no', "\n";
}
$dir = sys_get_temp_dir() . '/phpc_inc_' . getmypid();
mkdir($dir);
file_put_contents($dir . '/only_here.php', '<?php return "found";');
$old = set_include_path($dir . PATH_SEPARATOR . get_include_path());
$r = include 'only_here.php';
restore_include_path();
@unlink($dir . '/only_here.php');
@rmdir($dir);
echo "include=", var_export($r, true), "\n";

docker info >/dev/null
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php repro_include_path.php
php bin/vm.php repro_include_path.php
'

Step	Zend PHP 8.x	bin/vm.php (today)
get_include_path exists	yes	no ❌
set_include_path + include 'only_here.php'	include='found'	fatal/undefined ❌
restore_include_path pops stack	previous path restored	n/a

Scope (PHP-in-PHP)

Layer	Path
VM state	lib/VM/Context.php or Runtime — PATH_SEPARATOR-split stack, default .
Builtins	ext/standard/get_include_path.php, set_include_path.php, restore_include_path.php
Include resolver	lib/VM.php / lib/Compiler.php TYPE_INCLUDE — search stack after deploy root
Register	ext/standard/Module.php
Follow-up	#6051 stream_resolve_include_path() shares same stack
Tests	test/compliance/cases/stdlib/include_path_stack.phpt
Bootstrap	re-run php script/bootstrap-inventory.php --check after wiring

Forbidden: internal_* shims — wire real include resolution.

Done when

• Repro table: all three functions registered; include='found' on VM
• set_include_path() returns previous path string; nested calls stack correctly
• restore_include_path() pops one level; empty stack restores ini/default .
• PHPT documents interaction with PHPC_DEPLOY_ROOT / AOT: PHPC_DEPLOY_ROOT for runtime template includes in deployed binaries #585
• ./script/ci-fast.sh --filter include_path green

Verification

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

Related

• Stdlib: stream_resolve_include_path() — include_path filename resolution missing (ext/standard/streams.c) #6051 · AOT: PHPC_DEPLOY_ROOT for runtime template includes in deployed binaries #585 · Language: JIT include/require compile-time lowering (#54 follow-up) #475 · Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 (MOST IMPORTANT bootstrap)

[PurHur]

Spec refresh — implementation-ready (2026-06-01)

Repro (correct harness command)

The issue body used ./script/docker-exec.sh php bin/vm.php — use:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php -r "echo function_exists(\"get_include_path\") ? \"yes\" : \"no\", \"\\n\";"'

Observed (2026-06-01): no

Zend reference behavior

<?php
$old = set_include_path(__DIR__ . PATH_SEPARATOR . get_include_path());
var_export(get_include_path());
restore_include_path();
echo "\n", get_include_path(), "\n";

Zend restores previous path after restore_include_path().

Done when (expanded)

• get_include_path() / set_include_path() / restore_include_path() registered in ext/standard/Module.php
• include / require / include_once resolve relative paths against the stack top after deploy-root / literal resolution (Language: JIT include/require compile-time lowering (#54 follow-up) #475)
• test/compliance/cases/stdlib/include_path_stack.phpt — set → include file only on new path → restore
• php script/bootstrap-inventory.php --check still green after regen (no new blockers)
• ./script/ci-fast.sh --filter include_path green

Bootstrap gate

Required for Composer-style vendor/autoload.php paths in self-host (#1492). Blocks nothing until require paths depend on INI include_path.

Verification

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

[PurHur]

claim: PHP Runtime → PHP — starting this run (#3223: include_path_stack compliance PHPT + fix file_include_path ?? parse failure).

[PurHur]

Merged via #8006.

Verification: vendor/bin/phpunit --filter include_path → OK (12 tests). VM repro: all three include_path functions registered; include='found' after set_include_path + include + restore.

PHP-in-PHP: get_include_path/set_include_path now use BuiltinExecute::writeReturn; added include_path_stack compliance PHPTs; fixed file_include_path PHPTs (removed ?? parser gap). 0 C runtime lines changed.