DEV Community: Nasrul Hazim Bin Mohamad

One Nullable Timestamp, Four Account States: Deriving User Status in Laravel

Nasrul Hazim Bin Mohamad — Fri, 12 Jun 2026 09:18:01 +0000

Most of today went into a user-management overhaul in kickoff — my Laravel starter kit. Flyout CRUD panels, bulk actions, permission assignment, and the piece I want to talk about: account status. Active, suspended, unverified, deleted.

The interesting part isn't the feature. It's the modelling decision underneath it. Where do those four states actually live?

The trap: a `status` column

The obvious move is a status enum column on users. Set it to suspended when you suspend someone, active when you reinstate, unverified until they verify their email, deleted when they're soft-deleted.

It works. Until it doesn't. Now you've got a status column and an email_verified_at column and a deleted_at from soft deletes — and all three encode overlapping truths. Soft-delete a user and forget to flip status? Now your database says the account is both active and trashed. Verify an email but the status update fails mid-request? Drift. Every place that mutates a user becomes a place that has to remember to keep status in sync. That's not a feature, that's a maintenance tax.

The signals already exist. email_verified_at tells you verified-or-not. deleted_at (soft deletes) tells you removed-or-not. The only genuinely new state is suspended — an admin deliberately blocking sign-in. So that's the only thing worth storing.

What we actually store: one nullable timestamp

Schema::table('users', function (Blueprint $table) {
    $table->timestamp('suspended_at')->nullable()->after('email_verified_at');
});

That's the whole migration. Not a boolean is_suspended — a nullable timestamp. Null means not suspended; a value means suspended and tells you when. A boolean throws that second fact away for free; the timestamp keeps it at no extra cost. Same instinct as email_verified_at and deleted_at — Laravel models "did this happen, and when" as a nullable timestamp everywhere, so we follow the grain of the framework.

The behaviour on the model stays tiny:

public function isSuspended(): bool
{
    return $this->suspended_at !== null;
}

public function suspend(): void
{
    $this->forceFill(['suspended_at' => now()])->save();
}

public function unsuspend(): void
{
    $this->forceFill(['suspended_at' => null])->save();
}

Status is derived, never stored

Here's the move. status() isn't a column read — it's a match over the signals, in priority order:

public function status(): UserStatus
{
    return match (true) {
        $this->trashed()                   => UserStatus::DELETED,
        $this->isSuspended()               => UserStatus::SUSPENDED,
        $this->email_verified_at === null  => UserStatus::UNVERIFIED,
        default                            => UserStatus::ACTIVE,
    };
}

match (true) reads like a cond — the first arm whose condition is truthy wins, so order encodes precedence. Deleted beats suspended beats unverified beats active. A trashed-and-suspended user reads as DELETED, which is what you want: the strongest fact wins, and there's exactly one place that decides. No drift, because there's nothing to keep in sync — the status is computed fresh from columns that other parts of Laravel are already maintaining for you.

Querying gets the same treatment via scopes, so "active" means the same thing in a list query as it does on a single model:

public function scopeActive(Builder $query): Builder
{
    return $query->whereNull('suspended_at')->whereNotNull('email_verified_at');
}

public function scopeSuspended(Builder $query): Builder
{
    return $query->whereNotNull('suspended_at');
}

The enum carries its own presentation

UserStatus is a string-backed enum, but it implements a Contract and pulls in an InteractsWithEnum trait (from my traitify package) so every enum in the app exposes the same label() / color() / description() surface:

enum UserStatus: string implements Contract
{
    use InteractsWithEnum;

    case ACTIVE = 'active';
    case SUSPENDED = 'suspended';
    case UNVERIFIED = 'unverified';
    case DELETED = 'deleted';

    public function color(): string
    {
        return match ($this) {
            self::ACTIVE     => 'green',
            self::SUSPENDED  => 'amber',
            self::UNVERIFIED => 'zinc',
            self::DELETED    => 'red',
        };
    }

    // label() and description() follow the same match shape
}

The payoff is the view never branches on status. It asks the enum:

<flux:badge :color="$user->status()->color()">
    {{ $user->status()->label() }}
</flux:badge>

Add a BANNED case later and you touch exactly one file — the enum — not every Blade template that paints a badge. The presentation lives with the data it describes, which is the whole point of giving an enum methods instead of scattering match blocks across the UI.

Deriving the state isn't enforcing it

A computed status() is a label. It does not stop a suspended user from using an existing session — they were logged in before you suspended them, and the cookie doesn't care about your enum. Enforcement is a separate, deliberate boundary: middleware.

class EnsureUserIsNotSuspended
{
    public function handle(Request $request, Closure $next): Response
    {
        $user = $request->user();

        if ($user && $user->isSuspended()) {
            Auth::guard('web')->logout();

            $request->session()->invalidate();
            $request->session()->regenerateToken();

            return redirect()
                ->route('login')
                ->with('error', __('Your account has been suspended. Please contact the administrator.'));
        }

        return $next($request);
    }
}

Note it doesn't just redirect — it logout()s, invalidates the session, and regenerates the CSRF token. Suspension should evict, not merely inconvenience. A redirect alone leaves a valid session sitting in the cookie jar.

Pest: pin the precedence and the eviction

Two things are worth locking down — that the match precedence holds, and that the middleware actually kicks a suspended session out.

it('derives status with deleted taking precedence over suspended', function () {
    $user = User::factory()->create(['email_verified_at' => now()]);

    expect($user->status())->toBe(UserStatus::ACTIVE);

    $user->suspend();
    expect($user->fresh()->status())->toBe(UserStatus::SUSPENDED);

    $user->delete(); // soft delete
    expect($user->fresh()->status())->toBe(UserStatus::DELETED);
});

it('evicts a suspended user mid-session', function () {
    $user = User::factory()->create(['email_verified_at' => now()]);
    $user->suspend();

    $this->actingAs($user)
        ->get('/dashboard')
        ->assertRedirect(route('login'));

    expect(auth()->check())->toBeFalse();
});

The first test is the one that earns its keep over time: it freezes the precedence order so a future refactor can't quietly let SUSPENDED outrank DELETED.

Takeaway

Don't store what you can derive. A status column looks convenient and turns into four columns that disagree with each other. Keep one nullable timestamp for the only state nobody else tracks (suspended_at), lean on email_verified_at and deleted_at for the rest, and compute status() with an ordered match (true) so precedence is explicit and there's a single source of truth.

Then remember the part that's easy to skip: deriving a state and enforcing it are different jobs. The enum labels the account; the middleware is what actually shows a suspended user the door.

Deep-Linkable Livewire: Scoping a Browser to the Thing You Clicked

Nasrul Hazim Bin Mohamad — Fri, 12 Jun 2026 04:21:17 +0000

Today's work was a small piece of UX that's easy to underestimate: making an admin "browser" page scope itself to whatever you clicked to get there. The setup is one I keep running into — you have a list of connectors (think AD/LDAP directory connections), and each connector has its own users and its own groups. The old flow dumped you into a generic Users browser and made you re-pick the connector from a dropdown. Annoying. You already told the app which connector you cared about by clicking its row.

The fix is the kind of thing Livewire makes almost too easy, so I want to slow down and talk about why it works and where the edge cases hide.

The core idea: a URL-bound property

The whole feature hinges on one attribute. In Livewire, you can bind a public property straight to a query-string parameter:

use Livewire\Attributes\Url;
use Livewire\Component;

class UserBrowser extends Component
{
    #[Url(as: 'connector')]
    public string $selectedConnector = '';

    // ...
}

#[Url(as: 'connector')] means two things at once. When $selectedConnector changes, the URL becomes ?connector=acme-ad without a full page load. And when someone arrives at ?connector=acme-ad, Livewire hydrates the property from the query string before mount() finishes. That second half is what makes deep links work — the page reads its own starting state from the URL.

So the "View Users" link on a connector row is nothing fancier than:

<a href="{{ route('admin.directory.users', ['connector' => $connector['name']]) }}">
    View Users
</a>

Click it, land on the browser, and the property is already set to that connector. No dropdown dance.

The edge case everyone forgets: untrusted input

Here's the thing — ?connector= is user input. Anyone can type ?connector=lol-not-real into the address bar. If you trust it blindly, you get an empty browser, a stray exception, or worse, a UI that looks like it's scoped to something that doesn't exist.

A URL-bound property is a contract with the outside world, and the outside world lies. So mount() has to validate against the real, allowed set and fall back gracefully:

public function mount(): void
{
    $names = collect(app(ConnectorSettings::class)->connectors)
        ->filter(fn (array $c) =>
            ($c['is_active'] ?? false)
            && in_array($c['type'] ?? '', ['ad', 'ldap'], true)
        )
        ->pluck('name');

    // Honour a ?connector= deep link, but only if it's real and active.
    // Otherwise fall back to the first active connector.
    if ($this->selectedConnector === '' || ! $names->contains($this->selectedConnector)) {
        $this->selectedConnector = $names->first() ?? '';
    }
}

Two failure modes, one guard: empty (no deep link, default to the first) and unknown (someone made up a name, also default to the first). Notice the allow-list is derived from config — only active connectors of the right type count. The query string can request anything; the component only honours what's genuinely on the menu.

This is the same instinct as validating a Form Request or authorizing a policy: never let the edge of the system set internal state without a check.

Stripping secrets out of a details modal

The second half of the day was a "View Details" modal on each connector row. Connectors carry connection config — host, port, base DN, sync settings — and they also carry credentials. The modal should show the former and never the latter.

I leaned on a #[Computed] property so the view never touches the raw config:

use Livewire\Attributes\Computed;

public ?int $detailsIndex = null;

public function showDetails(int $index): void
{
    $this->detailsIndex = $index;
    $this->modal('connector-details-modal')->show();
}

#[Computed]
public function detailsConnector(): ?array
{
    if ($this->detailsIndex === null) {
        return null;
    }

    $connector = app(ConnectorSettings::class)->connectors[$this->detailsIndex] ?? null;

    if ($connector === null) {
        return null;
    }

    // Never let credentials reach the Blade view (or the wire payload).
    unset($connector['password'], $connector['client_secret']);

    return $connector;
}

Why a computed property and not just a public array? Because anything you put in a public property gets serialized into the component's wire payload and shipped to the browser on every request. A #[Computed] value is resolved server-side at render time and isn't part of the persisted state — so the stripped array is the only shape the secret-free data ever takes. The unset() is the redaction; the computed property is what keeps the un-redacted version from ever leaving the server in the first place.

Small but worth saying out loud: stripping a secret in the view is too late. Strip it at the boundary where data becomes "stuff the client can see."

A test worth writing

The deep-link fallback is exactly the kind of logic that quietly rots. Pest makes the contract explicit:

it('falls back to the first active connector for an unknown deep link', function () {
    config()->set('connectors', [
        ['name' => 'acme-ad', 'type' => 'ad', 'is_active' => true],
        ['name' => 'beta-ldap', 'type' => 'ldap', 'is_active' => true],
    ]);

    Livewire::withQueryParams(['connector' => 'does-not-exist'])
        ->test(UserBrowser::class)
        ->assertSet('selectedConnector', 'acme-ad');
});

it('honours a valid connector deep link', function () {
    config()->set('connectors', [
        ['name' => 'acme-ad', 'type' => 'ad', 'is_active' => true],
        ['name' => 'beta-ldap', 'type' => 'ldap', 'is_active' => true],
    ]);

    Livewire::withQueryParams(['connector' => 'beta-ldap'])
        ->test(UserBrowser::class)
        ->assertSet('selectedConnector', 'beta-ldap');
});

Livewire::withQueryParams() is the bit that makes this honest — it simulates the deep-link arrival, so you're testing the same hydration path a real browser hits, not just calling mount() by hand.

Takeaway

Three ideas did the heavy lifting today, none of them new, all of them easy to get subtly wrong:

A URL-bound property turns "where you came from" into shareable, bookmarkable state for free — but it's untrusted input, so validate it against an allow-list and fall back, never trust it raw. And when you surface config in a modal, redact at the boundary with a computed property, not in the template, so secrets never ride along in the wire payload.

The UX win — click a connector, land already scoped to it — is the visible part. The invisible part is the two guards that keep a convenient query string from becoming a foot-gun.

Why an encrypted config backup breaks when you move servers — and how I fixed it in laravel-config-backup

Nasrul Hazim Bin Mohamad — Fri, 12 Jun 2026 03:52:06 +0000

Imagine you write a letter in a secret code that only your old house key can read. Then you move. You photocopy the coded letter, carry it to the new house… and realise the new key can't decode any of it. The letter is valid, just useless.

That's effectively what happens when you back up encrypted values from a Laravel database and restore them onto a different server. I hit exactly this while working on laravel-config-backup today, so here's the problem and the fix.

The real cause: `Crypt` is bound to `APP_KEY`

When you store sensitive settings (think API tokens or OAuth secrets) in the database, you typically encrypt them with Crypt::encryptString(). Lovely — until you remember Crypt uses your app's APP_KEY as the key.

A naive backup copies that ciphertext straight across:

// Naive approach — move the ciphertext as-is
$value = DB::table('settings')->where('key', 'some.secret')->value('value');
// this value is encrypted with the OLD server's APP_KEY

The new server has a different APP_KEY. Try to decrypt → DecryptException: The payload is invalid. Your backup is technically complete but practically dead.

The fix: decrypt on the way out, re-encrypt on the way in

The decision is easy to state, hard to stay disciplined about: never carry ciphertext across a server boundary. Instead —

On create: decrypt the values with the source server's APP_KEY, store plaintext inside the archive.
Protect that archive with AES-256 and a password (a human-held secret, not the APP_KEY).
On restore: re-encrypt the values with the destination server's APP_KEY before writing to the DB.

Back to the analogy: you decode the letter, carry the plain letter in a locked briefcase (the password-protected archive), and re-encode it with the new house's lock on arrival. The briefcase handles security in transit — not the old code that's no longer relevant.

I made that intent explicit right where the behaviour lives, in ConfigBackupService:

/**
 * Config Backup & Restore.
 *
 * Bundles .env + DB-stored settings into a single AES-256, password-encrypted
 * ZIP. Content inside the archive is stored DECRYPTED so the encrypted DB
 * columns are re-encrypted on import with the destination server's APP_KEY —
 * making a backup portable across servers.
 */
class ConfigBackupService { /* ... */ }

"Naked" plaintext inside the archive sounds scary, but the security boundary has moved on purpose: from the APP_KEY (which you want to differ per server) to the archive password (which you control and can rotate). That's the right trade-off for an artifact whose whole job is to move.

Authz: one source of truth, not scattered checks

The same pass hardened authorization. It's too easy to scatter gate checks across the UI, routes, and commands. One method everything refers to keeps it honest:

/**
 * Whether the current context passes the configured authorization gate.
 * Returns true when no gate is configured. CLI commands run by a server
 * operator deliberately bypass this. Single source of truth for authz.
 */
public function authorizes(): bool
{
    $gate = $this->gate();

    return $gate === null || Gate::allows($gate);
}

Two subtle but important points:

The gate is nullable. If the host app doesn't set a gate, the package doesn't impose its own policy — you can rely on route middleware. Good tooling suggests, it doesn't dictate.
The CLI deliberately bypasses it. Someone running php artisan config-backup:create on the server already has shell access. Forcing them through a web gate is theatre, not security.

Keep it honest with a test

The portability part is hard to verify "by eye". I keep it honest with a round-trip test: encrypt with one key, simulate a different key, and assert the restore can still read the original value.

it('restores secrets under a different APP_KEY', function () {
    config(['app.key' => 'base64:'.base64_encode(random_bytes(32))]);
    DB::table('settings')->insert([
        'key' => 'some.secret',
        'value' => Crypt::encryptString('super-secret'),
    ]);

    $backup = app(ConfigBackupService::class)->create(password: 'pa55');

    // Simulate the destination server: a different APP_KEY
    config(['app.key' => 'base64:'.base64_encode(random_bytes(32))]);
    DB::table('settings')->truncate();

    app(ConfigBackupService::class)->restore($backup, password: 'pa55');

    $value = DB::table('settings')->where('key', 'some.secret')->value('value');
    expect(Crypt::decryptString($value))->toBe('super-secret');
});

If this stays green across two different APP_KEYs, you know your backup is genuinely portable — not just "works on my machine".

The takeaway

Whenever you design something that crosses a boundary — server, environment, tenant — ask: which key is glued to this artifact, and does that key exist on the other side? The answer is often no, and the safest thing to carry is plaintext in a container whose key you control — not ciphertext bound to a key you left behind.

The package is open source: github.com/cleaniquecoders/laravel-config-backup.

Shipping a Livewire 4 + Flux admin UI inside a package: four gotchas that 500'd on me

Nasrul Hazim Bin Mohamad — Fri, 12 Jun 2026 03:51:07 +0000

Bundling an admin UI inside a Laravel package is a different game from building one in an app. The app's conveniences — a compiled Vite manifest, a registered layout, your own Livewire components — aren't there. Today, getting the bundled admin UI in laravel-config-webhook to actually render meant walking through four separate 500s. Each one is a small, sharp lesson about the boundary between a package and its host app.

1. A Livewire 4 component name can't contain `::`

I registered the component with a namespaced-looking name and got a ComponentNotFoundException at runtime. The cause is subtle: under Livewire 4, a name containing :: triggers namespace resolution that ignores singly-registered components. So a "nice looking" name silently routes to a lookup that will never find it.

The fix is to register a plain, dotted name:

// ❌ looks tidy, but the "::" sends Livewire down a namespace path
Livewire::component('config-webhook::webhooks', Webhooks::class);

// ✅ a flat dotted name resolves to the singly-registered component
Livewire::component('config-webhook.webhooks', Webhooks::class);

Lesson: in a package, treat the component name as an identifier with framework-reserved characters — :: is not yours to use.

2. Flux ships Heroicons, not Pro/Lucide names

The free tier of Flux ships Heroicons. Reach for a Pro-only or Lucide-style name and it throws at runtime. I'd used webhook, ellipsis, and list; the free equivalents are bolt, ellipsis-horizontal, and queue-list.

This is the same trap that bit my SSO package — which is exactly why I now guard it with a static test that reads the Blade and checks every icon against Flux's actual stub files. (Separate post on that.) If you ship a package UI with Flux, assume free-tier icons only unless you require Pro.

3. Don't `@vite` host assets that don't exist

The bundled fallback layout @vite-d the host app's assets. In a fresh consumer (or the package's own workbench) there's no compiled manifest, so you get a ViteManifestNotFoundException. A package's fallback layout has to stand on its own:

{{-- bundled fallback layout: self-contained, no host build step --}}
<head>
    <script src="https://cdn.tailwindcss.com"></script>
    @fluxAppearance
</head>
<body>
    {{ $slot }}
    @fluxScripts
</body>

Tailwind Play CDN + Flux directives mean the UI renders out of the box, with zero assumptions about the host's build pipeline. The host can always override the layout when it wants the real thing.

4. A non-null layout default defeats your own fallback

This one is sneaky. The config had:

'ui' => [
    'layout' => 'components.layouts.app', // a sensible-looking default…
],

…and the render used config('config-webhook.ui.layout') ?: $bundledFallback. Because the default was non-null, the ?: never fell back — it always pointed at components.layouts.app, which doesn't exist in a bare consumer, so: 500. Defaulting to null lets the fallback actually do its job:

'ui' => [
    'layout' => null, // null → the bundled fallback is used unless the host sets one
],

Lesson: when you offer a fallback via ?: or ??, the default that triggers it must be the empty value, not a placeholder that looks like a value.

Bonus: prove it end-to-end in the workbench

Bugs like these hide because nothing exercises the full path. So I wired the package's Testbench workbench to deliver a webhook for real: seed an active subscriber, add a /receiver route that verifies the HMAC signature, and — importantly — exclude the CSRF middleware (PreventRequestForgery) from that receiver route, since an inbound webhook isn't a browser form post:

Route::post('/receiver', VerifyAndStore::class)
    ->withoutMiddleware(PreventRequestForgery::class);

Now /fire delivers end-to-end straight after migrate:fresh --seed. The whole point: a demo that actually runs the real path is the cheapest way to keep these four gotchas from coming back.

The takeaway

Every one of these bugs lives at the package ↔ host boundary — names the framework reserves, assets the host may not have built, layouts the host may not define, defaults that quietly disable your own safety net. When you ship UI inside a package, assume the host gives you nothing, make the fallback self-sufficient, and wire a workbench that exercises the real path end-to-end.

Open source: github.com/cleaniquecoders/laravel-config-webhook.

A test that catches the bug your feature tests can't see

Nasrul Hazim Bin Mohamad — Fri, 12 Jun 2026 03:50:50 +0000

There's a class of bug that's maddening: it passes every test you have, then crashes in the user's face. I hit one in the admin UI of laravel-config-sso today, and the real fix wasn't changing an icon name — it was writing a test that could see the bug in the first place.

The bug: wrong icon name, crashes only at runtime

The admin UI uses Flux. Flux resolves icons through <flux:delegate-component>, and it throws for a name that doesn't exist:

Flux component [icon.ellipsis] does not exist.

It's an easy mistake. Flux ships Heroicons, not Lucide. So your Lucide reflexes lie to you:

You type (Lucide)	Flux wants (Heroicon)
`ellipsis`	`ellipsis-horizontal`
`trash-2`	`trash`
`eye-off`	`eye-slash`

Why feature tests don't catch it

Here's the interesting part. I had a feature test that hits the admin route and asserts 200. Green. But the real UI crashes. How?

Because in the headless test harness, Flux renders icons as no-ops. No real <flux:delegate-component> boots, so the icon name never gets resolved. The crash only surfaces under a full boot (testbench serve) — exactly where your automated tests don't go.

Analogy: it's like a spell-checker that only runs when you print the document, not while you type. Your tests type away happily. The crash waits at the printer.

The fix: a static test that reads the Blade and validates every icon

Instead of relying on runtime, I wrote a Pest test that reads the Blade view, extracts every icon name (static and inside dynamic expressions), and asserts Flux actually ships a stub for each one:

$fluxIconStubs = base_path('vendor/livewire/flux/stubs/resources/views/flux/icon');

it('only references Flux icons that exist', function () use ($fluxIconStubs) {
    expect(is_dir($fluxIconStubs))->toBeTrue("Flux icon stubs not found");

    $view = file_get_contents(__DIR__.'/../../resources/views/livewire/sso-providers.blade.php');

    // Static `icon="name"` plus quoted tokens inside dynamic
    // `icon="{{ $cond ? 'eye-slash' : 'eye' }}"` expressions
    preg_match_all('/icon="([a-z][a-z0-9-]*)"/', $view, $static);
    preg_match_all('/icon="\{\{(.+?)\}\}"/', $view, $dynamic);

    $names = $static[1];
    foreach ($dynamic[1] as $expression) {
        preg_match_all("/'([a-z][a-z0-9-]*)'/", $expression, $tokens);
        $names = array_merge($names, $tokens[1]);
    }

    $names = array_values(array_unique($names));
    expect($names)->not->toBeEmpty();

    foreach ($names as $name) {
        expect(is_file("{$fluxIconStubs}/{$name}.blade.php"))
            ->toBeTrue("Flux has no icon [{$name}] — use a valid Heroicon name (Flux ships Heroicons, not Lucide).");
    }
});

What I like about this test:

It runs against the source of truth. Flux's icon registry is a folder of stubs in vendor/. The test checks directly against that — not a hardcoded list that goes stale.
It handles dynamic icons. Toggles like eye / eye-slash are the ones that usually slip through. The second regex catches quoted tokens inside Blade expressions.
The failure message teaches. When it breaks, it tells you the real reason: "Flux ships Heroicons, not Lucide." Future-me will be grateful.

That payoff was immediate: the very same Flux free-vs-Pro icon trap bit a sibling package the same day (a webhook/ellipsis/list set that only exists in Flux Pro). A guard test like this turns a "crashes in production" into a "fails in CI" — which is exactly where you want it.

When to reach for this pattern

Not every typo deserves a test. This pattern shines when your runtime lies to you during tests — where a component becomes a no-op, where an adapter is mocked out, where the environment differs from production. There, a static test that reads the artifact (a Blade view, a config file, a migration) can catch what a dynamic test can't.

The rule I keep: if a failure only appears under a full boot but your tests run headless, don't chase the full boot in CI. Catch the thing earlier with a static check over the source files. It's cheaper, faster, and it never renders a no-op.

Making encrypted Laravel config backups portable across APP_KEYs

Nasrul Hazim Bin Mohamad — Fri, 12 Jun 2026 03:44:17 +0000

Here's a fun one. You build a package that backs up an app's config — the .env plus the settings stored encrypted in the database — into a single password-protected ZIP. The whole selling point is portability: take a backup on server A, restore it on server B, even when the two servers have different APP_KEYs. Then you write a test that actually changes the key during a restore, and it fails. The DB settings come back garbled.

Turns out the bug wasn't in the encryption at all. It was in a cache I forgot was there. Today I shipped 1.1.0 of laravel-config-backup and this portability fix was the headline. Let me walk through it, because the lesson generalizes way beyond this package.

Why APP_KEY portability is even a thing

Laravel encrypts things with APP_KEY. Encrypted Eloquent casts, signed cookies, sessions — all of it keys off that value. So if you naively mysqldump a table with encrypted columns and load it onto another server, every encrypted column is now ciphertext that the new key can't decrypt. Dead data.

The trick this package uses is to store the archive contents decrypted. When I export the database, rows go out through their casts, so an encrypted column becomes a plain value inside the ZIP (the ZIP itself is AES-256 password-encrypted, so it's not sitting around in plaintext). On import, each row is written back through the model, which means the cast re-encrypts it with whatever APP_KEY is active on the destination.

Server A (key A)              Archive (decrypted)         Server B (key B)
────────────────             ───────────────────         ────────────────
settings.payload ──decrypt──▶   "Portable"   ──import──▶ settings.payload
(ciphertext A)     (cast)                       (cast)    (ciphertext B)

Think of it like shipping furniture: you don't ship the assembled wardrobe through a doorway it doesn't fit, you flat-pack it and reassemble at the destination with the screws you have there.

The restore sequence

A restore that also brings a new .env has to be careful about ordering. Here's the real flow:

public function restore(string $absZipPath, string $password, array $sections, int|string|null $userId = null): array
{
    // 1. Safety snapshot of the CURRENT config before we touch anything.
    $safety = $this->create(
        ConfigBackupSection::values(),
        $password,
        'Automatic pre-restore safety backup',
        $userId,
        isSafety: true,
    );

    $zip = $this->openArchive($absZipPath, $password); // validates password
    $appKeyChanged = false;

    // 2. Restore .env FIRST. If APP_KEY changes, swap the active encrypter
    //    so any subsequent DB re-encryption uses the FINAL key.
    if ($this->wants($sections, ConfigBackupSection::ENV) && /* ... */) {
        $oldKey = (string) config('app.key');
        File::put(base_path('.env'), $newEnv);
        $newKey = Env::parse($newEnv)['APP_KEY'] ?? $oldKey;

        if ($newKey !== '' && $newKey !== $oldKey) {
            $this->useEncryptionKey($newKey);
            $appKeyChanged = true;
        }
    }

    // 3. Restore DB settings — now re-encrypted with the now-active key.
    // ...

    ConfigRestored::dispatch($restored, $databaseSummary, $appKeyChanged, $safety->uuid);

    return [
        'safety_backup'   => $safety->uuid,
        'restored'        => $restored,
        'database'        => $databaseSummary,
        'app_key_changed' => $appKeyChanged,
    ];
}

.env before database, always. Otherwise you'd re-encrypt the DB with the old key and then swap — exactly backwards.

The bug: a warm encrypter cache

So why did the test fail even with the ordering correct? Look at step 1: the pre-restore safety snapshot reads encrypted rows to back them up. Reading encrypted rows resolves the encrypter — and Crypt::getFacadeRoot() caches its instance. By the time I swapped app.key in step 2, the encrypter the casts actually use was already warmed with the old key. So step 3 dutifully re-encrypted everything with a stale encrypter. The key in .env said B; the bytes on disk were still keyed to A.

This is the classic shape of a caching bug: the value you changed and the value being read came from two different places. Setting config(['app.key' => ...]) updates the config repository, but the already-resolved encrypter singleton doesn't care about that — it's holding its own copy of the key.

The fix is to swap the live binding and clear the resolved facade instance so the casts re-resolve:

protected function useEncryptionKey(string $appKey): void
{
    $key = $this->parseKey($appKey);        // strip base64: and decode
    $cipher = config('app.cipher', 'AES-256-CBC');

    Config::set('app.key', $appKey);
    app()->instance('encrypter', new Encrypter($key, $cipher));
    Crypt::clearResolvedInstance('encrypter'); // force re-resolve on next use
}

That last line is the whole fix. Without it, the encrypter the casts grab is the stale one and the "portable" backup quietly isn't.

Lock the test around the actual failure

The dangerous thing about this class of bug is that a casual test passes. If your test restores and reads the value back in the same request with a still-warm encrypter, everything looks fine. The bug only shows when something has read encrypted data before the key swap — which is exactly what the safety snapshot does in production.

So the regression test has to reproduce that ordering: write a row under key A, take a backup, then restore an archive that carries key B, and assert the bytes on disk are decryptable under B and not A.

it('re-encrypts database settings under the restored APP_KEY', function () {
    // Stored under the original key.
    Setting::create(['key' => 'smtp.password', 'value' => 'Portable']);

    $path = ConfigBackup::backup(['env', 'database'], 'secret-pass');

    // Archive carries a different APP_KEY in its .env.
    $result = ConfigBackup::restore($path, 'secret-pass', ['env', 'database']);

    expect($result['app_key_changed'])->toBeTrue();

    // Raw column must decrypt under the NEW key, and fail under the OLD one.
    $raw = DB::table('settings')->where('key', 'smtp.password')->value('value');
    expect(Crypt::decryptString($raw))->toBe('Portable'); // new key is active
});

If you ever delete the clearResolvedInstance line, this test goes red. That's the goal — the test pins the exact behaviour, not a happy-path approximation of it.

The other 1.1.0 changes, briefly

Two more things landed in the same release that are worth a mention because they're about not leaking and not trusting the UI:

Secure password prompt. config-backup:create used to want --password on the command line. That leaks straight into shell history and the process list — anyone with ps access sees your backup password. Now, if you omit --password, it prompts with a hidden, confirmed input. The flag still works for unattended/scheduled runs where there's no TTY.

Authorization at the route boundary. The package has a Livewire admin screen behind a configurable gate. The gate check lived inside the Livewire component, which is fine until someone hits the route some other way. So authorization is now centralized in one method and also enforced as route middleware:

public function authorizes(): bool
{
    $gate = $this->gate();

    return $gate === null || Gate::allows($gate);
}

// routes/web.php — belt and braces
if ($gate = config('config-backup.gate')) {
    $middleware[] = 'can:'.$gate;
}

One source of truth (authorizes()), enforced at two layers. The Pest suite covers all four cases: no gate configured (allow), guest (deny), wrong user (deny), right user (allow). Cheap tests, and they document the contract better than a paragraph of prose ever would.

Takeaway

The portability fix is really a reminder that config() and a resolved singleton are not the same source of truth. Any time you mutate framework config at runtime and expect already-resolved services to notice, you probably need to re-bind and clear the resolved instance — encrypter, DB connections, cache stores, they all cache. And when you find a bug like this, write the test that reproduces the ordering that triggered it, not the easy version that passes by accident.

Package is here if you want to poke at it: cleaniquecoders/laravel-config-backup.

Building a Permission-Gated MCP Server in Laravel (Without Opening a Backdoor)

Nasrul Hazim Bin Mohamad — Fri, 12 Jun 2026 02:41:37 +0000

I spent today wiring an MCP server into a Laravel app that manages a Kong API gateway. The interesting part wasn't "make the AI talk to the app" — that's the easy bit now that there's a first-party package for it. The interesting part was making sure the MCP layer is just another UI over the same rules, and never a quiet little backdoor that skips authorization.

Here's how I think about it, and the patterns that kept it honest.

MCP is a third front-end, not a new set of powers

The app already has two ways in: a web UI and an HTTP API. Both go through the same authorization, the same action classes, the same approval workflow. When you bolt on an MCP server, the temptation is to let the tools "just query the database" because it's faster. That's exactly how you end up with an AI agent that can do things a logged-in user never could.

So the rule I set for myself: every MCP tool maps to a permission the human already has, and every write goes through the same action class the web UI calls. MCP gets zero special privileges.

Tool base class: gate first, work second

With laravel/mcp, a tool is a class extending Laravel\Mcp\Server\Tool. Instead of letting each tool reinvent the auth check, I push it into an abstract base. Each concrete tool just declares the permission it needs; the base decides whether the caller is allowed.

abstract class GatewayTool extends Tool
{
    /** The permission this tool requires, e.g. "gateway.manage.services". */
    abstract protected function permission(): string;

    protected function authorizedUser(Request $request): ?User
    {
        $user = $request->user();

        if (! $user instanceof User || ! $user->can($this->permission())) {
            return null;
        }

        return $user;
    }

    protected function unauthorized(): Response
    {
        return Response::error(
            "Unauthorized — this tool requires the '{$this->permission()}' permission."
        );
    }
}

The $request->user() here is the token holder — I issue scoped bearer tokens with Sanctum, so the MCP session is authenticated as a real user with real permissions. Superadmin still bypasses through the usual Gate::before, so I don't have to special-case it.

One small thing that matters more than it looks: an unauthorized tool returns an error, not partial data. No "here's what you're allowed to see" half-answers. If you can't call it, you get a clean refusal and nothing leaks.

class ListServicesTool extends GatewayTool
{
    protected function permission(): string
    {
        return 'gateway.view.services';
    }

    public function handle(Request $request): Response
    {
        if (! $user = $this->authorizedUser($request)) {
            return $this->unauthorized();
        }

        // ...paginated, uuid/code only — never the internal id
    }
}

Note the identifiers: tools take and return uuid or a human code, never the auto-increment primary key. The internal id stays internal — same convention I use everywhere, and it matters doubly when an LLM is the one passing arguments around.

Tiered capabilities via a driver-based contract

Not every deployment has the same data behind it. Aggregated metrics might come from gateway snapshots on a small install, from PostgreSQL request logs on a bigger one, or from Elasticsearch on the heavy tier. I didn't want analytics tools to care which.

So the analytics tools depend on a contract, and the container binds the right implementation based on a configured tier:

interface UsageMetricsProvider
{
    public function usageSummary(Carbon $from, Carbon $to): array;
    public function getProviderName(): string;
}

// Only the richer tiers implement this marker contract.
interface DetailedUsageMetricsProvider extends UsageMetricsProvider
{
    public function errorBreakdown(Carbon $from, Carbon $to): array;
    public function slowestEndpoints(Carbon $from, Carbon $to): array;
}

The base analytics tool resolves the detailed provider only when it's actually available, and degrades gracefully when it isn't:

abstract class AnalyticsTool extends GatewayTool
{
    public function __construct(protected UsageMetricsProvider $metrics) {}

    protected function permission(): string
    {
        return 'gateway.view.usage-report';
    }

    protected function detailedMetrics(): ?DetailedUsageMetricsProvider
    {
        return $this->metrics instanceof DetailedUsageMetricsProvider
            ? $this->metrics
            : null;
    }
}

A detailed tool checks detailedMetrics() and, if it's null, tells the caller why — "not available on this reporting tier, switch to the log-backed tier" — instead of throwing a confusing error or returning empty arrays. The marker-interface trick (a sub-interface that only the capable drivers implement) is a clean way to do capability detection without a pile of if ($tier >= 2) checks scattered around.

Write tools reuse the action classes — no shortcuts

This is the part I care about most. The write tools (approve a service, expire a subscription, configure a plugin) don't touch models directly. They call the exact same invokable action classes the web controllers call. Which means:

A new service still starts as draft and must be submitted, then approved by someone other than the owner, before it syncs to the gateway.
Changing a plugin on an approved service still reverts it to pending_approval.
Expiring a subscription still revokes gateway access; renewing still restores it.

The MCP tool is a thin adapter: parse input, resolve the resource by uuid, call the action, format the response. All the business rules live in one place and the AI can't route around them. If I ever change the approval flow, the MCP server inherits it for free.

I also deliberately left some things out. Destructive deletion isn't exposed over MCP at all — that stays a web-only, human-driven request/approve flow. Not everything needs an AI-accessible tool, and "can I" shouldn't decide "should I".

Two servers, two audiences

I ended up splitting into two MCP servers sharing the same tool conventions: an ops server (manage services, routes, plugins, run audits, read full analytics) and a consumer-facing catalogue server (browse available APIs, request a subscription, check my own usage). Same Sanctum tokens, different permission sets decide which endpoint a token can even reach. The catalogue server simply can't see the management tools — it's not a UI toggle, it's a different tool list bound to different access.

Testing the gate

The thing worth a Pest test isn't the happy path — it's the refusal. The most important assertion is "a user without the permission gets an error and zero data":

it('refuses a tool when the token user lacks the permission', function () {
    $user = User::factory()->create(); // no gateway permissions

    $response = ListServicesTool::make()
        ->handle(Request::for(['page' => 1], actingAs: $user));

    expect($response->isError())->toBeTrue()
        ->and($response->content())->toContain('requires')
        ->and($response->content())->not->toContain('uuid');
});

it('returns data once the permission is granted', function () {
    $user = User::factory()->create();
    $user->givePermissionTo('gateway.view.services');

    $response = ListServicesTool::make()
        ->handle(Request::for(['page' => 1], actingAs: $user));

    expect($response->isError())->toBeFalse();
});

Test the deny path first. It's the one a refactor is most likely to quietly break, and it's the one with the worst blast radius if it does.

Takeaway

An MCP server is a powerful new surface, and that's exactly why it should be the least privileged one — never more capable than the human whose token it carries. Three habits made that easy to hold: gate every tool through a base class against an existing permission, lean on a driver-based contract so capabilities degrade honestly instead of lying, and make write tools call the same action classes as the rest of the app so the workflow can't be bypassed. The AI gets to be useful without getting to be sneaky.

Next up: tightening the tool instructions so the model picks the right tool the first time — turns out a good #[Instructions] block is half the battle, but that's a post for another day.

Laravel Billing: one package, every gateway, working on day one

Nasrul Hazim Bin Mohamad — Mon, 01 Jun 2026 07:21:02 +0000

Every SaaS billing integration starts the same way: you pick a provider, pull in their package, wire it up — and three months later when the business wants to add a second gateway (or swap to a Malaysian one like BayarCash or ToyyibPay because Stripe doesn't do local rails), you discover your entire subscription layer is welded to the first provider's package. Different webhook shapes, different status vocabularies, different model assumptions. You're not adding a gateway; you're re-architecting.

I kept watching this happen — especially in the Malaysian market, where the "obvious" global packages assume a gateway that half my clients can't actually use. So I built cleaniquecoders/laravel-billing around one inversion: the gateway is the plugin, not the package. The engine owns subscription and invoice state. A gateway is a single contract your app implements. This post is less about the API surface and more about why it's shaped this way — because the shape is the whole point.

The core decision: one package, gateways as a contract

The temptation when building a billing library is to ship laravel-billing-stripe, laravel-billing-bayarcash, laravel-billing-toyyibpay, and so on. It feels modular. It's actually a maintenance trap — every gateway sub-package re-implements the same subscription lifecycle slightly differently, and the core can never assume a stable shape because each adapter bends it.

This package goes the other way. There is one package, one repo, and it never references a real provider by name. Instead there's a single extension point:

namespace CleaniqueCoders\LaravelBilling\Contracts;

interface PaymentGateway
{
    public function createCheckout(
        Billable $billable,
        Plan $plan,
        PlanInterval $interval,
        string $returnUrl,
    ): CheckoutIntent;

    public function cancel(Subscription $subscription): void;

    public function parseWebhook(Request $request): ?WebhookEvent;
}

Three methods. That's the entire surface your app implements to onboard BayarCash, ToyyibPay, Chip, senangPay, Stripe, or anything else. The trick that makes it hold together is the two DTOs at the boundary — CheckoutIntent going out, WebhookEvent coming back:

final class CheckoutIntent
{
    public function __construct(
        public string $redirectUrl,   // where to send the customer
        public string $externalId,    // echoed back by the webhook for correlation
    ) {}
}

The gateway's job is to translate the provider's idiosyncratic world into these two neutral shapes. Once it does, the engine — subscription transitions, invoice issuance, events — never needs to know which provider it's talking to. The provider-specific mess is quarantined inside one class instead of leaking through your whole billing layer. That's the package-worthy lesson here, independent of billing: when you integrate N external services that do conceptually-the-same thing, define your own DTO at the boundary and make each adapter responsible for the translation. Don't let provider shapes propagate inward.

Batteries included: a gateway that needs no merchant account

Here's the part I'm most pleased with. A fresh install defaults to BILLING_GATEWAY=local, and the bundled LocalGateway runs the entire subscribe → activate → invoice → receipt flow with no real money and no merchant account. You composer require, run migrations, and the billing flow works immediately — in demo, in development, in UAT, in CI.

But it's not a stub. This is the detail that matters:

// LocalGateway::createCheckout — approval flows through the SAME
// WebhookEvent path a real gateway uses
return new WebhookEvent(
    type: WebhookEventType::SubscriptionActivated,
    externalId: $payload['external_id'],
    amountCents: $payload['amount_cents'] ?? null,
    providerEventId: 'local-'.$payload['external_id'],
    rawPayload: $payload,
);

When you click "Approve" on the local dev checkout page, it produces a WebhookEvent and runs it through Billing::handle() — the exact same code path a real BayarCash webhook would take. It even HMAC-signs its checkout token with your app.key and verifies the signature on the way back, so signature-verification logic is exercised too:

public static function verify(string $token): ?array
{
    [$data, $signature] = explode('.', $token, 2);
    $expected = hash_hmac('sha256', $data, static::key());

    if (! hash_equals($expected, $signature)) {
        return null; // tampered or invalid
    }
    // ...
}

Why go to this trouble for a "dev" gateway? Because a fake that takes a different path than production is worse than no fake — it gives you false confidence. By making the local gateway flow through the real activation pipeline, your tests against local actually validate the pipeline a paying customer will hit. Set BILLING_LOCAL_AUTO=true and the whole thing runs synchronously in a single request, which is perfect for CI and feature tests. The local routes also refuse to register in production, so there's no footgun.

Headless core, optional UI

The engine — models, services, contract, events, the manager — works with no UI at all. If you want billing pages fast, there's an opt-in Livewire + Flux UI (plan picker, billing portal, receipt card) that closes the full loop. The guard is clean:

if (config('billing.routes.enabled') && class_exists(Livewire::class)) {
    // register /billing routes
}

If Livewire isn't installed, or you set BILLING_UI_ENABLED=false, the package stays fully headless and you build your own pages against the same models and facade. No hard dependency on the UI stack bleeds into the core. This is the right default for a library: the opinionated convenience layer is there if you want it, but it's behind a class_exists check and a config flag, never mandatory.

The webhook flow, and a replay guard worth stealing

Your app owns the route; the package does the work:

Route::post('/webhooks/{gateway}', function (Request $request, string $gateway) {
    $event = Billing::gateway($gateway)->parseWebhook($request);
    abort_if($event === null, 401);

    Billing::handle($event); // dedups, transitions state, issues invoices, fires events
    return response()->noContent();
});

parseWebhook() (your gateway's code) verifies the signature and normalises the payload, or returns null to reject it. Then Billing::handle() delegates to a WebhookProcessor that replay-guards, locates the subscription, transitions status, issues an invoice on activate/renew, and fires the matching domain event.

The replay guard is a small thing I like:

protected function isReplay(WebhookEvent $event): bool
{
    if ($event->providerEventId === null) {
        return false;
    }

    $key = 'billing:webhook:'.$event->providerEventId;
    $ttl = (int) config('billing.webhook.replay_ttl', 60 * 60 * 24 * 30);

    // Cache::add returns false when the key already exists → replay.
    return Cache::add($key, true, $ttl) === false;
}

Gateways retry. They send the same event twice, three times, because they didn't get your 200 fast enough. If you don't dedup, you double-issue invoices. The neat part is leaning on Cache::add's atomicity — it only writes if the key is absent and tells you whether it won the race, in one operation. No read-then-write window for a concurrent duplicate to slip through. That's a reusable pattern for any idempotent-event handling, not just billing.

State transitions live in one place

WebhookProcessor is where provider events become subscription state, and it reads like a state machine:

match ($event->type) {
    WebhookEventType::SubscriptionActivated => $this->activate($subscription),
    WebhookEventType::SubscriptionRenewed   => $this->renew($subscription),
    WebhookEventType::PaymentSucceeded      => $this->paymentSucceeded($subscription, $event),
    WebhookEventType::PaymentFailed         => $this->paymentFailed($subscription, $event),
    WebhookEventType::SubscriptionCanceled  => $this->cancel($subscription),
};

The gateway's only responsibility is mapping its provider's vocabulary onto these five WebhookEventType cases. Everything downstream — what "activate" means for period dates, when an invoice gets issued, which event fires — is decided once, in the engine, regardless of provider. A SubscriptionStatus enum carries its own access logic so the rule isn't scattered:

public function grantsAccess(): bool
{
    return match ($this) {
        self::Trialing, self::Active, self::PastDue => true,
        self::Canceled, self::Incomplete => false,
    };
}

Note PastDue still grants access — a failed renewal shouldn't instantly lock someone out mid-period. That's a deliberate dunning-friendly choice, and because it lives on the enum, it's consistent everywhere access is checked.

Polymorphic billing: tenancy is optional

The bill target is polymorphic, so the same engine serves single-tenant (User) and multi-tenant (Team/Workspace/Organization) without caring which:

class User extends Authenticatable implements Billable
{
    use HasSubscriptions;
}

HasSubscriptions satisfies the whole Billable contract and gives you the accessors the engine and UI depend on — subscription(), subscribedTo('pro'), onTrial(), onGracePeriod(), plan(), invoices(), plus metered-usage gating via canConsume('seats', 1) / recordUsage('seats', 1). To scope billing to a team instead of the logged-in user, you point one config closure at it:

'billable_resolver' => fn ($request) => $request->user()->currentTeam,

Every UI query and every invoice download is constrained to the resolved billable, and the download routes 403 on a foreign invoice — so one tenant can never see another's invoices. Tenancy didn't require a tenancy feature; it fell out of making the target polymorphic and routing all access through one resolver.

A few more details worth noting

Snapshot vs live. A subscription stores plan_tier as a snapshot string, but the live Plan is resolved from the repository at read time. So plan definitions can live in config or a database table (same PlanRepository interface either way), and a subscriber's tier reference survives even if you restructure your plan models.

Atomic invoice numbers. Sequential numbering (INV-2026-000001) is allocated in a row-locked transaction, so concurrent issuance never collides on a number:

$sequence = $sequenceModel::query()->where('year', $year)->lockForUpdate()->first();
$current = (int) $sequence->next_number;
$sequence->next_number = $current + 1;
$sequence->save();

Malaysia-friendly, neutrally. MYR default, an SST/SSM-aware tax-invoice template, configurable seller details — but all neutral by default, so it's not only a Malaysian package. The tax math is just round(subtotal * rate), stored as a breakdown on the invoice so the PDF renders correctly.

Events as your extension seam. The engine only updates state and issues invoices. Provisioning access, dunning emails, Slack pings — those are your listeners on SubscriptionActivated, SubscriptionRenewed, SubscriptionCanceled, PaymentSucceeded, PaymentFailed, InvoiceIssued. The package doesn't presume to know your side effects.

When you'd reach for this

It fits when you want subscription + invoicing in Laravel and:

you need more than one gateway, or a Malaysian gateway, or the freedom to swap later without re-architecting;
you want the full flow working on day one — demo, UAT, CI — before any merchant account exists;
you want a headless engine you can drive from your own UI, with an optional bundled UI when you're moving fast;
you bill teams or workspaces, not just users;
you're in a SST/SSM context and want sane local invoicing without a provider lock-in.

If you're all-in on a single global gateway forever and its first-party Laravel package covers you, use that. The value here shows up the moment "which gateway" becomes a question with more than one answer — which, for anyone building for the Malaysian market, it always is.

It's MIT-licensed and on Packagist:

composer require cleaniquecoders/laravel-billing

Repo and full docs (architecture, gateways, the full billing cycle, writing your own driver): github.com/cleaniquecoders/laravel-billing.

Implementing a gateway is one class and three methods — if you write a BayarCash or ToyyibPay driver, I'd love to see it.

PII Protection in PHP without a framework holding the leash

Nasrul Hazim Bin Mohamad — Mon, 01 Jun 2026 02:18:44 +0000

Every app that touches personal data eventually hits the same wall. You've got a national_id column, an email, a phone number, maybe a credit card. Compliance (PDPA here in Malaysia, GDPR, SOC 2 — pick your acronym) says you can't just store them in plaintext, and you definitely can't dump them into your audit log when someone edits a record.

The usual answer is "use the framework's encryption." And that works — until you're in a queue worker, a standalone CLI importer, a Symfony service, or a plain PHP webhook handler that doesn't have the framework's container booted. Suddenly your PII handling is coupled to config(), env(), and a service provider that isn't there.

I kept hitting this across different codebases, so I extracted the primitives into a small library: cleaniquecoders/pii-protection. This post walks through what's in it, but more usefully, why it's shaped the way it is — because the design decisions are the actual lesson here.

The one constraint that drove everything

The package has a single hard rule that everything else falls out of:

No framework. No global state. No static facades. No reading from env/config.

Every class is constructor-injected with explicit inputs and returns explicit outputs. That's it. The OpenSslEncrypter doesn't go looking for APP_KEY — you hand it a key. The masking strategies don't read a config file — you instantiate them with the options you want.

use CleaniqueCoders\PiiProtection\PiiManager;
use CleaniqueCoders\PiiProtection\Encryption\OpenSslEncrypter;
use CleaniqueCoders\PiiProtection\Masking\TailStrategy;

$manager = new PiiManager(
    new OpenSslEncrypter(key: $appKey),
    new TailStrategy(visible: 4),
);

$cipher = $manager->encrypt('0123456789');  // store at rest
$plain  = $manager->decrypt($cipher);       // "0123456789"
$masked = $manager->mask('0123456789');      // "******6789" for display
$audit  = $manager->redact($payload, ['phone', 'national_id']);

Why bother being this strict? Because PII protection is exactly the kind of cross-cutting concern that shows up in places your framework doesn't reach. The moment your encryption helper assumes a booted Laravel container, it's useless in the standalone importer that's actually processing the sensitive batch file at 2am. Keeping the primitives portable means the same code protects data everywhere — web request, artisan command, raw worker, test harness — with zero conditional "are we in a framework right now" branching.

There's a real trade-off here, and I want to name it honestly: you give up convenience. No auto-resolved facade, no Crypt::encrypt() one-liner. You have to wire the key in yourself. The package's position is that key handling is the caller's job — it'll rotate keys for you (more on that below), but loading and storing them is your responsibility. For a library whose entire reason to exist is correctness around sensitive data, I'd rather make the dependency explicit than hide it.

Requirements are PHP ^8.4, ext-openssl, ext-mbstring.

composer require cleaniquecoders/pii-protection

Three jobs, kept separate

The library cleanly splits into three responsibilities that are not the same thing, even though people often conflate them:

Encryption — reversible. You need the value back later. (AES-256-GCM)
Masking — one-way display transformation. ******6789 for the UI or a log.
Redaction — walk a payload and mask the listed fields before persisting.

Conflating these is where bugs come from. Masking is not security — it's a display concern. If you "mask" a value and store the masked version thinking it's protected, you've lost the data. If you encrypt a value you only ever need to show partially, you've added decryption surface for no reason. Knowing which job you're doing is half the battle.

Masking strategies

Each strategy implements one tiny contract — MaskStrategy::mask(string $value): string — and there's one per common PII shape:

Strategy	Behaviour	Example
`TailStrategy`	Keep last N chars	`******6789`
`FullStrategy`	Mask everything	`**********`
`EmailStrategy`	Mask local-part, keep domain	`****@acme.com`
`HashStrategy`	One-way `sha256` digest	`f4b0...e21`
`CreditCardStrategy`	Keep last 4, preserve grouping	`** ** 1111`
`IpStrategy`	Mask the last octet/group	`192.168.1.**`
`NameStrategy`	Keep each word's initial	`J* D`
`NricStrategy`	Mask MyKad digits, keep dashes	`****--****`

(new EmailStrategy())->mask('john.doe@acme.com');     // "****@acme.com"
(new CreditCardStrategy())->mask('4111 1111 1111 1111'); // "**** **** **** 1111"
(new NricStrategy())->mask('900101-01-1234');         // "******-**-****"

Every strategy takes an optional maskChar if * doesn't suit your UI:

(new TailStrategy(visible: 4, maskChar: '•'))->mask('0123456789'); // "••••••6789"

The NricStrategy is the local touch — masking Malaysian MyKad numbers while keeping the dash grouping intact, which is what you actually want on screen.

Encryption at rest, done properly

OpenSslEncrypter uses AES-256-GCM, and a few details matter:

use CleaniqueCoders\PiiProtection\Encryption\OpenSslEncrypter;

$encrypter = new OpenSslEncrypter(key: $appKey);

$cipher = $encrypter->encrypt('012345678'); // store this
$plain  = $encrypter->decrypt($cipher);     // "012345678"

Per message, it generates a random 16-byte salt and a 12-byte IV, then derives a fresh 256-bit data key with HKDF-SHA256 from the ring key plus that salt. The plaintext is encrypted under that derived key, with the caller context bound as GCM AAD. So encrypting the same value twice produces different ciphertext — correct behaviour for at-rest encryption, with a consequence people forget that I'll come back to.

The per-message derived key isn't decoration. Deriving a unique key per message means a single key/nonce mishap can't cascade — the blast radius is one record, not the whole column. You're not encrypting a million rows under literally the same AES key.

Ciphertext is written in a self-describing, versioned format:

v2.<keyId>.<base64( salt(16) || iv(12) || tag(16) || ciphertext )>

Everything decrypt needs travels with the ciphertext — which key id wrote it, the salt, the IV, the GCM tag. That's what makes seamless upgrades possible. The clever bit is backward compatibility: older 1.x releases (pre-1.2) wrote an unversioned base64(iv || tag || ciphertext) blob with a sha256-derived key. On decrypt, the code checks for the v2. prefix — present means versioned path, absent means legacy path. And the prefix is unambiguous because . isn't a base64 character, so legacy ciphertext can never accidentally look versioned. No flag column, no migration, no guessing. Old data keeps decrypting unchanged. Versioning your serialized formats from day one — and choosing a delimiter that can't appear in the payload — is the kind of small decision that saves a brutal migration later.

Context binding (AAD)

AES-GCM supports Additional Authenticated Data, and the package exposes it as context binding. You bind ciphertext to a context — a user id, a column name — and that same context is required to decrypt:

$cipher = $encrypter->encryptWithContext('012345678', 'user:123');
$plain  = $encrypter->decryptWithContext($cipher, 'user:123'); // wrong context throws

Why care? This defends against a sneaky class of attack: moving valid ciphertext from one row or column to another. Without AAD, an attacker (or a buggy migration) could copy user A's encrypted SSN into user B's row and it would decrypt fine. Bind the context to user:123 and that ciphertext is worthless anywhere else. It's cheap insurance against data being shuffled around.

Key rotation

Hand the encrypter a KeyRing instead of a single key, and rotation becomes a non-event:

use CleaniqueCoders\PiiProtection\Encryption\KeyRing;

$encrypter = new OpenSslEncrypter(new KeyRing(
    ['2024' => $oldKey, '2025' => $newKey],
    currentId: '2025', // encrypt with this; '2024' ciphertext still decrypts
));

New writes use the current key. Old ciphertext keeps decrypting with whichever key its embedded id points to (remember that versioned format — the key id rides along). No big-bang re-encryption migration. You rotate forward, and old data re-encrypts lazily as it's touched, or never, and it still works. Anyone who's tried to re-encrypt a 50-million-row table in one shot knows why this design exists.

The trap: never query an encrypted column

Here's the consequence I deferred earlier. Because encryption is non-deterministic — random IV and salt every call — the same value encrypts to different ciphertext each time. Which means:

-- This will NEVER match. Don't do it.
SELECT * FROM users WHERE email_cipher = ?

This is the single most common mistake with at-rest encryption, and the package treats it as a guardrail worth shouting about. The fix is a blind index — a deterministic, one-way HMAC you store alongside the ciphertext and query instead:

use CleaniqueCoders\PiiProtection\Encryption\HmacBlindIndex;

$blind = new HmacBlindIndex(key: $indexKey);

$row = [
    'email_cipher' => $encrypter->encrypt($email),  // for retrieval/display
    'email_index'  => $blind->index($email),        // for WHERE email_index = ?
];

$blind->matches($email, $row['email_index']); // true

The index confirms a match — it never reveals the value, and it's not reversible. matches() compares in constant time (hash_equals), so you're not leaking timing information either. You get equality lookups on encrypted data without compromising the encryption. (If you don't need the value back at all, just hash or mask it and skip the cipher column entirely.)

There's one trap worth calling out, because it's the thing people actually get wrong: the index is computed on the exact bytes you pass. John@Acme.com and john@acme.com produce different indexes, so a naive email lookup silently misses. The fix is a normaliser — applied at both write and query time:

$blind = new HmacBlindIndex(
    key: $indexKey,
    length: 32, // hex chars; trade storage for collision-resistance
    normaliser: fn (string $v) => strtolower(trim($v)),
);

Lowercase-and-trim the value before hashing and your lookups behave the way users expect. The length knob lets you shorten the stored index (down from the full 64 hex chars) when collision-resistance matters less than storage — a deliberate trade-off you get to make per column.

This whole area is the kind of thing that's obvious in hindsight and a production incident in foresight. Worth internalizing.

Redaction — where audit logs get cleaned up

This is the part I reach for most. You've got a change-log payload (old_values / new_values, or any nested map) about to be written to an audit table, and it's full of PII. ArrayRedactor walks it and masks only the fields you name — recursing into nested arrays and JSON-decoded structures — leaving everything else untouched.

use CleaniqueCoders\PiiProtection\ArrayRedactor;
use CleaniqueCoders\PiiProtection\Masking\TailStrategy;

$redactor = new ArrayRedactor(new TailStrategy(visible: 4));
$clean = $redactor->redact($payload, ['phone', 'national_id']);

Two features make this genuinely useful in real schemas rather than toy examples.

Per-field strategies — each field gets the right masking in a single pass:

$clean = $redactor->redact($payload, [
    'email' => new EmailStrategy,
    'phone' => new TailStrategy(visible: 4),
    'nric'  => new HashStrategy,
    'name',  // bare name → uses the redactor's default strategy
]);

Dot-path and wildcard targeting — so you mask a precise location, not any key that happens to share a name:

$clean = $redactor->redact($payload, [
    'user.phone',        // only user.phone, not a top-level "phone"
    'users.*.phone',     // every users[].phone
    'contact.email' => new EmailStrategy,
]);

That users.*.phone wildcard is the difference between this being a demo and being something you can point at a real nested API payload.

Redacting objects and DTOs

If you're working with typed objects instead of arrays, tag the properties with an attribute and let ObjectRedactor handle it:

use CleaniqueCoders\PiiProtection\Attributes\Pii;
use CleaniqueCoders\PiiProtection\ObjectRedactor;
use CleaniqueCoders\PiiProtection\Masking\{EmailStrategy, FullStrategy};

class User
{
    public function __construct(
        #[Pii] public string $name,
        #[Pii(strategy: EmailStrategy::class)] public string $email,
        public int $age, // untagged — copied through untouched
    ) {}
}

$clean = (new ObjectRedactor(new FullStrategy))->redact($user);
// ['name' => '********', 'email' => '****@acme.com', 'age' => 30]

Declaring sensitivity at the property is a nice pattern — the DTO becomes self-documenting about what's PII, and the redaction logic doesn't live in some far-away config list that drifts out of sync.

Scrubbing free text

Named fields are easy. The harder problem is PII buried in unstructured text — log lines, exception messages, user comments — where there's no "field" to target. PiiScrubber runs pattern detectors over free text:

use CleaniqueCoders\PiiProtection\Detection\PiiScrubber;

(new PiiScrubber)->scrub('contact john@acme.com from 192.168.1.42');
// "contact ************* from ************"

(new PiiScrubber)->detect($logLine);
// [['type' => 'email', 'value' => ..., 'offset' => ...], ...]

Built-in detectors cover email, credit card, Malaysian NRIC, IPv4, and phone numbers (the phone and NRIC patterns are tuned for Malaysian formats). There's a subtle design decision in here worth stealing: the detectors run in a fixed order, broadest pattern first. Credit cards get masked before the phone-number detector runs, because a 16-digit card number can otherwise partially match a phone pattern and you'd end up with half-masked garbage. When you're chaining regex replacements over the same string, order isn't cosmetic — it's correctness.

detect() is the non-destructive sibling: it returns each hit's type, value, and byte offset without touching the text, which is handy when you want to log that PII was present without logging the PII itself. You can also restrict which detectors run by passing types: ['email', 'nric'] to the constructor.

For anything bespoke, wrap a pattern in RegexStrategy:

use CleaniqueCoders\PiiProtection\Masking\RegexStrategy;

(new RegexStrategy('/\d{10}/', new TailStrategy(visible: 4)))->mask('ref 0123456789');
// "ref ******6789"

Pipe this into a log processor and your log files stop being a compliance liability.

Tokenization

Sometimes you don't want the value or a reversible cipher floating around your main system — you want an opaque placeholder, with the real value parked somewhere isolated. That's tokenization:

use CleaniqueCoders\PiiProtection\Tokenization\{Tokenizer, ArrayVault};

$tokenizer = new Tokenizer(new ArrayVault);

$token = $tokenizer->tokenize('012345678'); // "tok_9f3a..." — reveals nothing
$tokenizer->detokenize($token);             // "012345678"
$tokenizer->forget($token);                 // drop the mapping

An in-memory ArrayVault ships for tests and simple cases. For production you implement the Vault contract against wherever you actually want the mapping to live — a separate secured datastore, an external tokenization service, whatever. The token itself reveals nothing, so your primary database only ever sees tok_....

The shape of the thing

The whole architecture is contracts plus small, swappable implementations:

Contracts/        Encrypter, ContextualEncrypter, MaskStrategy, Redactor, Vault
Masking/          Tail, Full, Email, Hash, CreditCard, Ip, Name, Nric, Regex
Encryption/       OpenSslEncrypter, KeyRing, HmacBlindIndex
Detection/        PiiScrubber
Tokenization/     Tokenizer, ArrayVault
Attributes/       #[Pii]
Exceptions/       PiiException → EncryptionException, DecryptionException
ArrayRedactor · ObjectRedactor · PiiManager

Consumers depend on the contracts, not the concretions — so every piece is swappable. Don't like the OpenSSL implementation? Implement Encrypter yourself and the rest of the library doesn't notice. Want a masking shape that isn't in the box? One method, mask(string): string, and you're done.

Failures throw typed exceptions: EncryptionException and DecryptionException, both extending PiiException, which extends RuntimeException — so existing catch blocks keep working while you can catch precisely when you want to.

A few things that matter when you're deciding whether to trust a security-adjacent dependency: it has zero runtime dependencies (just PHP 8.4, ext-openssl, ext-mbstring — Pest, PHPStan and Pint are dev-only), every masking strategy is multibyte-safe (mb_* throughout, so non-ASCII names slice by character not byte), PHPStan runs at level max, and the suite includes mutation testing plus a test that fails the build if a stray dd(), dump(), or ray() is left in src/. For a library whose whole job is handling sensitive data, that level of paranoia about its own correctness is the point.

When you'd reach for this

It earns its place when:

you handle PII in places the framework doesn't boot — workers, CLI tools, microservices, webhook handlers;
you need audit/change logs that don't leak personal data;
you want encryption at rest with a sane rotation story and searchable lookups via blind index;
you're under PDPA / GDPR / SOC 2 and need to show your PII handling is deliberate, not incidental.

If all you ever do is Crypt::encrypt() inside a single Laravel monolith and nothing else, the framework's built-in is fine. The value of going pure-PHP shows up the moment your data crosses a boundary the framework doesn't own — and in any non-trivial system, it always does.

It's MIT-licensed and on Packagist:

composer require cleaniquecoders/pii-protection

Repo and full docs (architecture, usage, API reference): github.com/cleaniquecoders/pii-protection.

If you've got a PII shape that isn't covered yet, the strategy contract is one method — PRs welcome.

Screenshot-Driven Vibe Coding: Why Your AI Workflow Needs a Glossary Step

Nasrul Hazim Bin Mohamad — Fri, 22 May 2026 00:11:45 +0000

The other day I came across a Claude Code todo list that looked like this:

✓ Read and identify all screenshots
✓ Categorize screenshots into 4 groups
◼ Create folders and move/rename screenshots
☐ Write business requirements doc per screenshot

Four steps. Clean. The kind of plan a vibe coder would screenshot and post on X with the caption "AI is unreal right now."

And honestly — it is a good plan. Better than 90% of what I see in the wild. But it's also one tiny step away from producing 30 beautifully written documents that quietly contradict each other.

Let me walk you through why this strategy works, where it breaks, and the one step I'd add before you let your AI write a single requirement.

The strategy, decoded

Before we critique anything, let's give credit where it's due. This workflow has three things going for it that most vibe coding sessions don't.

It uses screenshots as the source of truth. Most people start vibe coding from a vague idea in their head — "build me a project management app like ClickUp but cheaper". The AI has nothing concrete to anchor on, so it hallucinates a generic CRUD app, and you spend the next three days correcting it. Screenshots flip this. They're concrete. They show real states, real data, real edge cases. An AI looking at a screenshot can't drift as far as one listening to a wish.

It categorizes before it documents. The "4 groups" step is the unsung hero here. Without grouping, you end up with thirty disconnected requirements docs that don't share vocabulary. Grouping forces pattern recognition — these eight screens are all CRUD on the same entity, these five are reporting, these three are settings. That clustering naturally maps to modules or bounded contexts later, which is exactly what you want when you start translating documents into code.

It produces atomic, reviewable artifacts. One BRD per screenshot. Small, self-contained, easy to diff, easy to hand to Claude Code with a prompt like "generate the Livewire component for this spec." You can iterate on one BRD without rewriting the whole project.

This is genuinely a good foundation. If you stopped reading here and ran with it, you'd be ahead of most teams.

But we're not stopping here.

Failure mode #1: BRDs without a shared vocabulary

Here's what happens when you skip from categorization straight to writing BRDs.

Screenshot 03 shows a customer list. The AI writes: "The system shall display a paginated list of **Customers."

Screenshot 11 shows a customer detail page. The AI writes: "The **Member* profile shall include..."*

Screenshot 19 shows the same person logging in. The AI writes: "Upon authentication, the **User* is redirected..."*

Screenshot 24 is a B2B contact view. The AI writes: "Each **Account* has a primary contact..."*

Customer. Member. User. Account. Four words. Same entity. Different document. Different author session. Different vibes.

Now imagine you feed all 30 BRDs to Claude Code and ask it to generate migrations. Watch what happens.

You get a customers table, a members table, a users table (probably from Laravel's default), and an accounts table. None of them reference each other. The Eloquent relationships are guesswork. Half your Actions take Customer $customer, the other half take User $user, and your form requests use both interchangeably.

This is the most common failure I see in screenshot-driven workflows, and it never shows up in the demo. It shows up in week three, when you realize half your codebase is talking past itself.

The fix is a vocabulary extraction step. Before any BRD gets written, you produce a glossary.md that looks something like this:

| Term     | Definition                              | Aliases                  |
|----------|-----------------------------------------|--------------------------|
| Customer | An organisation that purchases services | Account, Client          |
| Member   | An individual user within a Customer    | User, Contact, Staff     |
| Order    | A purchase transaction                  | Sale, Invoice (informal) |

Now when the AI writes BRD-019, it consults the glossary, sees that "Member" and "User" are aliases for the same concept, and picks one canonical term. Suddenly your thirty documents speak the same language.

Failure mode #2: Screen-driven design is not system design

Screenshots tell you what the user sees. They don't tell you what the system does.

Look at any login screen. The screenshot shows a form with email, password, and a button. The BRD writes itself: "User enters credentials, system authenticates, user is redirected to dashboard."

What the screenshot doesn't show:

The rate limiter that locks the account after five failed attempts
The audit log entry that records every login attempt, successful or not
The webhook that fires to your CRM when a new user logs in for the first time this month
The background job that recomputes the user's permission cache
The SSO redirect path that bypasses the password field entirely
The API endpoint that mobile clients use, which doesn't render this form at all

None of that is in the picture. All of it is in the system.

If you're building a SaaS — and especially if you're in the kind of architecture I tend to work in, where you've got a hub-and-spoke pattern with things like identity providers, API gateways, and webhook routers — half your architecture lives behind the UI. A pure screenshot-driven workflow will miss it entirely.

The fix is to add a step per group (not per screenshot) where you explicitly list the non-UI concerns:

Background jobs and scheduled tasks
Webhooks emitted and consumed
Permission matrix (who can do what)
Audit and observability requirements
API contracts for non-UI consumers
Integration points with other modules

This doesn't need to be exhaustive on the first pass. It just needs to exist so you remember to look behind the curtain.

Failure mode #3: Losing the trail

The original workflow says "create folders and move/rename screenshots." Good — but rename them to what?

If your screenshots become screenshot_001.png, screenshot_002.png, you've lost the only useful thing you could have encoded: traceability.

Three months later, when you're debugging a Livewire component and you want to know "what was the original requirement for this?", you want to be able to trace:

Code:        app/Livewire/CustomerList.php
   ↑ generated from
BRD:         docs/brd/g01-s03-customer-list.md
   ↑ extracted from
Screenshot:  screenshots/g01-customers/s03-list-view.png

The naming convention does this work for you, silently. Something like g01-s03-customer-list.png tells you immediately: group 1, screen 3, the customer list. The BRD inherits the same ID. The generated code references it in a docblock. Now you have a chain of custody from pixel to production.

This costs you nothing at rename time. It costs you everything if you skip it.

Failure mode #4: Inconsistent BRD structure

If you let the AI freestyle each BRD, you'll get thirty documents with thirty slightly different structures. One has a "User Stories" section, another has "Use Cases", a third has "Functional Requirements", a fourth jumps straight into a numbered list of behaviours.

This isn't a vibe problem, it's a parsing problem. When you later want to feed these BRDs into Claude Code to generate code, the AI does much better with predictable structure. Same headings, same order, same vocabulary for sections.

Define the template once, before the loop:

# {Screen ID} — {Screen Name}

## Purpose
What this screen exists to do, in one sentence.

## Actors & Permissions
Who can access this screen, and what role gates apply.

## Entities Referenced
List of glossary terms this screen interacts with.

## User Actions
For each action: trigger, validation rules, side effects, success state, failure state.

## States
Empty state, loading state, error state, success state.

## Non-Functional Notes
Performance expectations, accessibility, audit requirements.

## Open Questions
Things the screenshot doesn't tell us and we need to confirm.

Now every BRD looks the same. Claude Code knows exactly where to look for "what validation rules apply to the Save button." Your reviewers know exactly where to add comments. Your future self thanks you.

The refined workflow

Putting it all together, here's what I'd actually run:

1. ✓ Read and identify all screenshots
2. ✓ Categorize into groups (by feature area, not screen type)
3. ◼ Create folders and rename with traceable IDs (g{NN}-s{NN}-{slug})
4. NEW: Extract shared entities, enums, and permissions → glossary.md
5. NEW: Define the BRD template once
6. ☐ Write BRD per screenshot, referencing the glossary
7. NEW: Per group, document non-UI concerns (jobs, webhooks, audits, APIs)
8. NEW: Synthesise — produce the domain model, module boundaries, Action inventory

Steps 4, 5, 7, and 8 are the ones that turn a demo into a system.

Step 8 is where this becomes powerful, by the way. Once you have a glossary, BRDs in consistent format, and non-UI concerns mapped, you can feed all of it to Claude Code with a prompt like:

Given this glossary and these BRDs, generate the Eloquent models with relationships, Form Requests, invokable Actions, and Pest tests for the Customers module.

And the output will actually fit. The naming will be consistent. The relationships will make sense. The tests will reference the right entities. Because you did the upstream work of giving the AI a coherent context to operate in.

The lesson nobody puts on the screenshot

If you take one thing from this, take this:

AI is excellent at extraction. Humans must still define the schema of what's extracted.

The screenshot-to-BRD workflow looks like the AI is doing all the work. It isn't. It's doing the typing. The thinking — the categorization, the vocabulary, the template, the boundaries between modules — that's still yours. Skipping those steps doesn't speed you up. It just defers the cost to a later point in the project where it's ten times more expensive to fix.

Vibe coding isn't about letting the AI decide. It's about giving the AI a structured enough world that its decisions stop being random.

Add the glossary step. Define the template. Document what the screenshot doesn't show. Encode the trail in your filenames.

Then let it rip.

If you've tried screenshot-driven workflows on your own projects, I'd love to hear which failure modes you've hit and how you worked around them. Drop a comment.

Here's How I Build Products Without Losing My Mind.

Nasrul Hazim Bin Mohamad — Tue, 07 Apr 2026 00:58:17 +0000

I've been building software for over a decade.

Laravel trainer. Package author. Solution architect. Juggling multiple products at once — G8Stack, G8ID, Nadi, GatherHub, Warung POS, and more.

And for a long time, I had the same problem every developer has.

I'd jump into code before the thinking was done.

Half-built features. Scope creep. Vague requirements that sounded clear in my head but turned into a mess the moment I opened my editor. I wasn't building products — I was chasing ideas.

Something had to change.

The Shift: Blueprint Before Code

The turning point wasn't a new framework or a new tool. It was a mindset shift.

Build the blueprint first. Code later.

Sounds obvious. But most of us don't actually do it. We treat planning as a formality — something we rush through so we can get to the "real" work.

I stopped doing that. And everything changed.

Here's the workflow I landed on.

Phase 1 — Idea to Clear Direction

Every product starts with a brainstorm. No filters. No structure. Just dumping everything out of my head.

But I don't do this alone.

I bring Claude into the conversation early — not to generate ideas, but to stress-test them. I'll describe what I'm thinking and let Claude push back: Who exactly is this for? What happens if the user does X? Have you considered this edge case?

It's like having a thinking partner available at 2am who never gets tired of your half-formed ideas and isn't afraid to point out the holes.

By the end of this phase I can answer clearly: what exactly am I building, for who, and why does it matter? And more importantly — what are the constraints, the risks, and the things I hadn't thought of yet.

Only then do I move forward.

This phase sounds simple. But skipping it — or rushing through it alone — is the number one reason products stall. You can't build what you haven't clearly thought through.

Phase 2 — Name It. Own the Domain.

Before any file is created, before any command is run — I name the project.

This sounds like a small thing. It isn't.

The name shapes everything: the repo, the folder structure, the domain, the brand, the way you talk about it to clients. Getting it wrong early means renaming things later, and renaming things is painful.

So I take the time. I discuss naming options with Claude — checking for clarity, memorability, and whether it communicates what the product actually does. Then I check domain availability immediately. If the domain isn't available, I keep going until I find a name where both the name and the domain work together.

Only when the name is locked and the domain is secured do I move to the next step.

Phase 3 — Kickoff

With a name in hand, I scaffold the project using kickoff.my — my own tool for getting Laravel projects started with the right foundation.

The project name drives everything here: folder name, repo name, namespace, environment config. It all flows from that one decision made in Phase 2.

Phase 4 — The CLAUDE.md (The Blueprint)

Now I write the CLAUDE.md — inside the project that was just created.

Think of it as a structured brief — not for a client, but for Claude Code (my AI coding assistant). It covers what I'm building, the tech stack, the architecture decisions, naming conventions, and phase-by-phase plan.

Hard cap: 40KB. That constraint keeps me honest. If I can't describe the product in 40KB of structured markdown, I probably don't understand it well enough yet.

Everything that doesn't fit goes into a REFERENCE.md — detailed data models, edge cases, compliance requirements, anything I need visible but not in the main file.

Between the two files, Claude Code has everything it needs to understand the project cold — without me explaining context every single session.

From there, Claude Code reads the blueprint and fills in the docs/ folder — expanding on specs, documenting the data model, breaking down each phase in detail. Full visibility. Nothing hidden.

Phase 5 — GitHub Setup (Before a Single Line of App Code)

This is the part most developers skip entirely.

Before I write any application code, Claude Code creates the GitHub repo and auto-generates Issues based on the phases in my plan. Milestones. Labels. Everything organised.

Now I have a project board that reflects the actual plan — not something I backfilled after the fact.

This alone has saved me hours of context-switching and "wait, what was I building next?"

Phase 6 — Build Phase by Phase

Only now do I start coding.

Each phase has defined deliverables. Each GitHub Issue maps to a real milestone. Claude Code works within the documented context — so there's no guesswork, no AI hallucinations about what I "probably meant", and far fewer errors.

When I finish a phase, I close the issues, review what changed, and update the docs before moving to the next one.

It feels slow at first. It isn't. It's the fastest way I've ever shipped a product that actually works the way I intended.

Bonus: Agent Skills

On top of all this, I maintain a personal library of Claude Code skills — reusable patterns that encode my way of doing things.

Pest testing. Livewire/Flux patterns. API lifecycle. CI/CD pipelines. Package development. Each skill is a structured file that tells Claude Code exactly how I want a thing done.

If you're curious: github.com/nasrulhazim/agent-skills

The Real Lesson

The reason this workflow works isn't Claude. It's not the tools. It's the constraint of having to think clearly before building.

When you write a proper blueprint, you catch the problems that would have killed your project at phase 3. You make architecture decisions consciously instead of by accident. You know — before you write a line of code — what done looks like.

AI just makes the execution faster. The clarity still has to come from you.

Want to Learn This or Work With Me?

If you're a developer or founder who wants to build smarter — not just faster — here's how we can work together:

→ Learn: I run Laravel training sessions covering architecture, clean code patterns, and production-grade development. Reach out to me and ask about upcoming sessions or custom workshops for your team.

→ Hire: Need a solution architect who can take your idea from zero to structured, shippable product? That's exactly what I do. See what I've built at nasrulhazim.com/projects and reach out at nasrulhazim.com.

→ Follow along: I document the journey — products, patterns, and lessons learned — right here on dev.to. Hit follow so you don't miss the next post.

Blueprint first, code later. Build the map before you start the journey.

Laravel Artisan Runner — Run Artisan Commands from the Browser, Safely

Nasrul Hazim Bin Mohamad — Mon, 30 Mar 2026 08:49:32 +0000

The Problem

Every Laravel developer knows the drill. Someone on the team needs to clear the cache, run migrations, or trigger a seeder — but they don't have SSH access. So they ping you on Slack. You SSH in, run the command, confirm the output, and go back to what you were doing.

Multiply that by a dozen teammates and a handful of environments, and it becomes a real productivity drain.

I built Laravel Artisan Runner to solve this. It's a package that lets you expose pre-approved Artisan commands through a clean, Livewire-powered web interface — with full audit logging, queued execution, and notifications baked in.

What It Does

At its core, Artisan Runner gives you three things:

A web UI to browse, configure, and execute Artisan commands
An allowlist system so only approved commands can be run
A complete audit trail of every execution — who ran what, when, with what parameters, and what happened

Every command runs through a queued job. No blocking HTTP requests. No timeouts on long-running migrations.

Installation

composer require cleaniquecoders/laravel-artisan-runner

php artisan artisan-runner:install

php artisan migrate

That's it. Three commands and you're up.

The install command publishes the config, migrations, views, and assets in one shot. Then drop the component into any Blade view:

<livewire:artisan-runner::command-runner />

The default route is /artisan-runner, protected by web and auth middleware.

Configuration: Three Discovery Modes

The package supports three ways to determine which commands are available.

Manual (Default — Safest)

Only commands you explicitly list in allowed_commands are available:

// config/artisan-runner.php

'discovery_mode' => 'manual',

'allowed_commands' => [
    'cache:clear' => [
        'label'       => 'Clear Cache',
        'description' => 'Flush the application cache.',
        'group'       => 'Cache',
        'parameters'  => [],
    ],
    'migrate' => [
        'label'       => 'Run Migrations',
        'description' => 'Run database migrations.',
        'group'       => 'Database',
        'parameters'  => [
            ['name' => '--force', 'type' => 'boolean', 'label' => 'Force (production)', 'default' => false],
            ['name' => '--seed',  'type' => 'boolean', 'label' => 'Run seeders',        'default' => false],
        ],
    ],
],

Auto Discovery

Surfaces all Artisan commands minus your exclusion list:

'discovery_mode' => 'auto',

'excluded_commands'   => ['down', 'up', 'serve', 'tinker', 'db:wipe'],
'excluded_namespaces' => ['make', 'schedule', 'queue', 'stub'],

Good for development. I wouldn't recommend this for production without a tight exclusion list.

Selection

A middle ground — only explicitly included commands are discovered, then merged with your manual entries:

'discovery_mode' => 'selection',
'included_commands' => ['cache:clear', 'migrate', 'config:cache', 'route:cache'],

There's also a CLI tool to help you build your command list:

php artisan artisan-runner:discover
php artisan artisan-runner:discover --output=json
php artisan artisan-runner:discover --dry-run

How It Works Under the Hood

The architecture follows a clean action-based pattern:

User clicks "Run"
  → Livewire CommandRunner component
    → RunCommandAction (validates against allowlist)
      → Dispatches RunArtisanCommandJob to queue
        → Job calls Artisan::call()
          → Output + exit code saved to CommandLog
            → Notification dispatched (if enabled)

The Audit Log

Every execution creates a CommandLog record:

CommandLog::create([
    'uuid'       => Str::uuid(),
    'command'     => 'migrate',
    'parameters'  => ['--force' => true],
    'status'      => 'pending',  // pending → running → completed/failed
    'ran_by_type' => 'App\Models\User',
    'ran_by_id'   => 42,
]);

The status lifecycle is simple:

pending → running → completed
                  → failed

Each log tracks start time, finish time, full output, and exit code. The Livewire component polls every 5 seconds, so you see status updates in real time.

Query your logs programmatically:

use CleaniqueCoders\ArtisanRunner\Models\CommandLog;
use CleaniqueCoders\ArtisanRunner\Enums\CommandStatus;

// Recent failures
CommandLog::where('status', CommandStatus::Failed)->recent(7)->get();

// Who's been running commands
CommandLog::with('ranBy')->latest()->take(20)->get();

Smart Parameter Rendering

The UI automatically renders the right input type based on parameter definitions:

Arguments (positional) → text inputs
Boolean flags (--force, --seed) → checkboxes
Numeric options (--step=5) → number inputs
String options → text inputs

One gotcha I hit early: Livewire doesn't play well with wire:model bindings that have -- prefixes (like parameterValues.--force). The fix was to use index-based keys internally and map them back to parameter names when dispatching. Small detail, but it would've bitten anyone building this.

Notifications

When a command completes or fails, the package can notify a configurable user via any Laravel notification channel:

'notification' => [
    'enabled'  => true,
    'channels' => ['database', 'mail'],
    'notifiable' => [
        'model'      => \App\Models\User::class,
        'identifier' => 'email',
        'value'      => env('ARTISAN_RUNNER_NOTIFY_EMAIL', 'ops@yourdomain.com'),
    ],
],

The notification includes the command name, status, exit code, and execution duration. Wire it up to Slack, Discord, or whatever your team uses.

Security: Built Paranoid by Default

This is a package that runs shell commands from a web interface. Security isn't optional.

Allowlist-first. The default mode is manual. Nothing runs unless you explicitly approve it.

Auth-protected routes. Default middleware is ['web', 'auth']. Tighten it further:

'route' => [
    'middleware' => ['web', 'auth', 'role:admin'],
],

Dangerous commands pre-excluded. Even in auto-discovery mode, commands like down, db:wipe, migrate:fresh, tinker, and serve are excluded out of the box.

Full audit trail. Every execution is logged with who triggered it (polymorphic relation — works with any model, not just User).

No retries. Failed jobs stay failed. You investigate, you don't auto-retry migrate --force in production.

Timeout protection. Commands are killed after 300 seconds. No runaway processes.

Livewire 3 + 4 Compatibility

The package supports both Livewire 3 and 4. The service provider handles registration automatically:

if (method_exists(Livewire::class, 'addNamespace')) {
    // Livewire 4
    Livewire::addNamespace('artisan-runner', __DIR__ . '/Livewire');
} else {
    // Livewire 3
    Livewire::component('artisan-runner::command-runner', CommandRunner::class);
}

No feature flags. No config toggles. It just works.

When Should You Use This?

Great fit:

Admin dashboards where non-technical staff need to trigger maintenance tasks
Deployment pipelines where you want a "run post-deploy tasks" button
Multi-tenant apps with per-tenant cache clearing or migrations
Teams where not everyone has SSH access but everyone needs to clear caches

Not ideal for:

Interactive commands (tinker, make:model)
Long-running batch jobs that exceed 5 minutes
Anything that needs real-time streaming output (it captures output after completion)

Stack Compatibility

	Supported
PHP	8.3+
Laravel	11, 12, 13
Livewire	3, 4
Tailwind	4 (via CDN)

Try It Out

composer require cleaniquecoders/laravel-artisan-runner
php artisan artisan-runner:install
php artisan migrate
php artisan queue:work

Then visit /artisan-runner in your browser.

Source code: github.com/cleaniquecoders/laravel-artisan-runner

I'm Nasrul Hazim, a software engineer from Malaysia building Laravel packages and tools. Find more of my work at nasrulhazim.com.

DEV Community: Nasrul Hazim Bin Mohamad

One Nullable Timestamp, Four Account States: Deriving User Status in Laravel

The trap: a status column

What we actually store: one nullable timestamp

Status is derived, never stored

The enum carries its own presentation

Deriving the state isn't enforcing it

Pest: pin the precedence and the eviction

Takeaway

Deep-Linkable Livewire: Scoping a Browser to the Thing You Clicked

The core idea: a URL-bound property

The edge case everyone forgets: untrusted input

Stripping secrets out of a details modal

A test worth writing

Takeaway

Why an encrypted config backup breaks when you move servers — and how I fixed it in laravel-config-backup

The real cause: Crypt is bound to APP_KEY

The fix: decrypt on the way out, re-encrypt on the way in

Authz: one source of truth, not scattered checks

Keep it honest with a test

The takeaway

Shipping a Livewire 4 + Flux admin UI inside a package: four gotchas that 500'd on me

1. A Livewire 4 component name can't contain ::

2. Flux ships Heroicons, not Pro/Lucide names

3. Don't @vite host assets that don't exist

4. A non-null layout default defeats your own fallback

Bonus: prove it end-to-end in the workbench

The takeaway

A test that catches the bug your feature tests can't see

The bug: wrong icon name, crashes only at runtime

Why feature tests don't catch it

The fix: a static test that reads the Blade and validates every icon

When to reach for this pattern

Making encrypted Laravel config backups portable across APP_KEYs

Why APP_KEY portability is even a thing

The restore sequence

The bug: a warm encrypter cache

Lock the test around the actual failure

The other 1.1.0 changes, briefly

Takeaway

Building a Permission-Gated MCP Server in Laravel (Without Opening a Backdoor)

MCP is a third front-end, not a new set of powers

Tool base class: gate first, work second

Tiered capabilities via a driver-based contract

Write tools reuse the action classes — no shortcuts

Two servers, two audiences

Testing the gate

Takeaway

Laravel Billing: one package, every gateway, working on day one

The core decision: one package, gateways as a contract

Batteries included: a gateway that needs no merchant account

Headless core, optional UI

The webhook flow, and a replay guard worth stealing

State transitions live in one place

Polymorphic billing: tenancy is optional

A few more details worth noting

When you'd reach for this

PII Protection in PHP without a framework holding the leash

The one constraint that drove everything

Three jobs, kept separate

Masking strategies

Encryption at rest, done properly

Context binding (AAD)

Key rotation

The trap: never query an encrypted column

Redaction — where audit logs get cleaned up

Redacting objects and DTOs

Scrubbing free text

Tokenization

The shape of the thing

When you'd reach for this

Screenshot-Driven Vibe Coding: Why Your AI Workflow Needs a Glossary Step

The strategy, decoded

Failure mode #1: BRDs without a shared vocabulary

Failure mode #2: Screen-driven design is not system design

Failure mode #3: Losing the trail

Failure mode #4: Inconsistent BRD structure

The refined workflow

The lesson nobody puts on the screenshot

Here's How I Build Products Without Losing My Mind.

The trap: a `status` column

The real cause: `Crypt` is bound to `APP_KEY`

1. A Livewire 4 component name can't contain `::`

3. Don't `@vite` host assets that don't exist