Deploying PHP in a Bomb Suit: Token-Gated One-Shot Workers on $3 Shared Hosting

Deploying PHP in a Bomb Suit: Token-Gated One-Shot Workers on $3 Shared Hosting

BackerLeader ●1 ●5 ●33
calendar_today ago • schedule4 min read

Deploying PHP in a Bomb Suit: Token-Gated One-Shot Workers on $3 Shared Hosting
My last post, "Dead at File 30 of 62," was about making self-deleting scripts interrupt-safe. The reaction was great, but every comment thread had the same undertone: cool hack, but why are you deploying like this at all?

Fair question. This is the follow-up nobody asked for and everybody on shared hosting needs.

The problem
I run two production sites on shared cPanel hosting. No SSH. No CI. No git pull on the box. No staging environment. You get: a file manager, an FTP client, and a MySQL wizard. That's the whole toolbox.

The naive workflow is: edit file locally, upload, refresh browser, pray. On a 300KB PHP homepage with 99 artist pages, that means every deploy is a full-file overwrite. One stale local copy, one mis-pasted brace, and you've taken down production. I know because I did it. Twice.

So I stopped uploading source files. Now I upload surgeons.

The pattern: guarded one-shot workers
A worker is a single PHP file I upload to public_html that performs one narrowly-scoped patch, verifies its own work, backs itself up, and (usually) deletes itself. The rules:

  1. Token-gated, dry-run by default. The worker does nothing unless you hit it with a secret in the query string, and even then it only reports what it would do until you pass &go=1:

php

$TOKEN = 'djc-XXXX'; // random, per-worker, never reused
if (($_GET['t'] ?? '') !== $TOKEN) { http_response_code(404); exit; }
$APPLY = isset($_GET['go']);
Why the token? Because shared hosting means your public_html is web-accessible, and a self-modifying script that any crawler can trigger is a self-own waiting to happen. The token check is also why the worker can live at the web root, which matters (more on that below).
  1. Needles, not replaces. A worker never overwrites a whole file. It reads the live file from disk, finds a unique byte-exact needle around the change, and either injects after it or swaps the exact needle for an exact replacement. If the needle appears twice, or zero times, the worker aborts with a report instead of guessing:

php

$src = file_get_contents($path);
$needle = 'id="hero-deck"';
$n = substr_count($src, $needle);
if ($n !== 1) { exit("ABORT: needle found $n times (need exactly 1)"); }
$out = str_replace($needle, $needle . $payload, $src);

This is the difference between a patch and an overwrite. Overwrites don't compose. Patches do.

  1. A syntax gate before anything writes. If the worker generates or modifies PHP, it lints the candidate string before it touches disk. No php -l on shared hosting? Include the candidate in a scratch context and let the parser be the judge — or run the whole candidate through a closure-compile check. Whatever your flavor: no write happens until the code provably parses. A broken write on a shared host isn't a rollback away; it's a support ticket away.

  2. Byte-exact idempotency. Workers must be safe to run twice, because you will run them twice (LiteSpeed will serve you a cached page and you'll think it failed — more on that too). The cheap version: record the byte size of the file after the patch, and refuse to re-patch if the live file already matches:

php

if (filesize($path) === $EXPECTED_BYTES) { exit("ALREADY APPLIED"); } The paranoid version: check for the payload's marker string first. Do both. Markers lie less than sizes.
  1. Backups that outlive the worker. Before every write, the original goes to .bak-<worker-id>.bak on disk. The worker deletes itself; it never deletes its backups. When you're debugging three weeks later and the homepage is 4 bytes short of what you expect, those backups are the only archaeology you get.

  2. Self-deletion, interrupt-safe. And here's where the last post comes in. The worker's final act is deleting itself. But the naive version — unlink(FILE) as the last line, after all the echo output — has a failure mode: if execution dies at file 30 of 62, the worker stays behind, armed, live at a public URL, capable of running its patch again with no warning. The fix is to schedule the deletion before the work: unlink early (the file is already fully loaded into the OPcache/memory by then), do the work after. Then a mid-run crash leaves you with a half-patched file and no live gun on the web root.

  3. Verify against the served page, not the disk. After a worker reports success, I curl the live URL with a cache-buster (?v= + timestamp) and grep for the marker. This has caught more silent failures than anything else:

LiteSpeed served a 5-minute-cached page that didn't have the patch (disk fine, served stale)
an opcache held a stale compile (disk fine, served stale) — fix: a second one-line worker that calls opcache_reset()
a patch landed in a subdirectory that turned out to 404 on this host — workers live at the web root for a reason
Disk truth and served truth are different truths. Only one of them is production.

Why not just... get a VPS like a normal person?
Honestly? Partly cost, mostly honesty. I like that my deploy pipeline is a PHP file I can read end to end. There's no build step between me and production, no agent, no runner, no YAML. The worker pattern gives back the three things shared hosting takes away: safety (needles + gates + backups), repeatability (idempotency + self-verification), and blast-radius control (one file, one job, one death).

The other part is that constraints are a feature for a side project. A pattern that survives $3 hosting survives anything.

The checklist, condensed
If you steal one thing, steal this pre-flight list:

  1. Unique token, dry-run default, &go=1 to apply
  2. Needle must appear exactly once, else abort
  3. Lint before write
  4. Marker check + byte-size check for idempotency
  5. Backup with a dated suffix, never cleaned by the worker
  6. Unlink itself before the patch, not after
  7. Verify the served URL with a cache-buster, not the disk
  8. Keep the .bak files until you've personally eyeballed the feature

That's the whole religion. Eight commandments, zero cron jobs, zero YAML.

If you want to see the pattern in the wild, my live site runs on it — and the previous post covers the self-deletion mechanics in detail: "Dead at File 30 of 62: Making Self-Deleting Scripts Interrupt-Safe."

12 Comments

1 vote
1
1
1
0
2 votes
0
0
0
🔥 Join developers growing publicly
Share your knowledge, build in public, and grow your developer presence with a global community.

More Posts

Delivering Database Changes

Steve Fentonverified - Jul 22

Your AI Agent Doesn't Need Your Token: Edera's Ariadne Conill on Object Capabilities

Tom Smithverified - Nov 5

A Textile Mill's Dyehouse Ramp Curve: Get One Step Wrong and the Sheet Belongs to the Master

aiomniu - Oct 18

Cloudflare Blocked My Server, So I Made My Visitors' Browsers Do the Fetching

bryanhamiltondevverified - Nov 15

Escaping Cache Fragmentation: How Misconfigured PHP Workers Flooded My Token System

Rahim8050 - Mar 22
chevron_left
2.4k Points • 39 Badges
Rochelle Park, New Jersey, US • bryanhamilton.info
17Posts
18Comments
19Connections
Full-stack web engineer · PHP & vanilla JS · 25+ years · Founder of The DJ Calendar · Open to work

Related Jobs

View all jobs →

Commenters (This Week)

2 comments
1 comment
1 comment

Contribute meaningful comments to climb the leaderboard and earn badges!