d5DetectabilityOperational debt — how invisible misuse is to your safety net
Closest to 'specialist tool catches it' (d5). The detection_hints list opcache-gui and blackfire — both specialist tools requiring deliberate instrumentation. A developer won't notice OPcache is disabled or that compilation is repeated on every request without profiling; standard linters don't flag this, but tools like blackfire will expose the parse/compile overhead in a flamegraph.
e3EffortRemediation debt — work required to fix once spotted
Closest to 'simple parameterised fix' (e3). The quick_fix describes understanding the pipeline and enabling OPcache — enabling OPcache is a config change (php.ini / opcache.enable=1) plus potentially a deployment step (cache:clear awareness). It's more than a single-line code patch but doesn't span multiple files architecturally; it's a targeted configuration correction.
b5BurdenStructural debt — long-term weight of choosing wrong
Closest to 'persistent productivity tax' (b5). The concept applies to both web and CLI contexts across all PHP 5.0+ codebases. Misunderstanding the pipeline affects OPcache configuration decisions, deployment scripts (cache:clear), JIT tuning, and how developers reason about syntax errors — a persistent tax across multiple work streams rather than isolated to one component.
t7TrapCognitive debt — how counter-intuitive correct behaviour is
Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception field is explicit: developers assume PHP is interpreted line-by-line (a belief reinforced by scripting language analogies), but PHP compiles entire files to opcodes before executing any line. This contradicts the mental model imported from truly line-by-line interpreters, leading to consequential production mistakes like disabling OPcache or misunderstanding compile-time syntax errors.
About DEBT scoring →
scored by claude-sonnet-4-6 · 2026-05-11 · reviewed by human
Source code → lexer → tokens → parser → AST → compiler → opcodes → Zend VM — OPcache intercepts after compilation to cache and reuse opcodes across requests.
Explanation
PHP execution pipeline: (1) Lexer: source text → token stream (T_FUNCTION, T_STRING, T_WHITESPACE). (2) Parser: tokens → Abstract Syntax Tree using LALR(1) grammar. (3) Compiler: AST → opcode array (zend_op structs — ZEND_ADD, ZEND_CALL, ZEND_RETURN). (4) Zend VM: executes the opcode array. OPcache intercepts after step 3: serialises compiled opcodes to shared memory — subsequent requests fetch opcodes directly, skipping steps 1-3. JIT (PHP 8.0+): OPcache's JIT further compiles hot opcodes to native x86/ARM machine code.
Common Misconception
✗ PHP is interpreted line-by-line — PHP compiles the entire file to opcodes before executing any of it; the 'interpreted' label refers to the absence of AOT native compilation, not line-by-line execution.
Why It Matters
OPcache provides 2-5x speedup by skipping lexing, parsing, and compilation on every request; syntax errors appear before any code runs (they are compilation errors); JIT helps CPU-bound code but not I/O-bound web requests.
Common Mistakes
Assuming PHP re-lexes and re-parses files on every request without OPcache
Expecting syntax errors to appear lazily at the line they are on — errors appear at compile time
Disabling OPcache in production — the single biggest PHP performance regression possible
Thinking OPcache opcodes are the same as JIT-compiled native code — they are different stages
Code Examples
✗ Vulnerable
// Expecting lazy evaluation:
if (false) {
$x = 1 +; // Syntax error on this line
}
// Assumption: no error — dead branch
// Reality: PHP compiles the entire file first
// Fatal error: parse error, unexpected ';' — before any code executes
✓ Fixed
// OPcache eliminates recompilation:
// Request 1 (cold): lex → parse → compile → store in shared memory
// Request 2 (warm): fetch opcodes from shared memory → execute directly
// Speedup: skip ~90% of compilation work per request
// Verify OPcache is working:
$status = opcache_get_status();
// Healthy production: hit rate > 99%
// opcache_hit_rate = hits / (hits + misses)
🧱FUNDAMENTALS— new to this? Start with the ground floor.
CompilergeneralA compiler is a program that translates your entire source code into machine-readable instructions before the program runs, catching errors upfront and producing an executable file.
Understanding compilation explains why some errors appear before your code runs, why compiled programs are often faster, and how tools like TypeScript catch bugs at build time rather than in production.
💡 When you see an error before your code runs, that's the compiler helping you—read the line number and fix the syntax first.
PreprocessorcompilerA preprocessor is a program that transforms your source code before the main compiler sees it, handling tasks like including files, replacing text macros, and conditionally removing code sections.
Preprocessors let you write flexible, platform-aware code and avoid repetition. Understanding this phase explains why some errors happen before your 'real' code even compiles.
💡 Always wrap macro parameters and the entire macro body in parentheses to prevent precedence surprises.
