DEV Community: Mohamed

A five-file Laravel release when the production worktree has drifted

Mohamed — Mon, 12 Oct 2026 01:01:58 +0000

On 5 October I shipped a design refresh to the storefront I run: one stylesheet and four Blade templates, the hero, catalog, operations and homepage views. Nothing else moved. No migrations, no seeding, no dependency changes, no database edits.

The interesting part was not the design. It was that the production worktree was not in the state my branch said it should be in, and I did not want a whole-branch deployment to decide what those files became.

Why not a normal git deploy

The production checkout was at a different commit from my working copy. Its stylesheet carried a hash that I had pinned from an inspected snapshot, not derived from a commit. The production branch was left unchanged on purpose, because this was a scoped release over an existing production worktree.

So the release became a list of five paths, each with a before_sha256 and an after_sha256, written into a manifest. The local release script refuses to build the payload unless the four production templates match the committed versions in my source checkout and the stylesheet matches the hash I inspected. If either check fails, nothing is uploaded.

The payload is a tar of exactly those five files, and the manifest records the production commit hash, the source commit hash, and the two digests per file.

What `apply` checks before it writes anything

The remote script takes one of three modes: apply, verify or rollback. Everything runs inside an exclusive, non-blocking file lock, so a second release on the same checkout fails immediately instead of queueing. It is a file lock on one machine, which means it serialises releases on that host and nothing beyond it.

apply runs a chain of refusals before it touches a file:

If a backup.json already exists in the release directory, the release was already attempted and the script stops; a retry needs a new release directory.
Production HEAD must equal the commit recorded in the manifest.
Every target file's current hash must equal its before_sha256.
Every tar member must be a regular file named in the manifest; anything else aborts.
The set of members must equal the set of manifest entries, or the payload is incomplete.
Each member's content must hash to its after_sha256.
Plain .php files get php -l; .blade.php files are skipped. In this release the lint step did nothing, since the five files were Blade templates and a stylesheet.

Target paths are also checked: no absolute paths, no .. segments, no symlinks anywhere between the root and the file.

Only then does it back up each original together with its file mode, write backup.json, and record the phase in state.txt.

The write itself

Each file is written through one small function:

def atomic_write(p, data, permissions):
    p.parent.mkdir(parents=True, exist_ok=True, mode=0o755)
    temporary = p.with_name(p.name + '.storefront-release-tmp')
    created = False
    try:
        with temporary.open('xb') as out:
            created = True
            out.write(data)
            out.flush()
            os.fsync(out.fileno())
        os.chmod(temporary, permissions)
        os.replace(temporary, p)
    finally:
        if created:
            with contextlib.suppress(FileNotFoundError):
                temporary.unlink()

The temp file lives in the same directory as the target so os.replace is a rename on the same filesystem. A reader sees either the old file or the new one, never a half-written one.

Right before each write, the script hashes the target again. The pre-flight check already passed, but the backup step and the write step are separate moments, and the error for this case is named for what it means:

if digest(target(rel)) != entries[rel]['before_sha256']:
    raise RuntimeError('Concurrent production edit: ' + rel)
atomic_write(target(rel), payload[rel], saved[rel]['mode'])

After the five writes it runs php artisan config:cache and php artisan view:cache, logging both to a file in the release directory and raising on a non-zero exit. As the Laravel deployment docs describe them, config:cache combines the configuration files into a single cached file and view:cache precompiles the Blade views so they are not compiled on demand.

Then it hashes every file one more time and compares against after_sha256. Only if that passes does it write applied-awaiting-fpm-reload to state.txt and print reload php8.5-fpm.

Rollback is guarded the same way

Any exception inside the apply block triggers a rollback, and the exception is re-raised afterwards so the failure is still visible.

Rollback refuses to overwrite a file whose current hash is neither the before hash nor the after hash:

for rel, item in entries.items():
    current = digest(target(rel))
    if current not in (item['before_sha256'], item['after_sha256']):
        raise RuntimeError('Concurrent edit; refusing rollback overwrite: ' + rel)

That rule matters more than it looks. A rollback that blindly restores the backup would be a second way to lose a change made outside the release, which is the exact thing the whole release was built to avoid. Each backup is hashed against before_sha256 before it is restored, restored with the saved mode, and the caches are rebuilt again.

FPM reload is a separate step

The remote script does not reload PHP-FPM. The local driver runs the reload after apply, checks the service is active, and only then calls verify, which re-hashes the five files against after_sha256. The log for this release shows the backup, both cache rebuilds, the five applied files, active, and verified_files: 5.

The release reloads FPM rather than waiting on timestamp validation. The PHP manual says that with opcache.validate_timestamps disabled you must reset OPcache or restart the web server for changes to the filesystem to take effect.

The read-only browser check

Hash verification proves the bytes landed. It does not prove the pages render. So the last step is a Playwright script that is deliberately unable to submit anything.

await page.route('**/*', route => {
  const request = route.request(), url = new URL(request.url());
  if (request.method() !== 'GET' && request.method() !== 'HEAD') return route.abort();
  if (!['seosellers.com', 'www.seosellers.com',
        'fonts.googleapis.com', 'fonts.gstatic.com'].includes(url.hostname)) return route.abort();
  return route.continue();
});

Every request that is not GET or HEAD is aborted, and every request to a host other than the site or Google Fonts is aborted. Form submissions and third-party tracking cannot fire from inside the check.

It visits 14 public routes at 1440px and 390px, which is 28 renders. Each one must return HTTP 200, contain exactly one h1, have no horizontal overflow, no broken images, no uncaught page errors, and a _token field on every POST form. Images are forced to eager loading and decoded, and fonts are awaited, before the measurements are taken.

On the homepage it goes further: clicking the pages filter must leave exactly one visible product card, and at 390px the mobile menu must open and then close on Escape. Every result is written to a JSON file next to the screenshots. All 28 passed.

What this release did not prove

Live payment and mail delivery were not exercised. The git branch was not updated, so the next full deployment from the branch must carry these five changes or it will undo the design; that is a debt, and it is written in the release notes so it is not forgotten.

The hashes pin a moment, not correctness. They prove the file on disk is the file I inspected, before and after. Whether that file is right is what the local tests, 50 of them with 382 assertions, and the 28 browser renders are for.

The writes are atomic per file, not for the whole release. A request can see a mixture of old and new files while the five replacements are in progress.

And the lock is per host. It serialises releases that go through this script on that machine. The hash checks detect changes present when they run, but an editor that ignores the lock can still write between a check and a replacement. The script reduces that risk; it does not eliminate the race.

I build and run SEOSellers, a platform that publishes pages for other people's businesses; this release was its storefront.

Laravel: the homepage worked, but every slug returned 404

Mohamed — Wed, 23 Sep 2026 13:01:54 +0000

The home page on a custom domain loaded. Every page at /<slug> returned 404.

The domain resolved, the root route worked, and the page records existed. Those symptoms can make a routing bug look like a missing-content problem.

The route was this shape:

Route::domain('{customDomain}')->group(function () {
    Route::get('/{slug}', [LandingPageController::class, 'customShow']);
});

The missing detail was in the controller signature. {customDomain} is a route parameter too, and it arrives before {slug}. A method shaped like this leaves no argument for the domain:

public function customShow(Request $request, string $slug)

For a request to https://client.example/services, the route supplies client.example and then services. With that signature, $slug receives client.example. Looking up a page with the host as its slug returns nothing, so the request ends in a 404.

The fix was to account for both parameters. Here's the relevant part of the method:

public function customShow(Request $request, string $customDomain, string $slug)
{
    $host = $request->getHost();

    $page = LandingPage::where('host', $host)
        ->where('slug', $slug)
        ->where('is_published', true)
        ->first();

    // Render the page or continue with the site's normal fallback.
}

The method reads the host from the request because that's the value it uses for the lookup. The $customDomain argument still has to occupy its place so $slug receives the path segment.

What made this hard to notice was the passing home page. / uses a different controller method and has no slug to misplace. It proved the domain was reachable, but it didn't prove nested pages worked.

The regression test seeds a home page and a separate service page on the same host, then makes both requests:

$this->get('http://poolco.example.test/')
    ->assertOk()
    ->assertSee('Welcome To The Pool Co Home', false);

$this->get('http://poolco.example.test/deep-service-page')
    ->assertOk()
    ->assertSee('The Deep Service Landing Page', false);

Checking the content matters too. A 200 response from a fallback page wouldn't prove that the requested slug reached the right page.

When a Laravel route is bound to Route::domain('{something}'), I now count the domain placeholder while matching route parameters to a controller signature. It is easy to forget because it isn't visible in the path.

I build and run SEOSellers. This issue came from its custom-domain page routing.

A logo at 1.00:1 contrast passed every check we had

Mohamed — Fri, 18 Sep 2026 23:01:56 +0000

I run a service that publishes landing pages for other people's brands. Every page
gets the client's own logo in the header bar, and the bar comes in three colours:
white, the brand colour, or a neutral dark.

Picking the bar looked like the most trivial decision in the system. It produced
a bug that is invisible to every signal you would normally trust. The page renders.
The logo file is served. Every other gate is green. And half the client's name is
not there.

The case that broke the naive version

A client wordmark, transparent PNG: the word in white, a second word in the brand
blue, hyphen between them.

On the brand-blue bar, the blue word measured 1.15:1. Gone.
On the white bar, the white word measured 1.00:1. Perfectly gone.

Two bars, and each one erased a different half of the same logo. There was no
correct answer in the set, which is how the neutral third bar got built.

That is the first lesson: with two options it is easy to find one that scores
acceptably on average, and averages are exactly the wrong statistic here.

Why average contrast is the wrong measurement

The obvious implementation is: composite the logo over the bar, compute contrast
per pixel, average it, pick the winner.

It fails because it cannot tell these two situations apart:

A whole word vanished.
A faint interior highlight faded.

Both remove a similar quantity of low-contrast ink. Only one is a defect. Average
them into a single number and the word disappearing looks like a mild dip.

The difference is not in how much ink is lost, it is in where:

A word owns its horizontal slice of the mark — nothing else is in those columns.
A lost interior detail shares its columns with ink that still reads.

So you stop measuring pixels and start measuring columns.

The implementation

Composite over the bar (alpha included — this is what the eye actually receives),
then slice the mark's bounding box into full-height columns and ask which ones went
dark:

VIS_COLS         = 16     # full-height column slices across the mark's bbox
VIS_COL_MIN_INK  = 0.015  # a column holding <1.5% of total ink is noise, never judged
VIS_COL_LOST     = 0.12   # a judged column keeping <12% of its ink readable is a hole
VIS_MAX_LOST_INK = 0.15   # legible iff hole ink is <=15% of the mark...
VIS_MIN_VISIBLE  = 0.25   # ...and >=25% of all ink is CRISP overall

for y in range(h):
    for x in range(w):
        r, g, b, a = px[x, y]
        if a < 25:
            continue
        # What the eye gets: the pixel alpha-composited over the bar.
        f = a / 255.0
        comp = (r * f + bar[0] * (1 - f),
                g * f + bar[1] * (1 - f),
                b * f + bar[2] * (1 - f))
        c = contrast(comp, bar)
        ink.append((x, c >= INK_MIN_CONTRAST, c >= VIS_READABLE_FLOOR))

Then bucket that ink by column and flag the holes:

lost_ink = sum(tot for tot, seen in cols.values()
               if tot >= VIS_COL_MIN_INK * total_ink   # ignore noise columns
               and seen / tot < VIS_COL_LOST)          # this column went dark

Whitespace never enters the calculation — a column with no ink simply isn't there.
The VIS_COL_MIN_INK floor handles the case that is left: a column holding a few
stray anti-aliased pixels, where two of them fading would otherwise read as a hole.

WCAG 3:1 is the wrong floor here

My first threshold was WCAG's 3.0:1 for non-text contrast. It rejected logos that
were obviously fine on screen: a solid green icon at ~2.1:1, an orange one at
~2.2:1. Both perfectly readable.

WCAG's 3:1 is calibrated for thin UI strokes. A chunky solid mark carries far
more ink per glyph and survives well below it. So the floor is two-tier:

VIS_READABLE_FLOOR = 1.8

A column only counts as lost when its ink cannot manage even 1.8:1 — truly gone
(white-on-white at 1.00, blue-on-blue at 1.15), not merely muted. The separate
"crisp" share still uses the strict threshold, so a muted mark scores low without
being failed outright.

Every threshold in that block is pinned by a calibration test against real rendered
headers. When you are hand-tuning constants against human perception, the test suite
is the only thing standing between you and re-breaking it in three months.

Opaque logos ask a completely different question

This part is counter-intuitive.

Everything above applies to transparent logos, where the bar shows through and
the question is can I still read the ink.

An opaque logo — one with its own baked-in background plate — is legible on
every bar by construction. The ink question is meaningless. The real question is
whether the bar matches the plate, because if it does not, the logo renders as
a visible pasted rectangle sitting on your header.

Judging an opaque logo by ink contrast doesn't merely fail to help. It actively
selects the wrong bar, because maximum ink contrast is often precisely the bar that
clashes hardest with the plate.

Three logo shapes, three different questions:

Logo	Question	Failure mode
Transparent	Does the ink survive the bar?	A word disappears
Opaque	Does the bar match the plate?	A pasted rectangle
None	—	Text wordmark, safe by construction

The takeaway

The reason I keep coming back to this one: it is a whole category of bug where
every automated signal is green and the output is still wrong. The page renders,
the logo file is served, every gate passes. The only detector is a human
looking at the header — which does not scale past the first few dozen pages, and
is exactly the step an unattended run skips.

The fix is never "check it by eye." It is finding the measurement that actually
encodes what your eye is doing, then pinning it with tests against ground truth you
verified once, by hand, properly.

I build SEOSellers,
where this check is one of eleven gates a page has to clear before it is
allowed to publish. First page and article are free if you want to see the output.