php -l Passed My Bug as a Feature: Lint Is Not a Rehearsal
Three times this month, a bug sailed through php -l with a clean bill of health. Not once did the linter lie. Every time, the bug was real, shipped, and invisible - because a syntax check answers exactly one question, and I kept asking it a different one.
Here are the three, in increasing order of embarrassment. The third one happened while I was building the tool that documents the first two.
1. The missing dot that became a function call
Building stale-asset-audit's sibling worker, I appended a JS block to a file with a string concat. Missing one dot:
$out = build_block() . $head . $tail; became, in one spot, $out = build_block()($head) . $tail;
Read that again. The missing dot between build_block() and ($head) doesn't parse as garbage - it parses as PHP 7+'s uniform variable syntax: call whatever build_block() returns, as a function, with $head as the argument. php -l shrugs. It's valid syntax. The syntax check has no idea whether the return value is callable, because that's not a syntax question.
It ships fine. It installs fine. It dies at runtime - Call to undefined function or, worse, calls something unintended - on the first request that reaches the line. Lint passed. The bug passed. Same bus.
2. The health check that silenced itself
Same week, a site-health endpoint I wrote checked whether every rack card's target file existed. First version looped over the paths and only appended rows for files that passed:
foreach ($paths as $p) { if (file_exists($p)) { $out[] = row($p, true); } }
Missing files produced no row. No row read as "nothing to report." The LED rendered green - not because everything was healthy, but because the failures were the one thing the output omitted. A missing file and a passing check rendered identically: silence.
php -l loved this file. It parsed beautifully. The bug was semantic: absence of evidence encoded as evidence of absence. The fix is the boring one - every path gets a row, and missing means an explicit false, never a gap:
foreach ($paths as $p) { $out[] = row($p, file_exists($p)); }
A monitoring surface that can't say "down" is decoration. This one would have sat green over a 404 for months.
3. The detector that detected nothing
Then I extracted stale-asset-audit itself - the tool that finds pages serving cached assets under old version keys. The very first test run reported "no drift" on a fixture with drift deliberately planted in it.
The bug: I read the version key after stripping the query string off the URL.
$url = strtok($url, '?'); // strip the query
$ver = $matches[1] ?? ''; // ...then look for ?v= in what's left
Every reference parsed as versionless. Versionless refs grouped separately from keyed refs, each group had one version, no group had two - "no drift," everywhere, forever. And php -l passed it, because it is perfectly valid PHP that computes a perfectly wrong answer.
This is the scary category. Bugs 1 and 2 fail loudly or visibly once you look. Bug 3 fails green: the tool's entire job is to say "clean" or "dirty," and it said "clean" with total confidence. A detector that detects nothing doesn't look broken. It looks finished.
The fix is one line - capture the version before stripping the query - and the fixture immediately reported the planted drift. But the lesson isn't the line. It's that the bug survived lint, survived a visual read of the code, and only died when the tool ran against bytes it hadn't seen.
The actual rule
None of this means stop running php -l. It catches real things - an unterminated string, a doubled semicolon, the self-closing comment that ate half a worker's docblock. It's fast, free, and worth it.
The rule is what php -l is for: it answers "does this parse?" Nothing else. Every process that treats a clean parse as a rehearsal - "it linted, so it works" - is betting that semantics live in syntax. They don't. They live in the data, the order of operations, and the return values, none of which the linter sees.
So: lint, then run the real file against real bytes. Not a mock. Not a dry read. The actual served input, the actual output format, checked against what you expected - with an explicit assertion for the failure case, so silence can't impersonate health. Every deploy worker I ship now gets a dry run against freshly fetched production bytes before it can touch anything, and the failures above are why. Two of the three were caught exactly that way - in rehearsal, before the server ever saw them. The third is the reason the rehearsal exists.
The production sagas behind all three live in the receipts ledger. The raw ops log is at github.com/bryanhamiltondev/deploy-log, and the tool from bug 3 is stale-asset-audit - now version-checked the correct way round.