feat(opcache): give the OPcache surface real behaviour

[Guikingone]

Before this branch, elephc reported all 54 OPcache directives with byte-verified values and answered all 8 API functions — and almost none of it did anything. Fifteen directives now change what the program does, three shape a reported value, and the other 36 remain honest reporting.

What now exists

A runtime script cache for the one tier an AOT binary can still grow: files pulled in by dynamic include/require reached through eval(). The compile-time manifest stays frozen — that is the "the binary IS the cache" premise — so this is where an opcode-cache-shaped saving still exists. Measured on the eval-hosted include benchmark: ~20.6 ns per source byte below the old 64 KiB fragment cap, and the whole re-parse above it (a 128 KiB include cost 10.98 ms uncached against a ~0.26 ms floor).

An on-disk file cache behind opcache.file_cache, holding elephc's parsed form of those scripts, so a cold process skips the read, the <?php scan and the parse. This matters most under --web, where workers fork from a master that has executed no PHP and are recycled after --max-requests: every worker otherwise pays the re-parse continuously in production rather than once at boot.

The format was chosen by measurement, which is what rejected serde_json — it decodes a small script slower than parsing it, while bincode is 3.5–5× faster. A format_guard hashes the eval IR sources and fails the build if they change without a FORMAT_VERSION bump.

php-src's zend_accel_error channel — timestamped, pid-tagged, gated by opcache.log_verbosity_level rather than error_reporting, with a FATAL exiting 254 — and opcache.file_cache's startup refusal with it. A bad directory refuses to run, exactly as reference does.

Preloading actually preloads: opcache.preload becomes an implicit require_once at the top of the entry program, so its declarations compile in and its top-level code runs first. opcache_get_status() reports the synthetic $PRELOAD$ entry, counted in num_cached_scripts as reference counts it.

Directives that act

validate_timestamps · revalidate_freq · max_file_size · memory_consumption · max_accelerated_files · file_update_protection · blacklist_filename · file_cache · file_cache_read_only · log_verbosity_level · error_log · preload · restrict_api · enable · enable_cli

Three of them — revalidate_freq, validate_timestamps, file_update_protection — are additionally settable through ini_set(). That is the complete set php-src registers PHP_INI_ALL that elephc genuinely acts on; succeeding for the other fifteen would move a reported value while nothing changed.

How it was verified — and where that was not enough

Every rule was derived by probing reference PHP 8.5.10 rather than from memory, and the blacklist matcher was additionally compared against reference over a generated corpus of 34 paths × 26 patterns.

Twice that was still not enough, and both times a test passed while being wrong:

• The blacklist_miss_ratio formula came from a single run where hits == blacklist_misses, so two candidate denominators gave the same number. The right one is blacklist_misses * 100 / (hits + misses + blacklist_misses): php-src divides by its internal miss count, which includes blacklist misses, while the misses it reports has them subtracted back out.
• The differential corpus carried a doubled star only in trailing position, where ** and * behave identically — so it agreed while the matcher was wrong. php-src compiles * to [^/]* but ** to .*, so a doubled star does cross a separator.

A four-way model review (Fable, Kimi K3, GLM 5.3, Deepseek) produced twenty findings, six of which survived verification. The most serious was not in the matcher but in its integration: load() is emitted inside ensure_eval_context, whose guard is a function-local stack slot zeroed in every prologue — so every call of a function containing an eval() re-globbed and re-read every blacklist file. Enforced once on the bridge side, since the bridge cannot assume how often generated code calls it.

Divergences

All documented in docs/php/opcache.md.

Structural, following from compiling ahead of time: no cache growth for compiled code, no shared-memory segment, no tracing JIT, and no re-reading changed code after opcache_invalidate(). The last is the only one that changes what a program does rather than what it reports, and --strict-opcache turns it into a RuntimeException.

opcache.preload_user is deliberately not honoured. Reference runs the preload file in a privileged startup pass and uses the directive to drop out of root before executing it; elephc inlines the file, so its code runs with the privileges of whoever runs the binary and there is no boundary to drop from. The halves cannot be split either: the uid-0 fatal without the user switch would be worse than neither, since setting the directive as root would let the binary keep running as root while appearing guarded.

Pay-for-use held

This was the standing risk, since bridge calls sit inside functions every OPcache program calls. They fold away at lowering time when eval_bridge is false: a program calling opcache_get_configuration() and nothing else measures 0.13 MB against 0.05 MB for a bare program — the opcache prelude's own baked literals, not the ~1.25 MB an eval-linked binary costs.

Also fixed, unrelated to OPcache but found on the way

• libc::asctime does not exist on Linux. It broke two of the five supported targets the moment accel_log.rs was first compiled, and took four apparently unrelated CI jobs down with it. Replaced with a hand-written format_asctime, checked against the system asctime over 200,000 timestamps.
• opcache_get_status()['scripts'] reported its first entry's last_used in local time and every other entry in UTC — the helper resolved its zone from getenv('TZ') on every call, and elephc's own date_default_timezone_set() writes TZ.
• A string returned by a runtime helper and stored into a static property kept a pointer into the shared concat scratch buffer.
• implode() over a mixed-typed array segfaulted for int elements.
• A run-time promoted array was read through the packed path by some readers.

---

The pre-squash history is preserved at backup/opcache-pre-squash-20260912 if the per-commit reasoning is wanted for review; delete it once this merges.

[greptile-apps]

Too many files changed for review (187 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.