[lonnieezell]

Description
Fixes #10615

Without config caching, and on every request in FrankenPHP Worker Mode, BaseConfig::__construct() checks every leaf property against the environment. That is 8 failed array_key_exists() calls plus 4 failed getenv() calls per leaf, even though most properties have no override.

This PR indexes the environment once and reuses it:

• Index: $_ENV, $_SERVER and getenv() are grouped by the text before their first . or _. Each class only looks at the keys that match its short or full prefix. A leaf is skipped unless one of its 4 candidate names exists.
• Freshness: the index keeps a [$_ENV, $_SERVER] snapshot and is rebuilt when either changes (once per request in Worker Mode) or on BaseConfig::reset(). Copy-on-write makes the unchanged check cheap.
• Names getenv() doesn't list: PHP's getenv() array, $_ENV and $_SERVER all leave out OS env var names containing ., a space or [. For example, app.baseURL set through Docker or systemd is only readable with getenv('app.baseURL'). These names are probed with getenv() the first time each leaf is seen. Only the names that exist are cached for the process, and their values are re-read on every build, so changed or removed values are never reused. Leaves that first appear on a later instance (for example, added by a constructor or registrar) are probed then. Leaves are only walked again when a class's property values change since its last build. That check is cheap because unchanged arrays share memory. This is the main difference from the issue's proposal, which would have dropped these names.
• Case-insensitive getenv(): on Windows, and under Apache mod_php (where getenv() reads SetEnv vars, so SetEnv APP_BASEURL matches app_baseURL), only live getenv() calls match names case-insensitively. There the underscore forms are probed live too. This also applies to any SAPI not known to match exactly. The known-exact SAPIs are cli, phpdbg, cli-server, fpm-fcgi and frankenphp: their live getenv() only finds exact names that are also in $_SERVER or the getenv() array, so they skip this step and avoid doubling the getenv() calls on a cold build.
• Custom hooks: classes that override getEnvValue() or initEnvValue() keep the previous live lookups. This is detected with reflection once per class.
• Precedence is unchanged: short prefix over full prefix, $_ENV over $_SERVER over getenv(), dot form over underscore form, and arrays only accept existing keys. getEnvValue() and the new path now share a single lookup.

There is no new public or protected API.

Behavior change (listed in the changelog and upgrade_480.rst):

A bare putenv(), without a matching $_ENV/$_SERVER write, that adds a new name after the first config class was built may not be seen until BaseConfig::reset() runs. Values from .env are unaffected, because DotEnv also writes $_ENV and $_SERVER.

Benchmark

Time to build the 20 core config classes from the issue: PHP 8.3.23 CLI on macOS, OPcache off, testing environment. Warm rows are the median of 9 rounds of 500 builds. Cold rows are the median of 41 fresh processes, each timing its first build after autoloading and Registrar discovery. "5 overrides" means app.baseURL plus four database.default.* keys in $_ENV, $_SERVER and putenv().

Scenario	Before	After	Saved
Warm, no overrides, $_SERVER changes per build (Worker Mode)	0.462 ms	0.077 ms	83%
Warm, no overrides, environment unchanged	0.463 ms	0.034 ms	93%
Warm, 5 overrides, $_SERVER changes per build	0.475 ms	0.117 ms	75%
Warm, 5 overrides, environment unchanged	0.474 ms	0.071 ms	85%
Cold first build, no overrides (classic per-process request)	0.503 ms	0.257 ms	49%
Cold first build, 5 overrides	0.506 ms	0.306 ms	40%

Each figure is the average of two back-to-back before/after rounds. These figures are for the CLI SAPI on macOS. On Windows, and under Apache mod_php or other SAPIs outside the known-exact list, a cold build makes 4 getenv() calls per leaf instead of 2.

The cold gain is smaller because each class's first build still makes 2 getenv() calls per leaf for the names that getenv() doesn't list. I also tried keeping live getenv() calls for those names on every build instead of caching them. That came out slower than the current code (about 0.59 ms), so the per-process cache is needed. Requests served from config caching (FactoriesCache) already skip this work and gain nothing.

Benchmark scripts

Warm (php bench-config-env.php /path/to/CodeIgniter4):

<?php

// Usage: php bench-config-env.php /path/to/CodeIgniter4
// Times building 20 core config classes under three scenarios.

chdir($argv[1]);
require 'system/Test/bootstrap.php';

use CodeIgniter\Config\BaseConfig;

$classes = [
    Config\App::class, Config\Database::class, Config\Mimes::class, Config\Cache::class,
    Config\Logger::class, Config\Security::class, Config\Session::class, Config\Cookie::class,
    Config\Filters::class, Config\Routing::class, Config\Toolbar::class, Config\Email::class,
    Config\Exceptions::class, Config\Paths::class, Config\Kint::class, Config\Format::class,
    Config\Validation::class, Config\View::class, Config\Feature::class, Config\Encryption::class,
];

$overrides = [
    'app.baseURL'                => 'https://example.com/',
    'database.default.hostname'  => 'db',
    'database.default.database'  => 'ci4',
    'database.default.username'  => 'root',
    'database.default.password'  => 'secret',
];

// Warm up autoloading and registrar discovery.
foreach ($classes as $class) {
    new $class();
}

function bench(array $classes, bool $touchServer): float
{
    $iterations = 500;
    $start      = hrtime(true);

    for ($i = 0; $i < $iterations; $i++) {
        if ($touchServer) {
            // Simulates a new request: $_SERVER changes, as in Worker Mode.
            $_SERVER['REQUEST_TIME_FLOAT'] = $i;
        }

        foreach ($classes as $class) {
            new $class();
        }
    }

    return (hrtime(true) - $start) / $iterations / 1e6;
}

function median(callable $fn): float
{
    $runs = [];

    for ($r = 0; $r < 9; $r++) {
        $runs[] = $fn();
    }

    sort($runs);

    return $runs[4];
}

$results = [];

$results['No overrides, $_SERVER changes per iteration'] = median(static fn () => bench($classes, true));
$results['No overrides, environment unchanged']           = median(static fn () => bench($classes, false));

foreach ($overrides as $key => $value) {
    putenv("{$key}={$value}");
    $_ENV[$key]    = $value;
    $_SERVER[$key] = $value;
}

$results['Typical overrides, $_SERVER changes per iteration'] = median(static fn () => bench($classes, true));
$results['Typical overrides, environment unchanged']           = median(static fn () => bench($classes, false));

// Sanity check that overrides are applied.
if ((new Config\Database())->default['hostname'] !== 'db' || (new Config\App())->baseURL !== 'https://example.com/') {
    fwrite(STDERR, "Overrides not applied!\n");

    exit(1);
}

foreach ($results as $label => $ms) {
    printf("%-52s %.4f ms\n", $label, $ms);
}

Cold (php bench-cold.php /path/to/CodeIgniter4 [overrides], run 41 times and take the median):

<?php

// Usage: php bench-cold.php /path/to/CodeIgniter4 [overrides]
// Times the first build of 20 config classes in a fresh process
// (classic per-request PHP without config caching).

chdir($argv[1]);
require 'system/Test/bootstrap.php';

$classes = [
    Config\App::class, Config\Database::class, Config\Mimes::class, Config\Cache::class,
    Config\Logger::class, Config\Security::class, Config\Session::class, Config\Cookie::class,
    Config\Filters::class, Config\Routing::class, Config\Toolbar::class, Config\Email::class,
    Config\Exceptions::class, Config\Paths::class, Config\Kint::class, Config\Format::class,
    Config\Validation::class, Config\View::class, Config\Feature::class, Config\Encryption::class,
];

if (($argv[2] ?? '') === 'overrides') {
    foreach ([
        'app.baseURL'               => 'https://example.com/',
        'database.default.hostname' => 'db',
        'database.default.database' => 'ci4',
        'database.default.username' => 'root',
        'database.default.password' => 'secret',
    ] as $key => $value) {
        putenv("{$key}={$value}");
        $_ENV[$key]    = $value;
        $_SERVER[$key] = $value;
    }
}

// Autoload the classes and run registrar discovery outside the timing.
foreach ($classes as $class) {
    class_exists($class);
}
new Config\Pager();

$start = hrtime(true);

foreach ($classes as $class) {
    new $class();
}

echo (hrtime(true) - $start) / 1e6, "\n";

Tests

New tests in BaseConfigTest cover:

• $_ENV/$_SERVER writes after a build being picked up
• reset() picking up a bare putenv()
• overridden hooks still being called with live getenv()
• class names containing _
• the precedence matrix
• array keys
• an OS-only name containing a space
• a removed getenv()-only value not being reused
• an OS-only override for an array leaf that first appears on a later instance

The full suite has the same failures as plain 4.8 locally: SQLSRV and Predis are unavailable, and a few FeatureTestTrait tests fail only when run in the full suite.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage (tests added; coverage not measured locally, no coverage driver)
• User guide updated
• Conforms to style guide

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The per-class cache can silently miss existing OS-only overrides for array leaves introduced by later instances.

1 open issue

• Refresh cached environment overrides for newly encountered array leaves · New

What changed in this PR

Optimizes config construction for the 4.8 release by reusing an environment index, addressing #10615’s repeated lookup costs without config caching and in Worker Mode.

Changes:

• Adds indexed environment lookups, snapshot-based refresh, and live-lookup fallback for custom hooks.
• Adds regression coverage for precedence, refresh behavior, array keys, and unusual environment names.
• Documents changes to late putenv() updates and Windows case sensitivity.

Validation was limited to targeted source inspection; runtime tests remain for CI.

File	Description
user_guide_src/​source/​installation/​upgrade_480.rst	Explains environment lookup behavior changes.
user_guide_src/​source/​changelogs/​v4.8.0.rst	Records the optimization and compatibility notes.
tests/​system/​Config/​fixtures/​Snake_Config.php	Provides an underscore-containing class name fixture.
tests/​system/​Config/​fixtures/​EnvIndexConfig.php	Provides scalar and array override fixtures.
tests/​system/​Config/​fixtures/​CustomEnvHookConfig.php	Provides a custom environment hook fixture.
tests/​system/​Config/​BaseConfigTest.php	Tests indexed lookup behavior and precedence.
system/​Config/​BaseConfig.php	Implements indexing, caching, and shared lookup logic.

_{Review effort: Balanced}

[michalsn]

One last thing: in Worker Mode, the cache persists across requests, so changes made with putenv() alone may not appear in subsequently built config instances. Could we clarify this in the existing upgrade note, including that the limitation also affects updates and removals, not just newly added variables?

[lonnieezell]

Thanks, done in 348bcca. The upgrade note now says the limitation applies whether a variable is added, changed, or removed, and that in Worker Mode the cache persists across requests. It also gives the workaround: also set or unset the value in $_ENV, or call BaseConfig::reset(). The 4.8.0 changelog entry says the same in short form.

A correction to my earlier reply: changed or removed values are only re-read when $_ENV or $_SERVER changes too, which is what testRemovedGetenvOnlyNameIsNotReused does. Underscore names found in the getenv() array keep their cached value after a bare putenv(), so you're right that updates and removals are affected as well.