DEV Community: Dmitry Isaenko

I extracted an audit log into my SaaS core, and the review caught it logging the wrong thing

Dmitry Isaenko — Wed, 03 Jun 2026 13:12:12 +0000

This is the next entry in a build-in-public series where I extract a real, production Laravel CRM into a reusable SaaS core, one module at a time, and ship each piece as a Composer package. So far: the foundation layer, auth on top of Fortify, multi-tenancy, and roles & permissions. This one is v0.5.0: the activity log.

And I want to be honest up front about what this module is, because it's easy to oversell.

I did not invent an audit log

The logging itself is spatie/laravel-activitylog. It's great, it's everywhere, and writing my own would be silly. So I didn't.

What I extracted is everything spatie does not give you out of the box, wrapped around it:

every entry carries the device, IP, route, HTTP method and geolocation of the request that caused it, not just "model X changed"
a single super-admin viewer to read all of it
a config registry so the core logs its own events (auth, tenancy) and the host adds its domain events the same way

The value is the integration, not the storage. I say that in every post because the whole point of building in public is not pretending the car is finished when you've shipped an engine.

The one decision worth explaining: this is not a tenant feature

In my CRM, the activity log is a platform-operator tool. The person who reads it is me, the operator, not a company owner looking at their own team. So the log is global. It has no company_id. A super-admin sees everything across every tenant; a company owner never sees it at all.

That sounds like a small thing but it shaped the whole module. There's no tenant scoping to get wrong, no per-company filtering, no risk of one company reading another's trail. The access rule collapses to a single question: are you a super-admin? And super-admin, from the auth phase, is an identity flag resolved through one class, never a role you can hand out by accident.

It also means this module quietly lands the first slice of something bigger: a platform operator console. The activity log is its first screen. I kept the admin shell deliberately tiny (a header, a "super-admin" marker, a slot) so I'm not pretending to build the whole console this week.

The context wrapper

The core records request context on every entry through one place, resolving the device through the fingerprint contract the auth phase already owns (not a second user-agent parser), and redacting secrets before anything is stored.

public function forRequest(?Request $request = null): array
{
    $request ??= request();
    $device = $this->deviceResolver->resolve($request);

    return [
        'user_ip' => $request->ip(),
        'user_device_type' => $device->type,
        'user_os' => $device->os,
        'user_browser' => $device->browser,
        'route_name' => $request->route()?->getName(),
        'request_method' => $request->getMethod(),
        'full_url' => $this->redactUrl($request->fullUrl()),
        // ...
    ];
}

That redactUrl matters. The donor stored the raw URL, which means a password reset link or a 2FA code passed in a query string would land in the audit table in plain text. The package masks the value of any configured PII key before storing, and (a review note, more on reviews below) it does it without mangling the rest of the URL.

Then the review found it logging the wrong thing

Every module in this series goes through a code review before it merges, and every module so far has had the review catch something real. This one was subtle, because the code looked obviously correct.

The donor had a genuine bug I already knew about: it wrote the same user id into both causer_id and subject_id. "who did it" and "what it was done to" were the same row. That's nonsense for an audit log, so the extraction split them: causer is the actor, subject is the object of the action, resolved separately.

My resolver picked the subject off the event by looking for a known property:

foreach (['subject', 'company', 'model', 'invitation', 'employee'] as $property) {
    if (isset($event->{$property}) && $event->{$property} instanceof Model) {
        return $event->{$property};
    }
}

Looks fine. It passed the test I wrote, which used CompanyCreated (an event that only carries a company). Green. Ship it.

Except the review asked the question my test didn't: what about an event that carries more than one model?

EmployeeRemoved carries both the company and the removed employee. My loop checks company before employee, so for "employee removed" it recorded the company as the subject. The object of the action is the person who got removed, and I was logging the building they got removed from. An auditor reading "employee removed, subject: Acme Co" learns nothing about who was removed.

The fix is one line of ordering, plus the comment so the next person understands why order matters here:

// the most-specific OBJECT of the action wins. EmployeeRemoved carries both
// `company` (context) and `employee` (the actual subject), so specific entities
// must be checked before the surrounding company.
foreach (['subject', 'employee', 'invitation', 'model', 'company'] as $property) {

and a regression test that fires EmployeeRemoved and asserts the subject is the employee, not the company. The lesson, again: the bug wasn't in the line, it was in the test that only exercised the easy case.

A quieter one in the geo path

Geolocation is an outbound call to a third party with the user's IP, so it's opt-out, cached, and runs off a queued job. Private and loopback IPs are answered locally and never leave the server.

The job's failed() handler stamped "Unknown" so a row is never left half-enriched. Reasonable. But the review pointed out: the resolver is fail-soft (it returns "Unknown" itself on any network error and never throws), so the only way the job actually fails is if the database write throws, possibly after a real country was already resolved. In that case failed() would clobber correct geo data with "Unknown". The fix is to only stamp Unknown on a row that was never enriched:

if ($activity->geo_updated_at !== null) {
    return; // already enriched; don't overwrite good data with Unknown
}

Small, but it's the kind of thing you only see when someone asks "what is the actual path that reaches this line."

The model-audit trait, fixed

The donor shipped a LogsActivity trait for automatic created/updated/deleted auditing on any model. It was broken in three ways: it overrode spatie's boot method without calling the parent (so spatie's engine never ran), it called a method that didn't exist (fatal on first save), and it wrote every attribute instead of the dirty diff.

The package version throws all that out and uses spatie's native machinery: declare what to log, then decorate the entry with the core's request context through the hook spatie already calls. No engine override, real old-to-new diffs, plus device and IP on every audit row.

What it deliberately is not

Same honesty note I put on every release. v0.5.0 ships the audit log backend and a minimal super-admin viewer. It does not ship the full operator console (statistics, support, billing screens), those arrive with their own phases and slot into the same admin shell. The route-access middleware that logs every request is in the box but off by default, because it's noisy. Domain events (orders shipped, invoices paid) are the host's to register, the core only ships its own auth and tenancy events.

And the model-audit trait writes "HTTP 200, success" on every row, because a model save inside a request is, by definition, a success that reached the database. That's honest for that path, not a status I'm inventing.

Tests, and the close

The package is green: the activity-log suite covers the causer/subject split, the two fixes above, the PII redaction (including the URL-fidelity edge cases the review surfaced), the async geo dispatch and its opt-out, the super-admin gate, and the model-audit diff, plus a frontend test that proves the viewer renders a hostile user-agent as inert text and never as markup. The host integration smoke proves a real company-creation event lands in the log through the live middleware stack.

The pattern that keeps repeating: the extraction is rarely where the bugs are. They show up when a second pass asks the question your own test didn't. "what about the event with two models" found a log that was quietly recording the wrong subject, and it would have sat there looking correct for a long time.

Next up is navigation and the rest of the operator console.

The package is public on GitHub: https://github.com/dmitryisaenko/larafoundry

I wrote my own RBAC instead of reaching for Spatie, and the review caught a privilege-escalation hole

Dmitry Isaenko — Wed, 03 Jun 2026 09:33:18 +0000

This is the next entry in a build-in-public series where I extract a real,
production Laravel CRM into a reusable SaaS core, one module at a time, and ship each piece as a Composer package. Previous entries covered the foundation layer, authentication on top of Fortify, and multi-tenancy. This one is v0.4.0: roles and permissions.

And I'll start with the decision that surprises people.

I didn't use Spatie

spatie/laravel-permission is excellent. I've used it. If you're starting a fresh app, reach for it.

I didn't, for one specific reason: the RBAC in my CRM was already tenant-scoped, and not as an afterthought. Every role assignment and every individual permission grant carries the company it belongs to. The same user can be an admin in company A and a read-only member in company B, and a permission granted in A must never leak into B. My multi-tenancy layer (the previous release) makes company_id the tenant key everywhere, and the access layer was built around that from day one.

Wrapping a generic package to get back to per-tenant roles, custom grant/revoke overrides, and "default roles cloned into every new company" would have been more work than extracting the code that already did exactly that. So I lifted mine, modernized it, and put it through the same security and code review every module gets. (And yes, I say "self-written, not Spatie" in every post about it, because honesty is the whole point of building in public.)

The shape of it

Five tables, nothing exotic:

permissions - the catalog. Globally-unique slugs in module.action form, like company.roles.update. Seeded from config, never invented at runtime.
roles - named bundles of permissions. A company_id (nullable) scopes a role to a tenant. Flags mark whether a role is global, a template, or a custom role an owner made.
role_permissions - which permissions a role grants.
user_roles - a user's roles, each row carrying a company_id (the tenant).
user_permissions - individual grants and revokes, also tenant-scoped, with an is_revoked flag.

The interesting part is not the tables, it's the check. A permission lookup runs in a strict priority order that reads like a sentence:

public function hasPermissionTo(Permission|string $permission, Company|int|null $company = null): bool
{
    if ($this->isSuperAdmin()) {
        return true;
    }

    if ($company !== null && $this->userOwns($company)) {
        return true;
    }

    $slug = $permission instanceof Permission ? $permission->slug : $permission;

    return $this->getAllPermissions($company)->contains($slug);
}

Super-admin first. Then the company owner (everything in their own company). Then, for everyone else, the resolved permission set, which is:

(permissions from company roles) plus (permissions from global roles) plus
(individual grants), minus (individual revokes).

Because the (user, permission, company) row is unique, a permission is either granted or revoked, never both, so that set arithmetic reproduces the old "revoke beats grant beats role" order exactly, while resolving the whole set once per request instead of firing a query per check.

Two bypasses, and only two. The owner bypass reuses the is_owner flag the tenancy layer already owns, so RBAC sits on top of multi-tenancy without duplicating the concept of ownership. Super-admin is an identity flag resolved through the auth layer, never a role, so it can't be granted by accident from a role-management screen.

The hook that finally fired

When I shipped multi-tenancy, company creation dispatched a CompanyCreated event that did nothing yet. I wrote in that release that RBAC would listen to it later.

It does now. A queued listener clones a set of template roles into every new company the moment it's created, so a brand-new tenant starts with sensible roles instead of an empty access table. It's idempotent (a retry won't duplicate roles), and it's queued on purpose: the owner already has full access through the owner bypass, so they never wait on the clone. The cloned roles only matter for the employees they invite later, by which point the job has run.

Then the review found the hole

Every module in this series goes through a code review before it merges, and every module so far has had the review catch something real. This one was a privilege-escalation hole, and it's a good one because the code looked correct.

I wanted owners to be able to delegate employee management. "Let my office manager invite people and assign their roles" is a reasonable thing for a SaaS to support.
So there's a permission, company.employees.grant_permissions, and the endpoint that grants permissions to a member checked for it:

public function updatePermissions(Request $request, int $user): RedirectResponse
{
    $this->authorize('company.employees.grant_permissions');
    // ... validate the requested permission slugs against the catalog ...
    // ... grant them to the target member ...
}

Spot it? The gate checks "are you allowed to grant permissions." It does not check "do you actually hold the permission you're handing out." The requested slugs were validated only against the catalog, which contains every permission in the system, including the ones that manage roles.

So a delegated member with grant_permissions could grant themselves, or anyone else, ANY permission. Including company.roles.delete, company.employees.remove, or the grant permission itself. The office manager you trusted to invite people could quietly promote themselves to full role-admin. A textbook confused deputy: the deputy was allowed to act, but nobody bounded what they were allowed to act with.

The fix is a single rule: you can only hand out what you already hold.

$held = $request->user()->getAllPermissions($company);

foreach ($validated['grant'] ?? [] as $slug) {
    abort_unless($held->contains($slug), 403);
}

The actor's own effective permission set bounds every grant. Owners and
super-admins hold the entire catalog (the bypass returns everything), so nothing changes for them. A delegated member is capped at exactly their own access, and can never grant past it. The same rule applies to assigning roles: you can only assign a role whose permissions are a subset of what you hold, so you can't smuggle a powerful role to someone when you couldn't grant its permissions directly. Two regression tests fail loudly if either ever regresses.

And a second one, hiding in the flow

The review found a quieter bug too, the kind no single function reveals because it's about state moving across a whole flow.

Removing a member from a company is a soft delete: the membership row stays for audit, just flagged removed. But removing a member did nothing to their role assignments. Those user_roles rows just sat there. Two consequences: a custom role that only removed members held could never reach zero holders, so it became permanently undeletable through the UI, and the removed member's grants lingered in the table where a future code path could resolve them.

The fix sits at the right altitude. The tenancy layer already fires an
EmployeeRemoved event. RBAC listens to it:

class RevokeAccessOnEmployeeRemoval
{
    public function handle(EmployeeRemoved $event): void
    {
        $employee = $event->employee;
        $companyId = $event->company->getKey();

        $employee->roles()->wherePivot('company_id', $companyId)->detach();
        $employee->permissions()->wherePivot('company_id', $companyId)->detach();
    }
}

Leave a company, lose your access in that company. Global roles (like the base "authenticated" role every user carries) are untouched, because leaving one company should never change your identity everywhere else.

What it deliberately is not

Same honesty note I put on every release. v0.4.0 ships the RBAC engine and exactly one neutral starter role. It does not ship a pile of business permissions. Orders, inventory, billing actions, all of that belongs to the app you build on top, not the core. The core gives you the mechanism and a config catalog you extend.

The billing-aware access check is still a stub behind an interface (it returns "allowed" until the billing module lands), and the API-token resolver for non-session clients comes in a later phase. I'd rather ship a small honest engine than a big pretend one.

Tests, and the close

The package is green: the RBAC suite covers the check priority, tenant isolation, the clone-on-create job, the two security fixes above, and the Vue permission picker, on top of the host integration smoke that proves it all wires into the real app through the real middleware stack.

The pattern that keeps repeating in this series: the extraction itself is rarely where the bugs are. They show up when a second pass traces state across a whole flow, or asks "this gate lets you act, but what bounds what you act with." That's the part worth slowing down for.

Next up is the activity log.

The package is public on GitHub: https://github.com/dmitryisaenko/larafoundry

Multi-Tenancy from a Live CRM, and the Two Holes the Second Review Found

Dmitry Isaenko — Wed, 03 Jun 2026 09:27:35 +0000

Last time I shipped v0.2.x of LaraFoundry: authentication and users, built on top of Fortify. This post is v0.3.0, and it's the one a SaaS actually needs before anything else makes sense: multi-tenancy. Companies, teams, who-can-see-what.

If you've read the series, you know the pattern by now. I'm not writing this from scratch. I'm extracting it out of a CRM that's been running in production for years, re-reading the old code on the way out, and modernizing it as it lands in the package. Multi-tenancy is the module where that re-reading paid off the most, because the original had a data-isolation bug that had been quietly sitting there the whole time.

And then, because I got cocky, I ran my code review, saw "8 of 12 findings handled," felt good, and almost shipped. Then I ran it a second time. The second pass found two security holes the first one missed. Both real. Both the kind that let one tenant touch another tenant's stuff. More on those at the end, they're the reason I'm writing this one.

What multi-tenancy actually means here

One database, many tenants, row-level isolation. No database-per-tenant, no schema-per-tenant. Every tenant-owned row carries a company_id, and a global query scope makes sure you only ever see rows for the company you're currently acting as.

The core ships both modes behind a config switch:

teams - the tenant is a Company. Users belong to one or more companies, switch between them, invite each other. This is what my CRM uses.
personal - the tenant is the User. No companies at all, every user is their own island. Filtered by user_id instead of company_id, no fake one-person company in the way.

The host picks the mode in config and the rest of the package adapts. Same scope, same trait, different column.

The decision that mattered: fail-closed

Here is the old code, roughly, from the live CRM:

// legacy global scope, simplified
public function apply(Builder $builder, Model $model)
{
    $companyId = session('active_company_id');

    if ($companyId) {
        $builder->where('company_id', $companyId);
    }
    // else: no filter. all rows.
}

Read that else again. If there is no active company in the session, the scope adds no filter, and the query returns every row in the table for every tenant.

In normal use you always have an active company, so this never fired. But "normal use" is not a security boundary. A background job, a console command, a request that hits the model before the active company is resolved, a session that expired mid-request: any of those gives you $companyId = null, and now your tenant scope is wide open. That's a textbook IDOR, fail-open by construction.

The package version inverts it. No resolvable tenant means no rows, not all rows:

public function apply(Builder $builder, Model $model): void
{
    $tenantKey = static::currentTenantKey();

    if ($tenantKey === null) {
        // Fail closed. No tenant resolved -> show nothing, never everything.
        $builder->whereRaw('0 = 1');

        return;
    }

    $builder->where(static::tenantColumn(), $tenantKey);
}

If something goes wrong, you see an empty list. That's annoying. The old behavior was a data leak. I'll take annoying.

The same principle runs through the write path. When you create a tenant-owned model, the company_id is filled automatically from the resolver, and it is not mass-assignable, so a crafted form payload can't set it to someone else's company. And if there's no tenant resolved at create time, it throws instead of writing an orphan row:

static::creating(function (Model $model) {
    $tenantKey = static::currentTenantKey();

    if ($tenantKey === null) {
        throw new RuntimeException('Cannot create a tenant-owned model without an active tenant.');
    }

    $model->setAttribute(static::tenantColumn(), $tenantKey);
});

The resolver, and why it's behind an interface

"Which company am I acting as right now" is a question with more than one answer depending on where you are. In a browser session it's stored per-device. Under an API token (which is coming in a later phase for the mobile app) it'll be derived from the token. I didn't want the tenant scope to know or care which.

So the active tenant comes from a TenantResolver contract:

interface TenantResolver
{
    public function current(Authenticatable $user): ?Tenant;
    public function setCurrent(Authenticatable $user, Tenant|int|null $tenant): void;
    public function forget(Authenticatable $user): void;
}

In teams mode the binding is a SessionTenantResolver that reads and writes user_sessions.active_company_id (the active company lives per-device, on the session row I already track from the auth phase). In personal mode it's a resolver that just hands back the user. Later, the API phase adds a token resolver here and nothing else changes. The scope, the trait, the controllers all keep talking to the interface.

That one seam, by the way, is also where the single nastiest bug of this phase lived. I'll get to it.

The user side is a trait, not a base class

The host's User model already uses the auth trait from the last phase. Tenancy is a second trait that sits next to it:

class User extends Authenticatable
{
    use IsLaraFoundryUser;   // phase 1.1: identity, sessions, 2FA
    use BelongsToTenancy;    // phase 1.2: companies, active company, owner checks
}

BelongsToTenancy gives the user companies(), getActiveCompany(), setActiveCompany(), isOwnerOf(), and the bits the company switcher needs. RBAC (roles and permissions inside a company) is its own trait in the next phase. The point of the trait-slot idiom is that each phase adds a slice without rewriting the model or colliding with the host's own code.

The Company model itself is deliberately thin. The core owns only the columns every multi-tenant app needs (name, slug, uuid, country, the founder). The host extends it and points one config value at the subclass to add business columns. Billing is a phase-3 seam: hasAccess() returns true in the free core today, and the paid billing add-on overrides it with real subscription logic later, without any call site changing.

Invitations, and the email-spoof guard I kept

You invite someone by email. The package stores a 64-char random token and a hard expiry, and emails a link. So far, normal.

The guard that matters is on acceptance. A token alone is not enough to join a company. The logged-in user's email has to match the invited email:

public function isFor(string $email): bool
{
    return mb_strtolower($this->email) === mb_strtolower($email);
}

The legacy app had this, and I kept it, because without it a leaked invite link is a free pass into the company for whoever holds it. With it, the link is only useful to the person it was addressed to.

That felt airtight. It was not. Which brings me to the part I actually wanted to write about.

Now the two holes

I ran my review process, a high-effort multi-angle code review over the diff. First pass: about a dozen findings, I handled the actionable ones, and I had that "this is basically clean" feeling. Then I ran it a second time on the same diff. The second pass surfaced two security findings the first walked right past. Here's both.

Hole 1: company takeover through the invite flow

The email-match guard above checks that the account's email equals the invited email. Fine. But three things lined up:

The accept route was behind auth, but not behind verified.
Local registration sets email_verified_at = null. You can register an account on any email address without proving you own it.
The public invitation landing page was rendering the invited email into its props.

Put those together. An attacker gets a leaked invite link (they leak, links get forwarded, they sit in logs). The public landing page hands them the exact email it was sent to. They register a fresh account on that email, no verification needed. Their email now equals the invited email, so isFor() passes. They accept. They're in a company that was never theirs.

The string match was never the weak part. The weak part was that "has this email" and "owns this email" were treated as the same thing, and the landing page handed out the email for free.

Two fixes. The accept path now requires a verified email, so having the address isn't enough, you have to prove the mailbox is yours:

if (! $invitation->isFor($user->email) || ! $this->hasVerifiedEmail($user)) {
    return redirect('/')->with('error', __('larafoundry::tenancy.invitation.email_mismatch'));
}

And the email came out of the public page's props entirely. The landing page now says "you've been invited to join this company" and nothing about who. If you weren't sent the link, the page tells you nothing useful.

Hole 2: privilege resurrection back to owner

This one is subtler and I like it more.

Removing an employee is a soft delete. The pivot row stays for audit, with is_deleted = true. Re-adding someone restores that same row instead of making a new one (there's a unique constraint on company + user). And re-adding is owner-sticky: if you were already an owner, being re-added as a plain member must not silently demote you. So the new owner flag was OR-ed with whatever the row already had:

'is_owner' => $isOwner || ($existingRow && $existingRow->is_owner),

Looks reasonable. Now walk it through.

Someone is an owner. You remove them (soft delete, row keeps is_owner = true, because removal only flipped is_deleted). Months later you invite them back as a regular member. $isOwner is false. But $existingRow->is_owner is still true from before. The OR brings ownership back. A plain-member re-invite silently hands them owner rights again.

The fix is one line in the removal path: clearing ownership when you soft-remove, so a dormant row never carries a stale owner flag for the OR to pick up.

public function removeEmployee(Authenticatable $user): void
{
    $this->users()->updateExistingPivot($user->getAuthIdentifier(), [
        'is_deleted' => true,
        'is_owner' => false, // don't let a removed owner come back as one
    ]);
}

Owner-stickiness is still there, but now it's scoped to people who are currently members, which is the only place it was ever meant to apply.

Why the second pass caught what the first didn't

I think it's because the first pass and I were both reviewing the same way: read the diff, is each change correct in isolation. Both of these holes are correct in isolation. The accept guard correctly matches emails. The owner-OR correctly preserves ownership. Neither is wrong on its own line. They're only dangerous when you trace state across the whole flow: register -> see email -> accept, or remove -> wait -> re-invite.

"8 of 12 handled" gave me a number that felt like progress and wasn't really telling me about the two that mattered. The second run wasn't smarter, it just looked again with the question "what crosses a tenant boundary," and that question found things "is this line correct" didn't.

The tests

Every piece has Pest coverage, and the regression tests for both holes above are now in the suite, so they can't quietly come back. A couple that I care about:

it('SECURITY: refuses acceptance from an UNVERIFIED account even with the matching email', function () {
    [$company, $invitation] = companyWithInvite('invitee@x.test');
    $unverified = User::create([
        'email' => 'invitee@x.test',
        'email_verified_at' => null,
    ]);

    $this->actingAs($unverified)
        ->post("/invitations/{$invitation->token}/accept")
        ->assertRedirect('/');

    expect($unverified->fresh()->companies()->count())->toBe(0);
});

it('a soft-removed ex-owner re-invited as a member does NOT return as owner', function () {
    // remove the owner, then re-add as a plain member, assert they are not an owner.
});

it('the public landing page does not reveal the invited email', function () {
    $this->withHeader('X-Inertia', 'true')
        ->get("/invitations/{$invitation->token}")
        ->assertOk()
        ->assertJsonMissing(['email' => 'secret-invitee@x.test']);
});

The fail-closed scope has its own tests too: no active tenant returns zero rows, a foreign company's data is invisible, a crafted company_id in a create payload gets overwritten by the resolver and not honored.

The package suite is green (Pest plus the Vue component tests), and then I did the thing that has earned its place in my process: I wired v0.3.0 into the real host app and clicked through it. Create a company, invite someone, switch active company, land on the right page under the verified plus active-tenant middleware. That integration smoke is now seven host-side tests of its own, and it caught a config gotcha (a stale published config file shadowing the new tenancy keys, because Laravel's config merge doesn't add missing sub-keys to a section that already exists). Not a security bug this time, but exactly the kind of thing that only shows up when the package meets a real app.

Where this leaves the core

After three releases the package now has primitives, auth, and multi-tenancy. That's the spine. The next phase is RBAC, roles and permissions inside a company, and the hook for it is already in: creating a company fires an event the roles phase will listen on to seed default roles. Billing comes after that, sitting on the hasAccess() seam that returns true for now.

If you're building a multi-tenant Laravel app, the one thing I'd take from this regardless of my package: make your tenant scope fail closed, and write the test that proves an empty tenant shows nothing. The default-deny version costs you one whereRaw('0 = 1') and saves you the bug I'd been shipping for years.

Code is on GitHub. It's source-available, free for non-commercial use. If you want to follow the build, the repo and the series are the place.

Next: RBAC.

I Rebuilt My Laravel Auth on Top of Fortify (and Two Bugs the Integration Caught)

Dmitry Isaenko — Tue, 02 Jun 2026 13:44:21 +0000

Last time I tagged v0.1.0 of LaraFoundry, the foundation layer of a Laravel SaaS core I'm extracting in public from a live CRM. Primitives only: locale, filters, middleware, a small Vue UI kit. No auth yet.

This post is v0.2.x: authentication and users. And it's the one where two bugs slipped past 114 passing tests and only showed up when I actually wired the package into a real app. More on those at the end, because honestly they were the most useful part.

The decision that mattered: don't hand-roll auth

The legacy CRM had its own auth. Six login methods, custom rate limiting, a hand-written throttle, an admin 2FA built on a single shared secret. It worked for years. But when you re-read that kind of code on the way out, you notice how much of it is security-critical plumbing that Laravel already solved properly.

So I made a call early: the core builds on Laravel Fortify, not on a port of the old controllers.

Fortify is the headless auth backend behind Jetstream. It gives you login, registration, password reset, email verification, password confirmation, and real per-user two-factor (TOTP + recovery codes + QR enrollment + a confirm step) out of the box. No views, just routes and actions. That last part is exactly what you want when your frontend is Inertia + Vue.

The rule I held to: if Fortify already does it, I don't write it. The core only adds what Fortify doesn't cover.

What the core actually adds around Fortify

Fortify is the boring, correct center. The package wraps it with the stuff that's actually mine:

Session tracking. One row per device with a fingerprint (browser, OS, type), IP, login method, last activity, last route. This is what powers an "active sessions" screen and "log out my other devices."
OAuth via Socialite. Fortify doesn't touch social login. The package owns the redirect/callback, with an account-takeover guard (more below).
Blocked / deleted gating. A per-request middleware that logs out an account that got blocked or soft-deleted mid-session.
A IsLaraFoundryUser trait. The host's User model uses it to pick up identity, locale, OAuth fields, 2FA and session tracking, without inheriting anything about companies or roles. Those are separate traits in later phases, so one model can compose them.
Localized auth mail. The verification and reset emails are owned by the core through translation keys, so they ship translated and follow the locale standard from v0.1.0 instead of hardcoding English.
The Inertia/Vue pages. Login, register, forgot/reset, verify, 2FA challenge, 2FA settings, a blocked screen. Fortify is headless, so the UI is ours.

The whole thing is covered with Pest (backend) and Vitest (the Vue pages and UI kit), green CI on PHP 8.2/8.3/8.4.

The OAuth guard worth talking about

Here's the original OAuth callback from the legacy app, simplified:

$user = User::updateOrCreate(
    ['email' => $socialUser->email],
    [/* provider fields, email_verified_at => now() */]
);
Auth::login($user);

Looks fine. It's not.

If someone already has a local account at victim@example.com (registered with a password), and an attacker controls a Google account that asserts the same email, this updateOrCreate quietly links the attacker's provider to the victim's account and logs them in. Account takeover, no exploit needed, just an email collision.

The core resolves strictly instead:

match by provider identity (provider_name + provider_id) first, that's the only unconditional match;
if that misses but the email matches a local account, link only when link_existing is explicitly enabled, otherwise refuse and tell the user to sign in locally and connect the provider from settings;
otherwise create a new account.

Default is refuse. A Pest test pins the takeover case so it can't regress.

(There's a second, narrower issue here I haven't fully closed: a brand-new OAuth account gets email_verified_at = now() trusting the provider's email. For Google/GitHub primary emails that's fine, but I noted it as a hardening task before enabling OAuth in prod. Honesty over polish.)

Now the two bugs

This is the part I actually wanted to write down, because both of them passed every unit test and only died when the package met a real Laravel app.

Bug 1: session tracking on the wrong event

My first design recorded the session row by listening to Laravel's Login event. Clean, framework-native, fires on every login path including registration. Tests were green.

Then I logged in on the real host and got immediately bounced back to the login screen.

Turns out the Login event fires inside the auth guard, and Fortify regenerates the session id again afterwards, in its PrepareAuthenticatedSession step. So my listener wrote a row keyed to a session id that was dead a millisecond later. Then my "is this session still valid" check saw a mismatch and logged the user out. Every single time.

The unit tests never caught it because in isolation there's no second regeneration. you need the actual Fortify pipeline for the timing to bite.

The fix was to stop chasing the event and move tracking into a per-request middleware that runs against the final, live session id. Which, it turns out, is exactly how the old legacy app did it. sometimes the boring old approach was boring for a reason. Bonus: it also revived last_activity and last_route_name, which my event-based version never updated after login.

Bug 2: `views => false` is a trap with Inertia

This one's quick but I lost a good half hour to it.

For an SPA you instinctively set 'views' => false in config/fortify.php. Makes sense, right? You don't want Fortify rendering Blade, your frontend handles screens.

Except views => false doesn't just skip the view rendering. it stops Fortify from registering the GET routes entirely. So GET /login returns 405, and your Fortify::loginView(...) closure never runs.

For Inertia the correct setup is 'views' => true plus a loginView that returns Inertia::render('Auth/Login'). Fortify owns the route, your closure owns what it renders. The docs do say this, I just pattern-matched "SPA = views off" and skipped past it.

The takeaway

114 tests gave me confidence the units were correct. They said nothing about whether the pieces fit together in a real app. The integration smoke test, just spinning up the host and clicking through register / login / 2FA by hand, is where both real bugs lived.

So the workflow stays: extract, modernize, test, review, tag, and then actually run it in a real app before believing any of it.

Next phase is multi-tenancy, lifting the company/team layer out of the same production system. That's the one I'm slightly afraid of.

Code is on GitHub. If you're building something similar on Fortify, the session-id timing thing will get you too, so now you know.

Extracting a Production Laravel App Into a Reusable Core Package (and the Bugs Pest Caught Doing It)

Dmitry Isaenko — Tue, 02 Jun 2026 10:24:09 +0000

There's a particular kind of code that never makes it into a tutorial: the stuff that has been running in production for years, quietly working, written by a younger version of yourself who was in a hurry. It works. It's also a little embarrassing to look at.

I'm extracting that code from Kohana.io - a live CRM/ERP - into LaraFoundry, an open-source SaaS core for Laravel distributed as a Composer package. Not a rewrite from scratch: an extract-and-modernize. The premise is that battle-tested code is worth more than clean code, but only if you actually re-read it on the way out.

This post is the first real code milestone: v0.1.0. The backend primitives and the frontend base. It's also the post where the extraction caught two genuine bugs that had been sitting in production. So this is less "look at my framework" and more "here's what happens when you move old code into the light."

Why extract instead of rewrite

The boring answer is risk. A rewrite throws away every edge case the original code learned the hard way - the weird locale code a real browser sent, the filter parameter someone tried to abuse, the off-by-one in pagination. Extraction keeps those lessons. The cost is that you inherit the original's mistakes too, so the extraction only pays off if it comes with a review gate.

So the workflow for every piece is fixed:

extract from legacy  ->  modernize + harden  ->  Pest tests
   ->  /security-review + /code-review  ->  tag  ->  integrate into host app

The package ships nothing that hasn't been through that pipe. Let's walk the milestone.

What's in v0.1.0

Fourteen PHP classes and a small Inertia/Vue frontend. No auth module yet, no multi-tenancy - those are later phases. This release is the primitives everything else stands on:

Area	What
Locale	A single `SetLocale` middleware (resolution chain), a `ValidLocale` rule, an `Inertia` translation bridge
Query filters	A reflection-based `Filter` base + `Filterable` trait
Middleware	Email-verification gate, IP allow-list, intended-URL capture, appearance
Frontend	vue-i18n bootstrap, a form UI kit, flash toasts, a paginator, a base layout
Tests	39 Pest tests

The interesting part isn't the list. It's what changed between the legacy version and the extracted one.

Locale detection: the rewrite that paid for itself

The legacy SetLocale was actually two near-identical middleware classes - one for guests, one for authenticated users - and it did something I'm not proud of: on a guest's first request it made a synchronous HTTP call to ip-api.com to geolocate them, on the hot path, before rendering anything.

Two of those decisions were wrong, and extracting the code is what forced me to admit it.

Wrong thing #1: blocking network I/O in a request-path middleware. A third-party outage becomes your outage. So in the core, geo-IP is gone from the default path - it lives behind an optional contract a host can opt into:

interface LocaleGeoResolver
{
    /**
     * @param  array<int, string>  $available
     */
    public function resolve(string $ip, array $available): ?string;
}

If you don't configure it, no network call ever happens. The common case - a browser that tells you its language in a header - costs nothing.

Wrong thing #2: trusting input that reaches App::setLocale(). This one is subtle and it's the reason I now validate every single candidate. The resolved locale eventually flows into a filesystem path when the translation bridge loads lang/{locale}.json. A locale value you don't validate is a path-traversal waiting to happen. So the extracted middleware validates every source - user preference, session, cookie, header, geo, default - against an allow-list before it's ever applied:

protected function isAllowed(?string $locale, array $available): bool
{
    return $locale !== null && $locale !== '' && in_array($locale, $available, true);
}

And the fallback re-validates even the configured default, because a misconfigured default shouldn't be able to slip past the allow-list either:

$resolved = $this->detect($request, $available) ?? $default;

if (! $this->isAllowed($resolved, $available)) {
    $resolved = $this->isAllowed($default, $available)
        ? $default
        : ($available[0] ?? 'en');
}

App::setLocale($resolved);

The legacy version also injected <script>window.location.reload()</script> into the response to apply a language change. That's fragile and it breaks Inertia. In the extracted version the locale takes effect on the same request - no reload, no script injection.

One more thing the extraction fixed: the legacy data layer had collected junk locale codes over the years - 'ua' (not a real code; the ISO 639-1 code for Ukrainian is uk), 'English', country slugs. The single allow-list plus a tiny validation rule means that can't happen again:

class ValidLocale implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        $available = (array) config('larafoundry.locale.available', []);

        if (! is_string($value) || ! in_array($value, $available, true)) {
            $fail('The selected :attribute is not a supported locale.')->translate();
        }
    }
}

One source of truth. Everything - URL, cookie, DB, header - is validated against the same list.

Query filters: a reflection trick with a sharp edge

The legacy app had a neat pattern for list filtering: a filter class declares one method per query parameter, and the request keys get dispatched to matching methods.

class ProductFilter extends Filter
{
    public function search(string $value): void
    {
        $this->builder->where('name', 'like', "%{$value}%");
    }
}

Product::filter(new ProductFilter($request))->paginate();

Elegant. Also a loaded gun, if you implement the dispatch naively. If you just take request keys and call $this->{$key}($value), an attacker sends ?apply=... and now they're invoking your base class's apply() method - or any other method on the object - with input they control. Mass method invocation.

Writing the Pest test for this is what made the hole obvious. The fix is to restrict callable filters to public methods physically declared on the concrete subclass - nothing inherited, nothing static:

protected function callableFilters(): array
{
    $reflection = new \ReflectionClass(static::class);
    $names = [];

    foreach ($reflection->getMethods(\ReflectionMethod::IS_PUBLIC) as $method) {
        // Only methods declared on the subclass, not inherited from Filter.
        if ($method->getDeclaringClass()->getName() === self::class) {
            continue;
        }

        if ($method->isStatic() || $method->isConstructor()) {
            continue;
        }

        $names[] = $method->getName();
    }

    return $names;
}

And the test that locks it down:

it('never invokes methods inherited from the base Filter via a request key', function () {
    // ?apply=... must not reach Filter::apply()
    // ?callableFilters=... must not reach the helper
    // Only declared subclass methods are callable.
});

This is the whole argument for the extraction-plus-review approach in one example. The pattern shipped to production years ago. Nobody exploited it. But it was only when I wrote the test for the extracted version that the gap became a red bar instead of a latent risk.

The frontend: making Inertia + Vue survive inside `vendor/`

Here's the problem that nearly sank the whole "core as a Composer package" idea, and the one I was most nervous about.

A normal Inertia app resolves its pages with something like import.meta.glob('./Pages/**/*.vue'). That glob is resolved by Vite at build time, relative to the host app. The moment your components live in vendor/dmitryisaenko/larafoundry/..., that resolution breaks. Frontend code is not as relocatable as PHP.

The answer turned out to be: don't try to make the package own the page-resolution mechanism at all. The package exports plain ES modules and Vue SFCs, plus one bootstrap function. Routing and page resolution stay the host's job - the core never assumes how those are wired.

import { createLaraFoundry } from '@dmitryisaenko/larafoundry';

setup({ el, App, props, plugin }) {
    const app = createApp({ render: () => h(App, props) }).use(plugin);
    createLaraFoundry(app, props.initialPage.props);
    app.mount(el);
}

createLaraFoundry installs i18n (wired from the same Inertia shared props the backend sends) and registers the shared components. Ziggy and the Inertia plugin stay with the host. The CSS theme is a @theme block the host imports straight from vendor/:

@import 'tailwindcss';
@import '../../vendor/dmitryisaenko/larafoundry/resources/css/theme.css';

This is the boring solution and that's exactly why it works. The package stopped trying to be the application and became a library the application uses. Risk closed.

The i18n bridge mirrors the legacy ergonomics so host code migrates without edits - {{ $t('key') }} in any template with no import - but inside the package itself there's a proper useT() composable instead of a global.

The review gate, and a bug it caught

Before tagging v0.1.0 I ran the code through /security-review and /code-review, plus a cross-check of the key decisions against the Laravel 13 docs. Security came back clean. Code review surfaced a real one, in the flash-message toast component.

The bug: auto-dismissing toasts kept their dismiss timer keyed by the message slot (disappear-info), not by the message itself. So if a new "disappearing" message arrived while the previous one's timer was still pending, the stale timer would fire and close the new message early. Classic identity bug.

Before:

// timer keyed by slot - a replacement message inherits the old timer
if (isDisappearType(m.type) && !timeouts[m.key]) {
    timeouts[m.key] = setTimeout(() => closeMessage(m.key), AUTO_DISMISS_MS);
}

After - the timer is tied to the message's content-derived id, and stale timers are cleared when the message list changes:

.map((m) => ({ ...m, id: `${m.slot}:${m.content}` }));

// a new message in the same slot can't inherit the previous one's timer
if (isDisappearType(m.type) && !timeouts[m.id]) {
    timeouts[m.id] = setTimeout(() => closeMessage(m), AUTO_DISMISS_MS);
}

Not a security issue. Just the kind of thing that produces a "sometimes the notification vanishes too fast" bug report you can never reproduce on demand. Better to kill it before the tag than to chase it in six months.

Testing

39 Pest tests in this release. They aren't decoration - two of them are the reason bugs above are former bugs:

it('never invokes methods inherited from the base Filter via a request key', function () {
    // mass-method-invocation guard
});

it('falls back to a safe locale when the configured default is invalid', function () {
    // a misconfigured default must not bypass the allow-list
});

it('normalises a simple paginator without total/last_page', function () {
    // paginators that lack lastPage()/total() must not throw
});

The locale and filter suites cover the cases that matter: every resolution source validated, unsupported codes rejected, base-class methods unreachable from input, empty filter values skipped, pagination payloads that don't explode on a SimplePaginator.

CI runs Pest plus Pint across PHP 8.2 / 8.3 / 8.4 on every push. The legacy repo had its test workflow disabled - renamed to *.yml_old. Turning that back on, green, is its own small satisfaction.

What I'd tell myself before starting

Extraction is a review disguised as a refactor. The value isn't moving the code; it's that moving it forces you to re-read every line with fresh, slightly-more-paranoid eyes. Budget for the bugs you'll find.
A library is not an application. The frontend risk evaporated the moment the package stopped trying to own page resolution and just exported modules.
Validate at the boundary, every source. The locale allow-list isn't one check - it's the same check applied to user preference, session, cookie, header, geo, and default. One of those is the one you forgot.
Tests are how a latent risk becomes a fixed bug. The mass-method-invocation gap was harmless in production right up until it wasn't. The Pest test is what changed its status from "probably fine" to "provably closed."

Honest scope

To be clear about what v0.1.0 is and isn't: this is the foundation layer. Auth, users, multi-tenancy, admin, billing - all later phases, none of it shipped yet. The package description names the full ambition; the tag delivers the primitives. I'd rather undersell a tag than have you composer require something that doesn't match the post.

If you're building a Laravel + Inertia + Vue SaaS and you've ever wondered what it takes to package the cross-cutting parts cleanly - this is the start of that, built in public, extracted from something real.

LaraFoundry is an open-source Laravel SaaS core, built in public and extracted from a production CRM/ERP.

GitHub: github.com/dmitryisaenko/larafoundry
Website: larafoundry.com

laravel #vue #php #opensource #larafoundry

Building a Multi-Currency Payment System with Promo Codes for a Laravel SaaS

Dmitry Isaenko — Mon, 25 May 2026 11:49:51 +0000

Payments. The module where "just integrate Stripe" turns into multi-currency revenue tracking, promo codes with 4-level validation chains, admin dashboards with configurable currency conversion, and a full audit trail on every discount ever applied.

I built Kohana.io - a production CRM/ERP for small businesses. The payment module handles real money from real customers across multiple currencies. Now I'm extracting it into LaraFoundry, an open-source SaaS framework for Laravel.

This post covers the full implementation.

Architecture Overview
Database Schema
Promo Code System
Admin Dashboard & Statistics
Promo Code CRUD
Filtering & Multi-Currency
Frontend: Payments & Promo Codes
Events & Notifications
Testing
Design Decisions

Architecture Overview

LaraFoundry's payment module has two main parts: payment tracking and promo code management. Both are admin-only - end users interact with payments through the subscription flow, while admins get the full picture.

Payment Tracking:

View all company payments with full metadata
Revenue statistics with multi-currency support
Advanced filtering: period, status, country, plan, promo code, email, company
Latest payment per company detection (subscription expiration)

Promo Code Management:

Full CRUD with 7 endpoints
Two discount types: percentage and fixed
Four constraint levels: active, not expired, usage limit, per-user limit
Personal codes tied to specific users
Toggle active status with one click

The module is built with:

2 controllers: PaymentController (read-only), PromoCodeController (full CRUD)
2 models: CompanyPayment, PromoCode
2 dedicated filter classes
4 form request classes
5 Vue pages + 2 components

Database Schema

company_payments

company_payments
├── id (PK)
├── company_id (FK → companies, cascade)
├── user_id (FK → users, cascade)
├── plan_id (string) - subscription plan
├── billing_period (enum: monthly, yearly)
├── amount (decimal 10,2) - original amount
├── currency (string 3, default 'USD')
├── discount_amount (decimal 10,2, default 0)
├── discount_reason (string, nullable) - 'free_month', 'promo_code', etc.
├── promo_code_id (FK → promo_codes, nullable, nullOnDelete)
├── payment_status (enum: pending, success, failed)
├── payment_method (string, nullable) - 'Stripe', 'LiqPay'
├── payment_response (json, nullable) - raw gateway response
├── paid_at (timestamp, nullable)
├── period_start (date)
├── period_end (date)
└── timestamps
Indexes: (company_id, payment_status), plan_id, user_id

The key design: every payment carries its own discount data. The discount_amount, discount_reason, and promo_code_id are stored on the payment itself - not calculated from the promo code at display time. This means even if a promo code is deleted, you still know exactly what discount was applied and why.

promo_codes

promo_codes
├── id (PK)
├── user_id (FK → users, nullable, nullOnDelete) - personal codes
├── code (string 50, unique) - uppercase alphanumeric
├── description (text, nullable) - internal notes
├── discount_type (enum: percentage, fixed)
├── discount_value (decimal 10,2)
├── max_uses (int, nullable) - global limit
├── used_count (int, default 0)
├── single_use_per_user (boolean, default true)
├── is_active (boolean, default true)
├── expires_at (timestamp, nullable)
└── timestamps
Indexes: code, (is_active, expires_at)

Promo Code System

The promo code model is the most logic-heavy part of the module. Four methods handle everything:

Validation Chain

// PromoCode model

public function isValid(): bool
{
    return $this->is_active
        && ($this->expires_at === null || $this->expires_at->isFuture());
}

public function canBeUsed(?int $userId): bool
{
    if (! $this->isValid()) {
        return false;
    }

    if ($this->isPersonal() && $this->user_id !== $userId) {
        return false;
    }

    if ($this->max_uses !== null && $this->used_count >= $this->max_uses) {
        return false;
    }

    if ($this->single_use_per_user && $userId) {
        $alreadyUsed = $this->payments()
            ->where('user_id', $userId)
            ->where('payment_status', 'success')
            ->exists();
        if ($alreadyUsed) {
            return false;
        }
    }

    return true;
}

The order matters: cheapest checks first (boolean flags), expensive checks last (database query for per-user usage).

Discount Calculation

public function calculateDiscount(float $amount): float
{
    return match ($this->discount_type) {
        'percentage' => round($amount * $this->discount_value / 100, 2),
        'fixed' => min($this->discount_value, $amount),
    };
}

Fixed discounts are capped at the payment amount - a $50 discount on a $30 plan gives $30 off, not negative $20.

Status Detection

public function getStatus(): string
{
    if (! $this->is_active) {
        return 'inactive';
    }
    if ($this->expires_at && $this->expires_at->isPast()) {
        return 'expired';
    }
    if ($this->max_uses !== null && $this->used_count >= $this->max_uses) {
        return 'exhausted';
    }
    return 'active';
}

Four possible statuses. Used for both backend filtering and frontend badge colors.

Personal Promo Codes

When user_id is set on a promo code, it becomes personal - only that specific user can use it. The admin creates these through a user search autocomplete that queries by email, first name, and last name.

Admin Dashboard & Statistics

The PaymentController@index returns a rich data structure:

Revenue Totals

// Simplified logic
$totals = CompanyPayment::query()
    ->selectRaw('currency, SUM(amount - discount_amount) as total')
    ->when($statusFilter, fn ($q) => $q->where('payment_status', $statusFilter))
    ->groupBy('currency')
    ->get();

// Convert to admin display currencies
foreach ($totals as $total) {
    $converted = CurrencyConverter::convert(
        $total->total,
        $total->currency,
        $adminDisplayCurrencies
    );
}

The totals respect all active filters - period, status, country, plan. When filtering by "failed" status, the totals switch to show failed payment amounts, visually highlighted so the admin doesn't confuse them with revenue.

Latest Payment Per Company

$latestPayments = CompanyPayment::query()
    ->select('company_id', DB::raw('MAX(paid_at) as max_paid_at'))
    ->where('payment_status', 'success')
    ->groupBy('company_id')
    ->get();

Each payment row in the table checks if it's the latest for its company. If yes, the admin sees the plan name with an expiration indicator - instantly showing which subscriptions are about to end.

AdminPaymentResource

The API resource formats each payment row:

return [
    'id' => $this->id,
    'paid_at' => $this->paid_at?->format('Y-m-d H:i:s'),
    'paid_at_date' => $this->paid_at?->format('d-m-Y'),
    'paid_at_time' => $this->paid_at?->format('H:i'),
    'user_email' => $this->user->email,
    'user_fullname' => $this->user->fullname,
    'company_name' => $this->company->name,
    'company_country' => $this->company->country,
    'plan_name' => $planConfig['name'] ?? $this->plan_id,
    'amount' => $this->amount,
    'currency' => $this->currency,
    'promo_code' => $this->promoCode?->code,
    'discount_amount' => $this->discount_amount,
    'total_amount' => $this->getTotalAmount(),
    'payment_status' => $this->payment_status,
    'payment_method' => $this->payment_method,
    'payment_response' => $this->payment_response,
    'is_latest_for_company' => $this->is_latest_for_company,
];

Promo Code CRUD

7 endpoints handle the full lifecycle:

Method	Endpoint	Action
GET	/admin/promo-codes	Index with filters
GET	/admin/promo-codes/create	Create form
POST	/admin/promo-codes	Store
GET	/admin/promo-codes/{id}/edit	Edit form
PUT	/admin/promo-codes/{id}	Update
PATCH	/admin/promo-codes/{id}/toggle	Toggle active
GET	/admin/promo-codes/search-users	User autocomplete

Validation Rules

Store (StorePromoCodeRequest):

code: required, max 50, regex /^[A-Z0-9_-]+$/, unique
discount_type: required, in: percentage, fixed
discount_value: required, numeric, min 0, max 100 (for percentage only)
max_uses: nullable, integer, min 1
single_use_per_user: boolean, default true
expires_at: nullable, date, must be after now
user_id: nullable, must exist in users table
is_active: boolean

Update (UpdatePromoCodeRequest):

code and discount_type are excluded - immutable after creation
expires_at can be set to past dates (to manually expire a code)
All other fields follow the same rules

The immutability of code and discount_type is intentional: existing payment records reference these values. Changing them would break the audit trail.

Toggle

A dedicated PATCH endpoint flips is_active. One click, one request. No form, no page navigation.

User Search

For personal promo codes, the admin types a name or email. The backend searches users by email, name, and lastname with a minimum of 2 characters, returning max 10 results. The Vue frontend shows these in an autocomplete dropdown.

Filtering & Multi-Currency

AdminPaymentsFilter

The filter class uses method-per-filter pattern:

public function period(string $value): Builder
{
    return match ($value) {
        'this_month' => $this->builder->whereBetween(
            DB::raw('COALESCE(paid_at, created_at)'),
            [now()->startOfMonth(), now()->endOfMonth()]
        ),
        'last_month' => $this->builder->whereBetween(
            DB::raw('COALESCE(paid_at, created_at)'),
            [now()->subMonth()->startOfMonth(), now()->subMonth()->endOfMonth()]
        ),
        'year' => $this->builder->whereYear(
            DB::raw('COALESCE(paid_at, created_at)'),
            now()->year
        ),
        'range' => $this->builder, // handled by date_from/date_to
        default => $this->builder,
    };
}

The COALESCE(paid_at, created_at) pattern ensures pending and failed payments (which have no paid_at) are still filterable by date.

Smart default: when filtering by promo_code_id, the period automatically switches to "all time" so you see every payment that used that code.

AdminPromoCodesFilter

Status filtering uses SQL conditions matching the model's getStatus() logic:

public function status(string $value): Builder
{
    return match ($value) {
        'active' => $this->builder
            ->where('is_active', true)
            ->where(fn ($q) => $q->whereNull('expires_at')->orWhere('expires_at', '>', now()))
            ->where(fn ($q) => $q->whereNull('max_uses')->orWhereColumn('used_count', '<', 'max_uses')),
        'inactive' => $this->builder->where('is_active', false),
        'expired' => $this->builder->where('expires_at', '<', now()),
        'exhausted' => $this->builder->whereNotNull('max_uses')->whereColumn('used_count', '>=', 'max_uses'),
    };
}

Frontend: Payments & Promo Codes

Payments Table (PaymentsTable.vue)

The main payments view includes:

Filter bar:

Period selector with 5 options (this month, last month, year, all time, custom range)
Date range pickers (enabled only when "Range" is selected)
Status, country, plan, promo code dropdowns
Email and company name text search
Clear all filters button

Revenue totals:

Displayed at the top, auto-updated with filter changes
Multiple currencies separated by " / "
Failed totals highlighted in a different color

Payment rows:

Date (date + time formatted separately)
User (email, full name)
Company (name, country)
Plan with expiration indicator for latest payment
Price breakdown: amount → promo code → discount → total
Status badge
Gateway info with JSON tooltip
Document links (Invoice, Receipt)

Responsive: Desktop shows a full table. Mobile switches to vertical card layout with the same data.

Promo Codes (PromoCodesTab.vue)

Tabbed alongside payments. Each row shows:

Code (bold)
Description
Formatted discount (e.g., "20%" or "$50")
Usage counter (e.g., "3 / 10" or "Unlimited")
Usage type badge ("1x per user" or "Multi-use")
Personal/general badge (with email for personal)
Expiration date or "Never expires"
Color-coded status badge: Active (green), Inactive (gray), Expired (yellow), Exhausted (red)
Actions: toggle active, edit, view payments (with count)

Create/Edit Promo Code

Create form includes a "Generate" button that produces a random 8-character uppercase alphanumeric code.

Edit form displays immutable fields (code, discount type, usage count) in a read-only info block at the top, with editable fields below.

Events & Notifications

Three components handle post-payment processing:

// CompanyPaymentProcessed event
class CompanyPaymentProcessed
{
    public function __construct(
        public CompanyPayment $payment
    ) {}
}

// Queued jobs
class NotifyOwnerAboutPaymentSuccess implements ShouldQueue { ... }
class NotifyOwnerAboutPaymentFailed implements ShouldQueue { ... }

When a payment is processed, the event fires. Listeners dispatch queued jobs that notify the company owner about success or failure. The jobs run asynchronously - the payment flow isn't blocked by email/notification delivery.

Testing

Three test files cover every scenario:

PaymentControllerTest (Feature)

test('admin can view payments with revenue statistics', function () {
    // create payments in different currencies with discounts
    // assert totals are calculated correctly: sum(amount - discount_amount)
    // assert currency conversion works
    // assert latest payment per company is detected
});

test('period filter uses COALESCE for pending payments', function () {
    // create pending payment (no paid_at)
    // filter by this month
    // assert pending payment appears (filtered by created_at)
});

test('promo code filter switches period to all time', function () {
    // create payments across different months
    // filter by promo_code_id
    // assert all payments with that code appear regardless of date
});

PromoCodeControllerTest (Feature)

test('code and discount_type cannot be changed after creation', function () {
    $promo = PromoCode::factory()->create([
        'code' => 'ORIGINAL',
        'discount_type' => 'percentage',
    ]);

    actingAs($admin)
        ->put(route('admin.promo-codes.update', $promo), [
            'code' => 'CHANGED', // should be ignored
            'discount_type' => 'fixed', // should be ignored
        ]);

    expect($promo->fresh())
        ->code->toBe('ORIGINAL')
        ->discount_type->toBe('percentage');
});

PromoCodeTest (Unit)

test('failed payments do not consume single use per user quota', function () {
    $promo = PromoCode::factory()->create(['single_use_per_user' => true]);

    CompanyPayment::factory()->create([
        'promo_code_id' => $promo->id,
        'user_id' => $user->id,
        'payment_status' => 'failed',
    ]);

    expect($promo->canBeUsed($user->id))->toBeTrue();
});

test('percentage discount calculates correctly', function () {
    $promo = PromoCode::factory()->create([
        'discount_type' => 'percentage',
        'discount_value' => 25,
    ]);

    expect($promo->calculateDiscount(100))->toBe(25.00);
    expect($promo->calculateDiscount(50))->toBe(12.50);
});

test('fixed discount is capped at payment amount', function () {
    $promo = PromoCode::factory()->create([
        'discount_type' => 'fixed',
        'discount_value' => 50,
    ]);

    expect($promo->calculateDiscount(30))->toBe(30.00);
});

Design Decisions

Discount on the payment, not computed from promo code. Each payment stores its own discount_amount and discount_reason. Even if the promo code is deleted or modified, the payment history stays accurate.
Failed payments don't consume promo codes. The single_use_per_user check only counts successful payments. Users aren't penalized for payment failures.
Immutable code and discount_type. Once created, you can't change the code string or switch between percentage/fixed. This prevents audit trail corruption.
COALESCE for date filtering. Pending and failed payments don't have paid_at, so we fall back to created_at. Every payment is always filterable.
Personal promo codes via user_id. Instead of a separate table or a complex system, a nullable FK on the promo code turns it into a personal discount. Simple, effective.
Payment response as JSON. The raw gateway response is stored on the payment. No separate table, no logging service. The admin sees it in a tooltip for debugging.
Latest payment detection per company. Calculated on the fly with a MAX(paid_at) subquery. No denormalization, no cron job. The admin always sees current data.
Toggle as a separate endpoint. Activating/deactivating a promo code is the most common admin action. A dedicated PATCH endpoint makes it a single click.

This is module 13 of the LaraFoundry series. Built with Laravel 12, Inertia.js v2, Vue 3, and Pest. The code runs in production at Kohana.io.

Follow along on LinkedIn and GitHub.

Building a Dual-Interface Support Ticket System for a Multi-Tenant Laravel SaaS

Dmitry Isaenko — Mon, 18 May 2026 10:18:09 +0000

Every SaaS needs a way for users to reach support. A form, a list, some statuses. Then the requirements pile up: admins need a different view, priorities need to affect sort order, categories need to be togglable on the fly, resolved tickets need to auto-disappear, and the user should never see a raw database ID in the URL.

I built Kohana.io - a production CRM/ERP for small businesses. The ticket module evolved into a dual-interface system where users and admins interact with the same data through completely different controllers, policies, and views.

Now I'm extracting it into LaraFoundry, an open-source SaaS framework for Laravel. This post covers the full implementation.

Architecture Overview
Database Schema
Status Workflow
Admin CRUD & Features
Smart Sorting & Filtering
User Side & Security
Category & Label Management
Frontend: Two Interfaces
Events & Audit Trail
Testing
Design Decisions

Architecture Overview

LaraFoundry's ticket system is built on coderflex/laravel-ticket with significant customization. The core idea: one data model, two interfaces.

User side - limited, secure:

Create tickets with title, message, priority, categories
View own tickets only (via UUID)
Reply to tickets (auto-updates status)
Old resolved tickets hidden after 7 days

Admin side - full control:

View all tickets with statistics and filters
Create tickets on behalf of users
Reply, close, reopen, change priority
Toggle categories and labels without editing
Grid/list display modes

The separation happens at every level: controllers, form requests, API resources, policies, Vue pages.

Database Schema

Tickets Table

Schema::create('tickets', function (Blueprint $table) {
    $table->id();
    $table->uuid('uuid')->unique();
    $table->foreignId('user_id')->constrained();
    $table->string('title');
    $table->text('message');
    $table->string('priority');    // LOW, STANDARD, HIGH
    $table->string('status');      // wait-customer, wait-moderator, resolved
    $table->boolean('is_resolved')->default(false);
    $table->boolean('is_locked')->default(false);
    $table->foreignId('assigned_to')->nullable()->constrained('users');
    $table->timestamps();
});

The uuid field exists alongside id. Users access tickets via UUID - /tickets/a8f3e2b1-.... The internal integer id is used for admin routes and relationships.

Categories & Labels

// Categories: general, billing, feature request, bug report
Schema::create('ticket_categories', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('slug')->unique();
    $table->boolean('is_visible')->default(true);
    $table->timestamps();
});

// Labels: quick, complex
Schema::create('ticket_labels', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('slug')->unique();
    $table->boolean('is_visible')->default(true);
    $table->timestamps();
});

// Pivot tables
Schema::create('ticket_category_assignments', ...);
Schema::create('ticket_label_assignments', ...);

Both use many-to-many relationships. Both are toggleable from the admin detail view.

Conversation Messages

Schema::create('ticket_message_assignments', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained();
    $table->foreignId('ticket_id')->constrained();
    $table->text('message');
    $table->timestamps();
});

Each message tracks who sent it. The API resource adds an is_agent flag so the frontend knows whether the message came from a user or admin.

Model

class Ticket extends BaseTicket
{
    use Filterable;

    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public static function getUnderReviewTicketsCont(): int
    {
        return static::query()
            ->whereColumn('created_at', 'updated_at')
            ->where('status', '!=', 'resolved')
            ->orWhere('status', 'wait-moderator')
            ->count();
    }

    public function scopeExcludeOldResolved($query, $days = 7): void
    {
        $query->where(function ($q) use ($days) {
            $q->where('status', '!=', 'resolved')
              ->orWhere('updated_at', '>=', now()->subDays($days));
        });
    }

    public function getExcludeOldResolvedAttribute(): bool
    {
        return $this->status === 'resolved'
            && $this->updated_at->lt(now()->subDays(7));
    }
}

The Filterable trait enables the admin filter system. excludeOldResolved scope keeps the user list clean. The getUnderReviewTicketsCont method counts tickets that haven't been touched yet.

Status Workflow

The status changes automatically based on who acts:

User creates ticket    → status = 'wait-moderator'
Admin replies          → status = 'wait-customer'
User replies           → status = 'wait-moderator'
Admin closes           → status = 'resolved'
User replies to resolved → status = 'wait-moderator' (auto-reopen)

In the user controller:

public function store(TicketStoreRequest $request): RedirectResponse
{
    $ticket = Ticket::create([
        'uuid' => Str::uuid(),
        'user_id' => auth()->id(),
        'title' => $request->title,
        'message' => $request->message,
        'priority' => $request->priority,
        'status' => 'wait-moderator',
    ]);

    $ticket->attachCategories($request->categories);

    event(new TicketCreate(auth()->user(), $ticket));

    return redirect()->route('tickets.index')
        ->with('success', __('Ticket created'));
}

And for replies:

public function storeMessage(StoreTicketMessageRequest $request, string $uuid): RedirectResponse
{
    $ticket = Ticket::where('uuid', $uuid)->firstOrFail();

    $ticket->messages()->create([
        'user_id' => auth()->id(),
        'message' => $request->message,
    ]);

    // Auto-reopen if resolved
    if ($ticket->status === 'resolved') {
        $ticket->update(['status' => 'wait-moderator']);
    }

    event(new TicketAnswerCreate(auth()->user(), $ticket, $request->message));

    return back();
}

The user never touches the status field. The system infers intent from the action.

Admin CRUD and Features

Routes (12 endpoints)

GET    /admin/tickets                          → index
GET    /admin/tickets/create/{user}            → create (for specific user)
POST   /admin/tickets                          → store
GET    /admin/tickets/{ticket}                 → show
GET    /admin/tickets/{ticket}/edit            → edit
PUT    /admin/tickets/{ticket}                 → update
POST   /admin/tickets/{ticket}/reply           → reply
PATCH  /admin/tickets/{ticket}/close           → close
PATCH  /admin/tickets/{ticket}/priority        → updatePriority
POST   /admin/tickets/{ticket}/category/toggle → toggleCategory
POST   /admin/tickets/{ticket}/label/toggle    → toggleLabel

Statistics Action

class GetTicketsStat
{
    public function __invoke(): object
    {
        return (object) [
            'total' => Ticket::count(),
            'open' => Ticket::where('status', '!=', 'resolved')->count(),
            'high_priority' => Ticket::where('priority', 'high')
                ->where('status', '!=', 'resolved')->count(),
            'standard_priority' => Ticket::where('priority', 'standard')
                ->where('status', '!=', 'resolved')->count(),
        ];
    }
}

The index page shows four stat cards at the top. Each card is clickable and links to a filtered view.

Admin Creates Tickets for Users

Admin can create a ticket on behalf of a user. The route takes {user} as a parameter. Status is set to wait-customer (admin-initiated).

public function store(TicketStoreRequest $request): RedirectResponse
{
    $ticket = Ticket::create([
        'uuid' => Str::uuid(),
        'user_id' => $request->userId,
        'title' => $request->title,
        'message' => $request->message,
        'priority' => $request->priority ?? 'standard',
        'status' => 'wait-customer',
    ]);

    if ($request->categories) {
        $ticket->attachCategories($request->categories);
    }
    if ($request->labels) {
        $ticket->attachLabels($request->labels);
    }

    return redirect()->route('admin.tickets.show', $ticket);
}

Smart Sorting and Filtering

AdminTicketsFilter

class AdminTicketsFilter extends QueryFilter
{
    public function show_tickets($value = null): void
    {
        match ($value) {
            'standard_priority' => $this->builder
                ->where('priority', 'standard')
                ->where('status', '!=', 'resolved'),
            'high_priority' => $this->builder
                ->where('priority', 'high')
                ->where('status', '!=', 'resolved'),
            default => null,
        };
    }

    public function search($value = null): void
    {
        if ($value) {
            $this->builder->where(function ($q) use ($value) {
                $q->where('title', 'like', "%{$value}%")
                  ->orWhere('message', 'like', "%{$value}%");
            });
        }
    }

    public function status($value = null): void
    {
        if ($value) {
            $this->builder->where('status', $value);
        }
    }

    public function apply($builder): Builder
    {
        parent::apply($builder);

        return $builder
            ->orderByRaw("CASE WHEN status = 'resolved' THEN 1 ELSE 0 END")
            ->orderByRaw("CASE WHEN created_at = updated_at THEN 0 ELSE 1 END")
            ->orderByRaw("CASE WHEN priority = 'high' THEN 0 ELSE 1 END")
            ->orderByRaw("CASE WHEN status = 'wait-moderator' THEN 0 ELSE 1 END")
            ->orderBy('updated_at', 'desc');
    }
}

Five sorting levels ensure the most urgent ticket is always at the top:

Unresolved tickets float up
Brand new tickets (created_at = updated_at, never responded to) surface next
High priority before standard
Waiting for moderator before waiting for customer
Most recently updated first

User Side and Security

TicketPolicy

class TicketPolicy
{
    public function viewAny(User $user): bool
    {
        return true; // All authenticated users
    }

    public function view(User $user, Ticket $ticket): bool
    {
        return $user->id === $ticket->user_id
            && !$ticket->is_resolved
            && !$ticket->exclude_old_resolved;
    }

    public function update(User $user, Ticket $ticket): bool
    {
        return $user->id === $ticket->user_id
            && !$ticket->is_resolved;
    }

    public function reply(User $user, Ticket $ticket): bool
    {
        return $user->id === $ticket->user_id;
    }

    public function delete(): bool { return false; }
    public function close(): bool { return false; }
}

Key decisions:

Users can only view their own tickets
Resolved tickets are not viewable (admin handles resolution)
Old resolved tickets (>7 days) are also blocked
Delete and close always return false for users
Reply is allowed even to resolved tickets (triggers auto-reopen)

UUID URLs

User-facing routes use {ticket:uuid} binding:

GET    /tickets/{ticket:uuid}            → show
POST   /tickets/{ticket:uuid}/messages   → storeMessage

Admin routes use {ticket} (integer ID). This means:

Users never see sequential IDs
Admins work with simple numeric references
Both resolve to the same Ticket model

Auto-Hide Old Resolved

// In user TicketController@index
$tickets = Ticket::query()
    ->where('user_id', auth()->id())
    ->excludeOldResolved()
    ->orderByRaw("FIELD(status, 'wait-moderator', 'wait-customer', 'resolved')")
    ->orderBy('updated_at', 'desc')
    ->get();

Resolved tickets silently disappear from the user's list after 7 days. No delete button. No archive feature. Just a scope.

Category and Label Management

Toggle Pattern

On the admin ticket detail page, all categories and labels are displayed as buttons. Active ones are highlighted. Click to toggle:

public function toggleCategory(Request $request, Ticket $ticket): RedirectResponse
{
    $category = Category::where('slug', $request->slug)->firstOrFail();

    if ($ticket->categories->contains($category->id)) {
        $ticket->categories()->detach($category->id);
    } else {
        $ticket->categories()->attach($category->id);
    }

    return back();
}

Same pattern for labels. One POST request per toggle. No form submission. No page reload via Inertia's preserveScroll.

Available Categories & Labels

Configured in config/laravel_ticket.php:

Categories	Labels
general	quick
billing	complex
feature request
bug report

All translated via Laravel's localization system.

Frontend: Two Interfaces

Admin Pages

IndexTickets.vue:

4 stat cards (open, high priority, standard priority, total)
Each card links to filtered view
Filter form: search, status, priority
Grid/list view toggle
TicketCard (grid) and TicketListItem (list) components

TicketCard component:

Title (linked to show), user name, creation date
Status and priority badges with color coding
Message preview (150 chars truncated)
Category and label tags
Message count with icon
Close button (if not resolved)
Search text highlighting

TicketListItem component:

More detailed metadata: user icon, creation date, message count, assigned user
Full categories/labels with calculated contrast colors
Close/reopen buttons based on status
Priority indicator dot

ShowTicket.vue:

Dynamic category/label toggle buttons (all available, active highlighted)
Priority selector buttons
Full conversation via MessageList component
Admin reply form

EditTicket.vue:

Pre-filled form: title, message, priority, status, categories, labels
Status selector with buttons for each state
Category/label checkboxes

User Pages

IndexTickets.vue:

Own tickets list: priority badge, categories, title, status, dates
Empty state when no tickets

CreateTicket.vue:

Title, message (textarea), priority (select), categories (checkboxes)
Form validation with error messages

ShowTicket.vue:

Status/priority badges, creation date, title, message (HTML rendered)
Categories as tags
MessageList component (shared with admin)
Reply textarea

Shared Component

MessageList is the only component shared between user and admin show pages. It renders the conversation thread with sender info, message content, timestamps, and an is_agent flag for visual distinction.

Events and Audit Trail

Two events fire during ticket interactions:

TicketCreate

class TicketCreate
{
    public function __construct(
        public User $user,
        public Ticket $ticket
    ) {}
}

Logged data: ticket_id, title, message, priority, categories. Fires when a user creates a new ticket.

TicketAnswerCreate

class TicketAnswerCreate
{
    public function __construct(
        public User $user,
        public Ticket $ticket,
        public string $message
    ) {}
}

Logged data: ticket_id, title, answer_message, priority, categories. Fires when a message is added to a ticket.

Both events integrate with LaraFoundry's logging system (covered in module 4) for a complete audit trail.

Testing

Feature Tests (User)

test('user can view own tickets list', function () {
    $user = User::factory()->create();
    Ticket::factory()->create(['user_id' => $user->id]);

    actingAs($user)
        ->get(route('tickets.index'))
        ->assertOk();
});

test('user cannot view other users tickets', function () {
    $user = User::factory()->create();
    $other = User::factory()->create();
    $ticket = Ticket::factory()->create(['user_id' => $other->id]);

    actingAs($user)
        ->get(route('tickets.show', $ticket->uuid))
        ->assertForbidden();
});

test('user can create ticket with valid data', function () {
    $user = User::factory()->create();

    actingAs($user)->post(route('tickets.store'), [
        'title' => 'Need help',
        'message' => 'I have an issue with billing',
        'priority' => 'standard',
        'categories' => ['billing'],
    ])->assertRedirect();

    expect(Ticket::first())
        ->status->toBe('wait-moderator')
        ->user_id->toBe($user->id);
});

test('message reply reopens resolved ticket', function () {
    $ticket = Ticket::factory()->create([
        'status' => 'resolved',
        'user_id' => $user->id,
    ]);

    actingAs($user)->post(
        route('tickets.messages.store', $ticket->uuid),
        ['message' => 'I still need help with this']
    );

    expect($ticket->fresh()->status)->toBe('wait-moderator');
});

Feature Tests (Admin)

test('admin can close ticket', function () {
    $ticket = Ticket::factory()->create(['status' => 'wait-moderator']);

    actingAs($admin)
        ->patch(route('admin.tickets.close', $ticket))
        ->assertRedirect();

    expect($ticket->fresh()->status)->toBe('resolved');
});

test('admin can toggle category', function () {
    $ticket = Ticket::factory()->create();
    $category = TicketCategory::first();

    actingAs($admin)->post(
        route('admin.tickets.category.toggle', $ticket),
        ['slug' => $category->slug]
    );

    expect($ticket->categories)->toHaveCount(1);
});

test('admin can filter tickets by priority', function () {
    Ticket::factory()->create(['priority' => 'high']);
    Ticket::factory()->create(['priority' => 'standard']);

    actingAs($admin)
        ->get(route('admin.tickets.index', ['show_tickets' => 'high_priority']))
        ->assertOk();
});

Unit Tests

test('ticket belongs to user', function () {
    $ticket = Ticket::factory()->create();
    expect($ticket->user)->toBeInstanceOf(User::class);
});

test('exclude old resolved scope works', function () {
    Ticket::factory()->create([
        'status' => 'resolved',
        'updated_at' => now()->subDays(10),
    ]);
    Ticket::factory()->create(['status' => 'wait-moderator']);

    expect(Ticket::excludeOldResolved()->count())->toBe(1);
});

Policy Tests

test('user can view own non-resolved ticket', function () {
    expect($user->can('view', $ownTicket))->toBeTrue();
});

test('user cannot view old resolved ticket', function () {
    expect($user->can('view', $oldResolvedTicket))->toBeFalse();
});

test('user cannot delete tickets', function () {
    expect($user->can('delete', $ticket))->toBeFalse();
});

Real HTTP requests, real database, no mocking the ticket system.

Design Decisions

Why coderflex/laravel-ticket as a Base?

Starting from a package gives you the basic table structure and relationships. Then you extend: add uuid, customize the model, add filters, add events. It's faster than building from scratch and the package handles the boilerplate migrations and pivot tables.

Why Separate Controllers for Users and Admins?

Mixing user and admin logic in one controller leads to messy authorization checks everywhere. Separate controllers mean clean, focused methods. The user controller has 4 methods. The admin controller has 11. Different validation, different resources, different concerns.

Why UUID for Users but ID for Admins?

Users shouldn't enumerate tickets. UUID prevents /tickets/1, /tickets/2, /tickets/3 guessing. Admins are trusted - integer IDs are simpler for internal use and URL readability in the admin panel.

Why Auto-Hide Instead of Archive?

An archive feature adds UI complexity: archive button, archived tickets list, unarchive action. The 7-day auto-hide achieves the same result with zero UI. Resolved tickets disappear naturally. The data stays in the database. If needed, it's queryable.

Why Toggle Instead of Edit for Categories/Labels?

Editing a ticket to change its category requires: load edit form → modify → submit → redirect. Toggling requires: one click → one POST → done. Admins manage dozens of tickets daily. Every saved click matters.

Why Five-Level Sorting?

A single "sort by date" puts old high-priority tickets below new low-priority ones. A single "sort by priority" puts old tickets at the top forever. Multi-level sorting ensures the admin always sees the most actionable ticket first, without manual sorting.

This is part of the "LaraFoundry series" - documenting the extraction of a production CRM/ERP into an open-source Laravel SaaS framework.

Previous: Notifications Module
LaraFoundry: larafoundry.com

Building a Dual Notification System for a Multi-Tenant Laravel SaaS

Dmitry Isaenko — Mon, 11 May 2026 08:44:35 +0000

Your SaaS needs to talk to users. Not just email - in-app notifications that persist, track reads, support multiple languages, and let admins target specific user segments.

I built Kohana.io - a production CRM/ERP for small businesses. The notification module evolved into a dual-architecture system: admin broadcasts and automated system notifications sharing the same table, the same UI, and the same read-tracking mechanism.

Now I'm extracting it into LaraFoundry, an open-source SaaS framework for Laravel. This post covers the full implementation.

Dual Architecture
Database Schema
Multilingual Content
Recipient Segmentation
Admin CRUD & Workflow
System Notifications
Delivery & Read Statistics
Frontend UX
Testing
Design Decisions

Dual Architecture

LaraFoundry has two notification types that coexist in one system:

Admin notifications - created manually in the admin panel:

Multilingual titles and bodies stored as JSON in the database
Recipient filters: country, sex, age range, registration date, activity level, verification status
Draft → Sent workflow with visibility scheduling
Delivery and read statistics

System notifications - created programmatically by queued jobs:

Laravel translation keys with dynamic parameters
Auto-sent when events occur (company created, invitation accepted, payment failed)
Auto-expire after 30 days
Rich metadata for UI actions

Both types appear in the same user notification panel. The user doesn't know or care where a notification came from.

Database Schema

Notifications Table

Schema::create('notifications', function (Blueprint $table) {
    $table->id();
    $table->string('code')->index();
    $table->enum('notification_type', ['admin', 'system']);
    $table->enum('status', ['draft', 'sent']);

    // system notifications - translation keys
    $table->string('title_key')->nullable();
    $table->string('body_key')->nullable();
    $table->json('params')->nullable();

    // admin notifications - stored translations
    $table->json('title_translations')->nullable();
    $table->json('body_translations')->nullable();

    // admin notifications - targeting
    $table->json('recipient_filters')->nullable();
    $table->json('data')->nullable();

    // scheduling
    $table->timestamp('visible_from')->nullable();
    $table->timestamp('visible_until')->nullable();
    $table->timestamps();
});

One table with two sets of nullable columns. The notification_type enum determines which set is used. This is simpler than two tables because the user-facing side doesn't care about the source.

Notification-User Pivot

Schema::create('notification_user', function (Blueprint $table) {
    $table->id();
    $table->foreignId('notification_id')->constrained()->cascadeOnDelete();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->timestamp('read_at')->nullable()->index();
    $table->timestamps();
    $table->unique(['notification_id', 'user_id']);
});

read_at is nullable. Null = unread. Timestamp = read (and you know exactly when). The unique constraint prevents duplicate attachments.

Model

class Notification extends Model
{
    use HasFactory;

    protected function casts(): array
    {
        return [
            'params' => 'array',
            'recipient_filters' => 'array',
            'title_translations' => 'array',
            'body_translations' => 'array',
            'data' => 'array',
            'visible_from' => 'datetime',
            'visible_until' => 'datetime',
        ];
    }

    public function users(): BelongsToMany
    {
        return $this->belongsToMany(User::class)
            ->withPivot('read_at')
            ->withTimestamps();
    }

    // Scopes
    public function scopeDraft($q) { $q->where('status', 'draft'); }
    public function scopeSent($q) { $q->where('status', 'sent'); }
    public function scopeAdmin($q) { $q->where('notification_type', 'admin'); }
    public function scopeSystem($q) { $q->where('notification_type', 'system'); }

    // Helpers
    public function isDraft(): bool { return $this->status === 'draft'; }
    public function isSent(): bool { return $this->status === 'sent'; }
    public function isAdmin(): bool { return $this->notification_type === 'admin'; }
    public function isSystem(): bool { return $this->notification_type === 'system'; }
}

Multilingual Content

The same getLocalizedTitle() method handles both notification types:

public function getLocalizedTitle(string $locale = 'en'): string
{
    if ($this->isSystem()) {
        return __($this->title_key, $this->params ?? [], $locale);
    }

    return $this->title_translations[$locale]
        ?? $this->title_translations['en']
        ?? '';
}

System notifications use Laravel's __() helper. Translation files + parameters. Standard.

Admin notifications use JSON lookup with fallback: requested locale → English → empty string.

Auto-Translate in Admin Panel

The admin creation form has a language accordion. English is required. Other languages are optional. Each language tab has a "Translate" button:

POST /admin/translate
{
    "source_locale": "en",
    "text": "System maintenance on Friday",
    "target_locales": ["uk", "de"]
}

One click fills all empty language fields. The admin reviews and adjusts. Only empty fields are populated - already-filled translations are preserved.

The body field supports up to 10,000 characters per language.

Recipient Segmentation

When creating an admin notification, the admin configures who receives it:

Filter	Options
Country	From available_countries config
Sex	Male / Female
Age range	16 - 100
Registration date	All / Today / This month / This year
Recent activity	All / More active / Less active
Email verified	All / Verified / Unverified
Phone verified	All / Verified / Unverified

The form shows a live user count that updates as filters change:

Recipients matching filters: 847 users

Debounced at 500ms. The submit button is disabled if count is 0.

Filter Implementation

Filters are stored as JSON in recipient_filters and applied via AdminUsersFilter:

public function send(
    Notification $notification,
    AdminUsersFilter $filter
): RedirectResponse
{
    DB::transaction(function () use ($notification, $filter) {
        $users = User::query()
            ->filter($filter)
            ->where('email', '!=', config('own.admin_email'))
            ->pluck('id');

        $notification->users()->attach(
            $users->mapWithKeys(fn($id) => [
                $id => ['created_at' => now(), 'updated_at' => now()]
            ])
        );

        $notification->update(['status' => 'sent']);
    });
}

The HasUserFilterRules trait provides shared validation rules, reusable across any feature that needs user targeting.

Admin CRUD and Workflow

Routes

GET    /admin/notifications               → index
GET    /admin/notifications/create         → create
POST   /admin/notifications                → store (draft)
GET    /admin/notifications/{id}/edit      → edit
PUT    /admin/notifications/{id}           → update
DELETE /admin/notifications/{id}           → destroy
POST   /admin/notifications/{id}/send      → send

Workflow

Create - Admin fills form, notification saved as draft
Edit - Modify translations, filters, scheduling while in draft
Send - Apply filters, attach matching users, set status to 'sent'
Resend - Re-run filters on already-sent notification, attach new matches
Delete - Detach all users, delete notification (transaction-wrapped)

The form request validates everything:

class AdminNotificationStoreRequest extends FormRequest
{
    use HasUserFilterRules;

    public function rules(): array
    {
        $rules = [
            'code' => ['required', 'string', Rule::in(
                array_keys(config('own.notification_types'))
            )],
            'title_translations.en' => 'required|string|max:255',
            'visible_from' => 'nullable|date',
            'visible_until' => 'nullable|date',
        ];

        foreach (config('app.available_languages') as $locale => $name) {
            if ($locale !== 'en') {
                $rules["title_translations.{$locale}"] = 'nullable|string|max:255';
            }
            $rules["body_translations.{$locale}"] = 'nullable|string|max:10000';
        }

        return array_merge($rules, $this->userFilterRules());
    }
}

English title required. Everything else optional. Filter rules mixed in from the trait.

System Notifications

System notifications are created by queued jobs when events happen:

class NotifyEmployeeAboutRejection implements ShouldQueue
{
    public function handle(): void
    {
        $notification = Notification::create([
            'code' => 'invitation_rejected_employee_' . $this->id,
            'notification_type' => 'system',
            'status' => 'sent',
            'title_key' => 'Invitation Rejected',
            'body_key' => 'You declined the invitation to join :company.',
            'params' => ['company' => $this->company->name],
            'visible_from' => now(),
            'visible_until' => now()->addDays(
                config('own.system_notification_lifetime_days')
            ),
        ]);

        $notification->users()->attach($this->user->id);

        $this->user->notify(
            new InvitationRejectedEmployeeNotification(...)
        );
    }
}

Pattern: create → attach → optionally email. Unique code prevents duplicates.

System Notification Triggers

Event	Notification
Company created	Owner gets in-app + email
Company deleted	Owner gets in-app + email
Invitation sent	Invitee gets email (+ in-app if registered)
Invitation accepted	Owner notified
Invitation rejected	Both sides notified differently
Employee removed	Employee notified
Payment success	Owner notified
Payment failed	Owner notified
Admin login attempt	Admin gets email + Telegram

Each notification auto-expires after 30 days (system_notification_lifetime_days config). Old notifications disappear naturally without cleanup jobs.

Delivery and Read Statistics

The admin panel shows per-notification statistics:

| Type    | Title                      | Received | Read         | Status    |
|---------|----------------------------|----------|--------------|-----------|
| info    | System maintenance Friday  | 847      | 312 (36.8%)  | Active    |
| warning | New pricing March 1        | 1,204    | 891 (74.0%)  | Scheduled |
| info    | Welcome to v2.0            | 2,100    | 2,034 (96.9%)| Expired   |

All computed from the pivot table:

// AdminNotificationResource
'total_recipients' => $this->users->count(),
'read_count' => $this->users->whereNotNull('pivot.read_at')->count(),
'read_percentage' => $total > 0
    ? round(($read / $total) * 100, 1)
    : 0,

Visibility Status

Computed from timestamps, displayed as a colored badge:

'visibility_status' => match(true) {
    $this->visible_until?->isPast() => 'expired',
    $this->visible_from?->isFuture() => 'scheduled',
    default => 'active',
},

Drafts show "Not sent yet" instead of statistics. The can_send flag controls whether the send button appears.

Frontend UX

User Notification Panel

The notification page shows both admin and system notifications in a unified list:

Header: "Notifications (3 unread)" + "Mark all as read" button
List: Paginated (25 per page), each item expandable
Item: Type badge, title, timestamp, read indicator
Expand: Body text appears, auto-marks as read

// NotificationItem.vue
const toggle = () => {
    expanded.value = !expanded.value;
    if (expanded.value && !notification.read_at) {
        markAsRead(notification.id);
    }
};

Real-Time Unread Count

Polling every 30 seconds updates the notification bell in the header:

GET /notifications/unread → { unread: true, count: 4 }

Synced to a global store. No WebSockets needed - polling is simple and reliable for non-chat notifications.

Bulk Operations

"Mark all as read" uses a direct DB update:

$count = $request->user()
    ->notifications()
    ->wherePivot('read_at', null)
    ->update(['notification_user.read_at' => now()]);

One query regardless of notification count.

User API Endpoints

GET  /notifications              → paginated list
GET  /notifications/unread       → unread count
GET  /notifications/unread-recent → last 5 unread (for dropdown)
GET  /notifications/recent       → last 5 all (for widget)
POST /notifications/{id}/read    → mark single
POST /notifications/mark-all-read → mark all

Admin Creation Form

Three sections:

Main info: notification type (info/warning), visible_from, visible_until
Translations: language accordion with auto-translate button
Recipients: filter form with live user count

The form is disabled for sent notifications except resend action.

Testing

Notifications get tested end-to-end with Pest:

CRUD

test('admin can create a draft notification', function () {
    actingAs($admin)
        ->post(route('admin.notifications.store'), [
            'code' => 'info',
            'title_translations' => ['en' => 'Test notification'],
            'body_translations' => ['en' => 'Test body'],
            // ... filter defaults
        ])
        ->assertRedirect(route('admin.notifications.index'));

    expect(Notification::first()->status)->toBe('draft');
});

Segmentation

test('only matching users receive notification', function () {
    User::factory()->create(['country' => 'DE']);
    User::factory()->create(['country' => 'DE']);
    User::factory()->create(['country' => 'US']);

    $notification = Notification::factory()->create([
        'recipient_filters' => ['country' => 'DE'],
    ]);

    actingAs($admin)->post(route('admin.notifications.send', $notification));

    expect($notification->users)->toHaveCount(2);
});

Read Tracking

test('expanding notification marks it as read', function () {
    actingAs($user)->post(route('notifications.read', $notification));

    expect($user->notifications()->first()->pivot->read_at)
        ->not->toBeNull();
});

System Notifications

test('rejection job creates notification and sends email', function () {
    NotifyEmployeeAboutRejection::dispatch($user, $company);

    expect(Notification::system()->count())->toBe(1);
    Mail::assertSent(InvitationRejectedEmployeeNotification::class);
});

Real requests. Real database. No mocking of notification creation.

Design Decisions

Why One Table Instead of Two?

Admin and system notifications have different creation flows but identical consumption. The user sees a list of notifications - they don't care about the source. One table means one query, one resource, one component. The notification_type enum + nullable columns is simpler than polymorphism for this use case.

Why JSON Translations Instead of a Translations Table?

Admin notifications are write-once. Draft, translate, send, done. No one edits translations after sending. A flat JSON column avoids the complexity of a polymorphic translations table for something that's essentially immutable after creation.

Why Polling Instead of WebSockets?

Notifications aren't chat messages. A 30-second delay is acceptable. Polling is simpler to implement, deploy, and debug. No WebSocket server to maintain. No connection management. If the latency requirements change, switching to WebSockets is straightforward - the API endpoints stay the same.

Why Auto-Mark-as-Read on Expand?

Forcing users to click a separate "mark as read" button adds friction without adding value. If you expanded a notification to read it, you read it. The timestamp records when, which is useful for analytics.

Why Exclude Admin From Recipients?

The admin who creates and sends notifications doesn't need to receive their own broadcasts. Excluding config('own.admin_email') prevents self-notification without adding a "skip creator" flag to the schema.

What's Next

This module is part of LaraFoundry - an open-source SaaS framework for Laravel, extracted from a production CRM/ERP.

GitHub: github.com/dmitryisaenko/larafoundry
Previous modules: Registration, Authentication, Multi-Tenancy, Logging, Multilanguage, Navigation, Vue Frontend, Traits & Middlewares, Admin Users, Admin Companies
Follow for the next module deep-dive.
LaraFoundry: larafoundry.com

Building an Admin Company Management System for a Multi-Tenant Laravel SaaS

Dmitry Isaenko — Mon, 04 May 2026 13:08:41 +0000

Companies sign up. They pick a plan. They start paying. Some stop paying. Some owners get banned. Some trials expire and nobody notices.

I built Kohana.io - a production CRM/ERP for small businesses. The admin companies module became the financial nerve center of the whole system. Now I'm extracting it into LaraFoundry, an open-source SaaS framework for Laravel.

This post covers the full implementation: company dashboard, subscription engine, blocking system, expiry notifications, payment model, frontend blocked pages, and testing.

Company Dashboard
Subscription Status Engine
Blocking System
Subscription Expiry Notifications
Frontend Blocked Pages
Payment Model
Admin Filtering & Search
Testing
Design Decisions

Company Dashboard

What the Admin Sees

Every company row in the admin panel shows a complete operational picture:

Company info - name, logo, country, creation date
Owner info - full name, email, phone, age, companies count, last activity, blocked status badge
Subscription - plan name, status badge with color, billing period, expiry date
Finances - total payments sum, last payment date and amount, full payment history on hover
Activity - employee count (excluding soft-deleted), last activity across all users

The Query

public function index(AdminCompaniesFilterRequest $request, AdminCompaniesFilter $filter): Response
{
    $companies = Company::query()
        ->with(['createdBy', 'users', 'payments'])
        ->withCount(['users' => fn($q) => $q->wherePivot('is_deleted', false)])
        ->addSelect([
            'total_payments' => CompanyPayment::selectRaw('SUM(amount)')
                ->whereColumn('company_id', 'companies.id')
                ->where('payment_status', 'success'),
            'last_payment_date' => CompanyPayment::select('paid_at')
                ->whereColumn('company_id', 'companies.id')
                ->where('payment_status', 'success')
                ->latest('paid_at')
                ->limit(1),
        ])
        ->filter($filter)
        ->paginate(config('own.admin_companies_per_page'));

    return Inertia::render('admin/companies/IndexCompanies', [
        'companies' => AdminCompanyResource::collection($companies),
        'pagination' => /* pagination data */,
        'filters' => $request->validated(),
        'available_plans' => config('own.company_plans'),
        'available_countries' => config('app.available_countries'),
    ]);
}

Key decisions:

Subqueries for aggregates - total payments and last payment calculated in SQL, not PHP. No N+1.
Filter injection - AdminCompaniesFilter applied via scope. Controller doesn't know filtering internals.
Config-driven everything - pagination, plans, countries all from config files.
AdminCompanyResource - single transformation layer. The Vue frontend gets consistent, pre-formatted data.

AdminCompanyResource

The resource does heavy lifting:

public function toArray($request): array
{
    $owner = $this->createdBy;

    return [
        // Company
        'id' => $this->id,
        'uuid' => $this->uuid,
        'name' => $this->name,
        'country_name' => $this->getCountryName(),

        // Owner
        'owner_fullname' => $owner?->getFullname(),
        'owner_email' => $owner?->email,
        'owner_is_blocked' => $owner?->user_blocked_at !== null,
        'owner_last_activity' => $this->formatLastActivity($owner?->last_activity_at),

        // Subscription
        'plan_name' => $this->getPlanName(),
        'subscription_status' => $this->getSubscriptionStatus(),
        'subscription_status_text' => $this->getSubscriptionStatusText(),
        'subscription_ends_at_formatted' => $this->subscription_ends_at?->format('d-m-Y'),

        // Finances
        'total_payments_sum' => $this->total_payments,
        'last_payment_date' => $this->last_payment_date,

        // Activity
        'employees_count' => $this->users_count,
    ];
}

Country names translated from config. Plan names resolved from config. Subscription status calculated with priority logic. Last activity formatted as "Recently", "Long time ago", or exact date.

Subscription Status Engine

A company can be in 5 states. The logic has a specific priority order:

private function getSubscriptionStatus(): string
{
    $company = $this->resource;

    // Priority 1: Never started
    if ($company->isInSetup()) {
        return 'never_activated';
    }

    // Priority 2: Trial is running
    if ($company->isOnTrial()) {
        return 'trial';
    }

    // Priority 3: Subscription ended
    if (!$company->subscription_ends_at || $company->subscription_ends_at->isPast()) {
        return 'expired';
    }

    // Priority 4: Expiring soon (within 7 days)
    if ($company->subscription_ends_at->diffInDays(now()) <= 7) {
        return 'expiring';
    }

    // Priority 5: All good
    return 'active';
}

Each status gets a visual indicator in the admin panel:

active - company is paying
expiring - less than 7 days left (yellow flag - retention opportunity)
expired - subscription ended, access restricted
trial - free trial period running
never_activated - signed up, never picked a plan

Company Model Access Methods

public function isOnTrial(): bool
{
    return $this->trial_ends_at && $this->trial_ends_at->isFuture();
}

public function hasActiveSubscription(): bool
{
    return $this->subscription_ends_at && $this->subscription_ends_at->isFuture();
}

public function hasAccess(): bool
{
    return $this->isOnTrial() || $this->hasActiveSubscription();
}

public function isInSetup(): bool
{
    return !$this->plan_id && !$this->trial_ends_at && !$this->subscription_ends_at;
}

hasAccess() checks both trial and subscription. A company on trial with an expired subscription still has access. Trial takes priority.

Blocking System

A company can be blocked for three distinct reasons. Each one triggers a different user experience.

GetBlockStatusAction

The single source of truth for access status:

class GetBlockStatusAction
{
    public function __invoke(): array
    {
        $user = auth()->user();
        $company = $user?->getActiveCompany();

        $status = [
            'user_blocked' => false,
            'user_ban_reason' => null,
            'company_blocked' => false,
            'company_block_reason' => '',
            'subscription_expires_soon' => false,
            'days_until_expiry' => null,
        ];

        // Level 1: User personally banned
        if ($user->user_blocked_at !== null) {
            $status['user_blocked'] = true;
            $status['user_ban_reason'] = /* from config */;
            return $status;
        }

        // Level 2: Company owner banned
        $owner = $company->createdBy;
        if ($owner->user_blocked_at !== null) {
            $status['company_blocked'] = true;
            $status['company_block_reason'] = 'owner_banned';
            return $status;
        }

        // Level 3: Payment issue
        if (!$company->hasAccess()) {
            $status['company_blocked'] = true;
            $status['company_block_reason'] = $hadSubscriptionBefore
                ? 'payment_expired'
                : 'first_payment_required';
            return $status;
        }

        // Warning: subscription expiring within 10 days
        if ($company->hasActiveSubscription()) {
            $daysLeft = now()->diffInDays($company->subscription_ends_at, false);
            if ($daysLeft <= 10 && $daysLeft > 0) {
                $status['subscription_expires_soon'] = true;
                $status['days_until_expiry'] = $daysLeft;
            }
        }

        return $status;
    }
}

Three blocking scenarios with clear priority:

1. Owner banned - Admin blocked the owner. Every employee in the company is locked out. They see: "Your company owner's account has been restricted." Not their fault - different message.

2. First payment required - Company finished trial or skipped it. Never made a payment. Owner sees billing link. Non-owner sees "contact administrator".

3. Payment expired - Had a subscription, it ended. Same owner/employee split as above.

CheckAccessMiddleware

Enforces blocking at the request level:

class CheckAccessMiddleware
{
    public function handle($request, Closure $next)
    {
        $user = $request->user();

        // Priority 1: User personally banned
        if ($user->user_blocked_at !== null) {
            return $this->handleBannedUser($request);
        }

        // Priority 2: Company access check
        if ($user->getActiveCompany()) {
            $check = $this->checkCompanyAccess($user);
            if (!$check['allowed']) {
                return $this->handlePaymentRequired($request, $check);
            }
        }

        return $next($request);
    }
}

Banned user whitelist - even banned users can access:

Support tickets (to appeal)
Notifications
Tutorials
Language switching
Logout
Leave impersonation
Switch companies

That last one is important. If the owner is banned on Company A but has Company B with active subscription - they switch to B and keep working. The block is per-company, not per-user.

Gates

// UserBlockedGates
Gate::define('view-company-payment-blocked-page', function (User $user, string $type) {
    return match ($type) {
        'owner_banned' => $user->getActiveCompany()?->createdBy?->user_blocked_at !== null,
        'payment_required', 'payment_required_non_owner'
            => !$user->getActiveCompany()?->hasAccess(),
        default => false,
    };
});

Direct URL protection. Users can't access the blocked page unless they're actually blocked.

Subscription Expiry Notifications

The system warns users before blocking them.

Scheduled Command

class CheckExpiringSubscriptions extends Command
{
    protected $signature = 'subscriptions:check-expiring';

    public function handle(): void
    {
        $this->checkAndNotify(daysBeforeExpiry: 10);
        $this->checkAndNotify(daysBeforeExpiry: 3);
    }

    private function checkAndNotify(int $daysBeforeExpiry): void
    {
        $targetDate = now()->addDays($daysBeforeExpiry)->toDateString();

        $companies = Company::query()
            ->whereDate('subscription_ends_at', $targetDate)
            ->get();

        foreach ($companies as $company) {
            $owner = $company->createdBy;

            // Skip if no owner or owner is banned
            if (!$owner || $owner->user_blocked_at !== null) {
                continue;
            }

            // Unique code prevents duplicates
            $code = "subscription_expiring_{$daysBeforeExpiry}d_{$company->id}";

            if (Notification::where('code', $code)->exists()) {
                continue;
            }

            // Create notification with all locale translations
            $notification = Notification::create([
                'code' => $code,
                'type' => 'subscription_expiring',
                // ... translations, data with company name, days, expiry date, payment URL
            ]);

            $notification->users()->attach($owner->id);
        }
    }
}

10 days = friendly reminder. "Hey, renew when you can."
3 days = urgent. "You're about to lose access."

Unique notification codes (subscription_expiring_10d_42) prevent spam. Cron runs daily, notifications are created once.

Banned owners are skipped - no point notifying someone who can't access the system anyway.

Frontend Blocked Pages

CompanyBlocked.vue

One component handles all three blocking scenarios:

<script setup>
const props = defineProps({
    blockType: String,     // 'user_banned' | 'payment_required' | 'payment_required_non_owner'
    isOwner: Boolean,
    companyName: String,
});

const config = computed(() => ({
    user_banned: {
        icon: 'ban',
        title: 'Account blocked',
        description: 'All company operations are unavailable.',
        action: { label: 'Contact support', href: route('tickets.create') },
    },
    payment_required: {
        icon: 'credit-card',
        title: 'Subscription expired',
        description: 'Renew your subscription to continue.',
        action: { label: 'Go to billing', href: route('company.billing') },
    },
    payment_required_non_owner: {
        icon: 'credit-card',
        title: 'Subscription expired',
        description: 'Please contact your company administrator.',
        action: { label: 'Logout', href: route('logout') },
    },
}[props.blockType]));
</script>

Different icons, titles, descriptions, and calls-to-action. The owner gets a billing link. The employee gets "contact your admin". The banned user gets support tickets.

Inertia Shared Props

// HandleInertiaRequests middleware
public function share(Request $request): array
{
    return [
        // ... other shared data
        'block_status' => ($this->getBlockStatus)(),
    ];
}

Every page has access to block_status. The Vue frontend can:

Show warning banners: "Your subscription expires in 3 days"
Disable features incrementally
Display countdown timers

The middleware blocks. Inertia warns. Two different mechanisms for two different purposes.

Responsive design: desktop shows side-by-side layout with icon and message, mobile stacks vertically. Dark mode supported via CSS variables.

Payment Model

CompanyPayment

class CompanyPayment extends Model
{
    // Fields
    // company_id, user_id, plan_id, billing_period
    // amount, currency, discount_amount, discount_reason, promo_code_id
    // payment_status, payment_method, payment_response (JSON)
    // paid_at, period_start, period_end

    protected function casts(): array
    {
        return [
            'amount' => 'decimal:2',
            'discount_amount' => 'decimal:2',
            'payment_response' => 'array',
            'paid_at' => 'datetime',
            'period_start' => 'date',
            'period_end' => 'date',
        ];
    }

    public function markAsPaid(?array $response = null): void
    {
        $this->update([
            'payment_status' => 'success',
            'paid_at' => now(),
            'payment_response' => $response,
        ]);
    }

    public function markAsFailed(?array $response = null): void
    {
        $this->update([
            'payment_status' => 'failed',
            'payment_response' => $response,
        ]);
    }

    public function getTotalAmount(): float
    {
        return $this->amount - $this->discount_amount;
    }

    public function isSuccessful(): bool { return $this->payment_status === 'success'; }
    public function isPending(): bool { return $this->payment_status === 'pending'; }
    public function isFailed(): bool { return $this->payment_status === 'failed'; }
}

Clean state transitions. markAsPaid() sets status, timestamp, and stores raw gateway response. No string comparisons scattered across controllers.

Events

Every successful payment fires CompanyPaymentProcessed:

public function getLogProperties(): array
{
    return [
        'company_id' => $this->company->id,
        'company_name' => $this->company->name,
        'payment_id' => $this->payment->id,
        'plan_id' => $this->payment->plan_id,
        'amount' => $this->payment->amount,
        'currency' => $this->payment->currency,
        'discount_amount' => $this->payment->discount_amount,
        'payment_status' => $this->payment->payment_status,
        'period_start' => $this->payment->period_start,
        'period_end' => $this->payment->period_end,
    ];
}

Full audit trail. Every dollar tracked.

Admin View

In the admin panel, payment data is displayed in two layers:

Table level: Total payments sum and last payment date (calculated via SQL subquery)
Tooltip level: Full payment history with individual amounts, discounts, and dates

// AdminCompanyResource
'payments_history' => $this->payments->map(fn ($p) => [
    'id' => $p->id,
    'date' => $p->paid_at?->format('d-m-Y'),
    'amount' => $p->amount,
    'discount' => $p->discount_amount,
    'currency' => $p->currency,
    'total' => $p->getTotalAmount(),
]),

Admin Filtering and Search

AdminCompaniesFilter

class AdminCompaniesFilter extends Filter
{
    protected function subscription_status(?string $value): Builder
    {
        return match ($value) {
            'active' => $this->builder
                ->where('subscription_ends_at', '>', now())
                ->where('subscription_ends_at', '>', now()->addDays(7)),
            'expiring' => $this->builder
                ->where('subscription_ends_at', '>', now())
                ->where('subscription_ends_at', '<=', now()->addDays(7)),
            'expired' => $this->builder
                ->where('subscription_ends_at', '<=', now())
                ->whereNotNull('subscription_ends_at'),
            'trial' => $this->builder
                ->where('trial_ends_at', '>', now())
                ->whereNotNull('trial_ends_at'),
            'never_activated' => $this->builder
                ->whereNull('plan_id')
                ->whereNull('trial_ends_at')
                ->whereNull('subscription_ends_at'),
        };
    }

    protected function plan_id(?string $value): Builder { /* exact match */ }
    protected function country(?string $value): Builder { /* exact match */ }
    protected function date_from(?string $value): Builder { /* created_at >= */ }
    protected function date_to(?string $value): Builder { /* created_at <= */ }

    protected function search_string(?string $value): Builder
    {
        return $this->builder->where(function ($q) use ($value) {
            $q->where('name', 'like', "%{$value}%")
              ->orWhereHas('createdBy', fn($q) => $q->where('email', 'like', "%{$value}%"));
        });
    }
}

Same auto-discovery pattern from previous modules. Request has ?subscription_status=expiring&plan_id=basic? Base Filter class iterates params, calls matching methods.

Validation

class AdminCompaniesFilterRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'subscription_status' => 'nullable|in:active,expiring,expired,trial,never_activated',
            'plan_id' => 'nullable|in:basic,optimal,advanced',
            'country' => 'nullable|string',
            'date_from' => 'nullable|date',
            'date_to' => 'nullable|date|after_or_equal:date_from',
            'search_string' => 'nullable|string|max:255',
            'sort_by' => 'nullable|in:created_at,subscription_ends_at,employees_count,payments_sum',
            'sort_order' => 'nullable|in:asc,desc',
        ];
    }
}

Everything validated before reaching the filter. Invalid params can't cause SQL errors.

Quick Search

public function search(Request $request): JsonResponse
{
    $companies = Company::query()
        ->where('name', 'like', "%{$search}%")
        ->orWhereHas('createdBy', fn($q) => $q->where('email', 'like', "%{$search}%"))
        ->limit(15)
        ->get(['id', 'name']);

    return response()->json($companies);
}

Separate JSON endpoint. 15 results max. Used in admin navigation for fast company lookup.

Testing

Subscription Status

test('company with future subscription has access', function () {
    $company = Company::factory()->create([
        'subscription_ends_at' => now()->addMonth(),
    ]);

    expect($company->hasAccess())->toBeTrue()
        ->and($company->hasActiveSubscription())->toBeTrue();
});

test('company on trial has access even without subscription', function () {
    $company = Company::factory()->create([
        'trial_ends_at' => now()->addDays(14),
        'subscription_ends_at' => null,
    ]);

    expect($company->hasAccess())->toBeTrue()
        ->and($company->isOnTrial())->toBeTrue();
});

test('company with expired subscription has no access', function () {
    $company = Company::factory()->create([
        'subscription_ends_at' => now()->subDay(),
        'trial_ends_at' => now()->subMonth(),
    ]);

    expect($company->hasAccess())->toBeFalse();
});

Ban Cascade

test('blocking owner blocks employee access', function () {
    $owner->update(['user_blocked_at' => now(), 'user_blocked_status' => 1]);

    actingAs($employee)
        ->get(route('dashboard'))
        ->assertRedirect(route('company.payment.blocked'));
});

test('employee can switch to another company when owner is banned', function () {
    // Employee belongs to companyA (owner banned) and companyB (active)
    actingAs($employee)
        ->post(route('company.switch', $companyB))
        ->assertRedirect();
});

Payment Events

test('successful payment fires CompanyPaymentProcessed', function () {
    Event::fake();

    $payment->markAsPaid(['gateway_status' => 'ok']);

    Event::assertDispatched(CompanyPaymentProcessed::class);
    expect($payment->isSuccessful())->toBeTrue()
        ->and($payment->paid_at)->not->toBeNull();
});

Expiry Notifications

test('expiring subscription triggers notification at 10 days', function () {
    $company = Company::factory()->create([
        'subscription_ends_at' => now()->addDays(10),
    ]);

    Artisan::call('subscriptions:check-expiring');

    expect(Notification::where('code', "subscription_expiring_10d_{$company->id}")->exists())
        ->toBeTrue();
});

test('banned owner does not receive expiry notification', function () {
    $company = Company::factory()->create([
        'subscription_ends_at' => now()->addDays(10),
    ]);
    $company->createdBy->update(['user_blocked_at' => now()]);

    Artisan::call('subscriptions:check-expiring');

    expect(Notification::where('code', "subscription_expiring_10d_{$company->id}")->exists())
        ->toBeFalse();
});

Admin Filtering

test('admin can filter companies by subscription status', function () {
    actingAs($admin)
        ->get(route('admin.companies.index', ['subscription_status' => 'expired']))
        ->assertOk()
        ->assertInertia(fn ($page) => $page->has('companies.data'));
});

test('admin search finds company by owner email', function () {
    actingAs($admin)
        ->get(route('admin.companies.search', ['search' => $owner->email]))
        ->assertOk()
        ->assertJsonCount(1);
});

Pest v4. Real HTTP requests. No middleware mocking. The tests prove the behavior users experience.

Design Decisions

hasAccess() checks both trial AND subscription. A company on trial with an expired subscription still works. Trial takes priority over subscription status. No double penalty.
GetBlockStatusAction as single source of truth. One place calculates all blocking logic. Middleware uses it. Frontend uses it (via Inertia shared props). No duplicated conditions.
Three block reasons, not one. "Company blocked" is useless information. "Owner banned" vs "payment expired" vs "never paid" - each requires different user action.
Owner/employee split on blocked pages. Owner can fix the problem (pay, appeal). Employee can't. Showing an employee a billing link makes no sense.
Per-company blocking, not per-user. User owns Company A (banned owner) and Company B (active). They can switch to B. Blocking one company shouldn't kill their entire account.
Unique notification codes. subscription_expiring_10d_42 ensures the same notification is never sent twice. Cron-safe.
Subqueries for aggregates in admin. Total payments, last payment date - calculated in SQL. One query with subqueries is faster than loading all payments and summing in PHP.
Config-driven plans and statuses. Plan names, subscription status thresholds (7 days for "expiring"), pagination limits - all in config. Changing a threshold doesn't require code changes.

What's Next

This module is part of LaraFoundry - an open-source SaaS framework for Laravel, extracted from a production CRM/ERP.

GitHub: github.com/dmitryisaenko/larafoundry
Previous modules: Registration, Authentication, Multi-Tenancy, Logging, Multilanguage, Navigation, Vue Frontend, Traits & Middlewares, Admin Users

Follow for the next module deep-dive.

Building an Admin User Management System for a Multi-Tenant Laravel SaaS

Dmitry Isaenko — Mon, 27 Apr 2026 10:19:57 +0000

You built a SaaS. Users signed up. Now you need to actually manage them. And "manage" means a lot more than a table with an edit button.

I built Kohana.io - a production CRM/ERP for small businesses. The admin user management module turned out to be one of the most complex pieces in the system. Now I'm extracting it into LaraFoundry, an open-source SaaS framework for Laravel.

This post covers the full implementation: CRUD, banning, impersonation, activity logging, and search/filtering.

CRUD Architecture
Ban System
Impersonation ("Follow")
Activity Logging
Search & Filtering
Testing
Design Decisions

CRUD Architecture

Create

User creation goes through AdminUserStoreRequest - validation happens before the controller.

Validated fields:

Required: name, email, password (with confirmation)
Optional: lastname, middlename, phone, sex, country, birth_date
Social links: array validation - URL must be valid, social network must exist in config

Password handling:

// User model
protected function password(): Attribute
{
    return Attribute::make(
        set: fn ($value) => Hash::make($value),
    );
}

The controller never calls Hash::make(). The Eloquent Attribute mutator handles it. Create, update, import - doesn't matter. One place for hashing.

Social links are validated as an array:

'social_links' => 'nullable|array',
'social_links.*.url' => 'nullable|url|max:255',
'social_links.*.social_network' => 'required_with:social_links.*.url|in:' . implode(',', $configuredNetworks),

Read (Index)

public function index(AdminUserFilterRequest $request, AdminUsersFilter $filter): Response
{
    $users = User::query()
        ->filter($filter)
        ->paginate(config('own.admin_users_per_page'));

    return Inertia::render('admin/users/Users', [
        'users' => UserResource::collection($users),
        'totalUsers' => User::count(),
    ]);
}

Three key decisions here:

Filter injection - AdminUsersFilter is injected, applied via scope. Controller doesn't know how filtering works.
UserResource - one transformation layer for all responses. The Vue frontend gets consistent data.
Config-driven pagination - page size lives in config, not hardcoded.

What the Admin Sees Per User

Every row in the admin users table shows:

Column	Data
ID	User ID
Avatar	Profile image or default placeholder
Name	Full name (lastname + name), with block/delete reason if applicable
Email / Phone	Email with verification icon, phone with verification icon, social network links
Registration / Activity	Registration date, last activity (with "long ago" warning highlight)
Companies	Owned companies count / employee companies count
Country	Localized country name
Sex	Gender
Age	Calculated from birth_date
Actions	Create ticket, view logs, edit, block/unblock, delete/undelete, impersonate

The UserResource handles all transformation:

return [
    'id' => $this->id,
    'name' => trim($this->lastname . ' ' . $this->name),
    'avatar' => $this->avatar_url ?? '/images/default-user-logo.png',
    'email' => $this->email,
    'phone' => $this->phone,
    'email_verificated' => $this->email_verified_at !== null,
    'phone_verificated' => $this->phone_verified_at !== null,
    'social_links' => $this->socialLinks->map(/* ... */),
    'country' => $localizedCountryName,
    'age' => $this->birth_date?->age,
    'sex' => $genderLabel,
    'created_at' => $this->created_at->format('d-m-Y'),
    'last_activity_at' => $formattedActivity, // "5 min ago", "long_ago", "Never"
    'owned_companies_count' => $ownedCount,
    'employee_companies_count' => $employeeCount,
    'user_blocked_at' => $this->user_blocked_at,
    'block_code_text' => $formattedBlockReason, // "1. SPAM (3 days ago)"
    'user_deleted_at' => $this->user_deleted_at,
];

Blocked users get a visual badge and the row is styled differently. Deleted users too. Action buttons change based on status: blocked users show "unblock" instead of "block", deleted users show "restore" instead of "delete".

Update

Social links are managed in a database transaction:

DB::transaction(function () use ($user, $validated) {
    $user->socialLinks()->delete();

    foreach ($validated['social_links'] ?? [] as $link) {
        if (trim($link['url'] ?? '') !== '') {
            $user->socialLinks()->create([
                'url' => $link['url'],
                'social_network' => $link['social_network'],
            ]);
        }
    }
});

Delete all existing, create new ones. Atomic operation. No orphaned records.

Email uniqueness on update ignores the current user:

'email' => ['required', 'email', Rule::unique(User::class)->ignore($this->route('user')->id)],

The controller also supports a return_url parameter - so the admin lands back exactly where they navigated from.

Delete (Soft)

Deletion sets a user_deleted_at timestamp. Not Laravel's SoftDeletes trait - we use separate timestamps for blocking and deletion.

public function delete(User $user): RedirectResponse
{
    $user->update([
        'user_deleted_at' => now(),
        'user_blocked_at' => null,
        'user_blocked_status' => null,
    ]);

    return back()->with('success', __('User deleted'));
}

Deleting clears block status. A user can't be both blocked and deleted.

Restoring is the reverse: clear user_deleted_at.

Ban System

Banning is not a boolean toggle. It's a multi-step process with events, notifications, and cascade effects.

Block Reasons (Config-Driven)

// config/own.php
'block_codes' => [
    1 => 'SPAM',
    2 => 'Violation of the rules of service',
    3 => 'Inappropriate behavior',
    4 => 'Fake account',
    5 => 'Reason 05',
]

Add a ban reason = add a config entry. No code changes. No migrations.

Block Flow

When an admin clicks "Block":

Database update - user_blocked_at = now(), user_blocked_status = $reasonId
Event dispatch - event(new UserBlocked(auth()->user(), $user, $reasonId))
Queue job - NotifyUserAboutBlocked::dispatch($user, $reasonId)

Two separate concerns: event for activity logging, job for email notification. The admin doesn't wait for SMTP.

Access Enforcement

CheckAccessMiddleware runs on every authenticated request. Three levels:

Level 1 - User ban:
The user is redirected to a "blocked" page. But they can still access:

Support tickets (to appeal the ban)
Notifications
Tutorials
Language switching
Logout
Leave impersonation

Locking someone out with zero recourse is bad UX and possibly a legal problem.

Level 2 - Company owner ban:
Every employee of the banned owner's company gets blocked. Different page, different message. They know it's the owner's issue, not theirs.

Level 3 - Payment expired:
Users can access payment pages and settings, but the rest of the app shows alerts.

Blocked User Page

The blocked user sees their ban reason and date:

public function show(Request $request): Response
{
    return Inertia::render('user/Blocked', [
        'blockReason' => $request->user()->getUserBlockedStatus(),
        'blockDate' => $request->user()->getUserBlockedDate(),
    ]);
}

Access to this page is gated - only users with user_blocked_at !== null can see it.

Unblock

Clears timestamps, fires UserUnblocked event, dispatches NotifyUserAboutUnblocked job. Clean reverse.

Event Logging

Every block/unblock is captured in the activity log with full context:

public function getLogProperties(): array
{
    return [
        'user_id' => $this->user->id,
        'user_name' => $this->user->getFullname(),
        'user_email' => $this->user->email,
        'blocked_at' => $this->user->user_blocked_at?->toDateTimeString(),
        'block_reason_id' => $this->reasonId,
        'block_reason' => $reasonText,
    ];
}

Who blocked whom, when, and why. Complete audit trail.

Impersonation

"I can't see that button on my dashboard."

One click - you're logged in as that user. Seeing exactly what they see.

Implementation

class ImpersonateController extends Controller
{
    public function take(Request $request, $userId, ImpersonateManager $impersonate)
    {
        $user = User::findOrFail($userId);
        $impersonate->take($request->user(), $user);
        return Inertia::location(route('home'));
    }

    public function leave(ImpersonateManager $impersonate)
    {
        $impersonate->leave();
        return Inertia::location(route('admin.users.index'));
    }
}

Built on lab404/laravel-impersonate. The admin session is preserved.

Frontend Awareness

Every page knows if impersonation is active:

// HandleInertiaRequests middleware
'impersonate' => [
    'isActive' => $impersonate->isImpersonating()
]

The Vue frontend can show a warning bar: "You are viewing as User X" with a "Leave" button.

Security

Route requires AdminAccess middleware
2FA verification required
Activity log captures the event
"Leave impersonation" route is whitelisted even for banned users (admin can exit cleanly)
"Follow" button hidden for blocked or deleted users

UI

<Link @click.stop class="btn follow"
      :href="route('admin.impersonate.take', user.id)"
      method="post"
      :title="t('Follow')">
    <!-- person + arrow icon -->
</Link>

Inertia <Link> component with POST method. No JavaScript fetch calls. No page reload after leaving - Inertia::location() handles full redirect.

Activity Logging

Every action in the system flows through ActivityLogServiceProvider. 30+ event types: login, logout, failed login, user blocked, company created, warehouse updated - everything.

What Gets Stored

Extended Spatie's Activity model with CustomActivity:

activity_log table:
├── core: log_name, description, subject_type, subject_id, causer_id
├── geo: geo_country, geo_city, geo_updated_at
├── device: user_device_type, user_device_name, user_os, user_browser
├── network: user_ip, user_agent
├── request: route_name, request_method, full_url, response_code
└── status: is_successful

Plus custom event properties in the properties JSON column.

Logging Flow

Event fires (e.g., UserBlocked)
ActivityLogServiceProvider listener captures it
ActivityLogService::logActivity() creates the record with all metadata
RetrieveActivityGeoData job dispatched to resolve IP → country/city asynchronously

The geo lookup is a queued job. The original request isn't slowed by an external API call. Geo data appears in the activity log when the job completes.

Admin UI - User Activity Log

Route: GET /admin/logs/{user}?hours=1

Time range selector: Buttons for 1h, 6h, 12h, 24h, 48h, 72h. Because "show me the last hour" is 90% of debugging.

Table with interactive tooltips:

Hover IP → Device type, device name, OS, browser, country, city
Hover action → Event name, route name, middleware chain, request method, full URL, event properties

Desktop shows a table. Mobile shows cards. Same data, different layout via responsive Vue component.

General Activity Log

Route: GET /admin/logs?hours=24

System-wide activity. All events. 100 per page. Useful for spotting patterns across users.

Data Transformation

ActivityLogResource prepares the data:

'formatted_date' => $this->created_at->format('d.m.Y H:i:s'),
'human_date' => $this->created_at->locale(config('app.locale'))->diffForHumans(),
'response_code' => $this->response_code,
'is_successful' => $this->is_successful,

Search and Filtering

Multi-Field Search

protected function search_string($value): Builder
{
    return $this->builder->where(function ($query) use ($value) {
        $query->where('id', $value)
            ->orWhere('name', 'like', "{$value}%")
            ->orWhere('lastname', 'like', "{$value}%")
            ->orWhere('middlename', 'like', "{$value}%")
            ->orWhere('email', 'like', "{$value}%")
            ->orWhere('phone', 'like', "{$value}%")
            ->orWhereRaw("lastname || ' ' || name LIKE ?", ["{$value}%"])
            ->orWhereRaw("name || ' ' || lastname LIKE ?", ["{$value}%"])
            ->orWhereRaw("lastname || ' ' || name || ' ' || middlename LIKE ?", ["{$value}%"])
            ->orWhereRaw("name || ' ' || lastname || ' ' || middlename LIKE ?", ["{$value}%"]);
    });
}

"Smith John" works. "John Smith" works. "Smith" works. User ID works. Email prefix works.

Filter Auto-Discovery

Same pattern from the Traits & Middlewares module:

class AdminUsersFilter extends Filter
{
    protected function search_string($value) { /* multi-field search */ }
    protected function age_from($value) { /* birth_date <= now - age years */ }
    protected function age_to($value) { /* birth_date >= now - age years */ }
    protected function country($value) { /* exact match */ }
    protected function registrated($value) { /* today | this_month | this_year */ }
    protected function email_verificated($value) { /* verificated | unverificated */ }
    protected function phone_verificated($value) { /* verificated | unverificated */ }
    protected function recent_activity($value) { /* configurable threshold */ }
    protected function sex($value) { /* m | f */ }
}

Request has ?age_from=25&country=DE? Base Filter class iterates request params, calls matching methods. No switch statements. No config mappings.

Validation

Every filter parameter goes through AdminUserFilterRequest:

'age_from' => 'nullable|integer|min:16|max:100',
'age_to' => 'nullable|integer|min:16|max:100',
'country' => 'nullable|string|in:' . implode(',', array_keys(config('app.available_countries'))),
'registrated' => 'nullable|string|in:all,today,this_month,this_year',
'recent_activity' => 'nullable|string|in:all,more,less_or_equal',
'email_verificated' => 'nullable|string|in:all,verificated,unverificated',
'sex' => 'nullable|string|in:m,f',

Real-Time Search

Separate endpoint: GET /admin/users/search

public function search(AdminUserFilterRequest $request, AdminUsersFilter $filter): JsonResponse
{
    $users = User::query()
        ->where('email', '!=', config('own.admin_email'))
        ->filter($filter)
        ->paginate(config('own.admin_users_per_page'));

    return response()->json([
        'users' => UserResource::collection($users),
        'search' => $request->input('search_string'),
    ]);
}

Returns JSON. Frontend component shows matching users as you type. Click a result = navigate to user.

Testing

Admin user management touches auth, permissions, events, jobs, middleware, and database. All tested through HTTP behavior.

CRUD

test('admin can create user with valid data', function () {
    actingAs($admin)
        ->post(route('admin.users.store'), [
            'name' => 'John',
            'email' => 'john@example.com',
            'password' => 'securepassword',
            'password_confirmation' => 'securepassword',
        ])
        ->assertRedirect();

    expect(User::where('email', 'john@example.com')->exists())->toBeTrue();
});

test('admin cannot create user with duplicate email', function () {
    User::factory()->create(['email' => 'taken@example.com']);

    actingAs($admin)
        ->post(route('admin.users.store'), [
            'name' => 'John',
            'email' => 'taken@example.com',
            'password' => 'securepassword',
            'password_confirmation' => 'securepassword',
        ])
        ->assertSessionHasErrors('email');
});

Ban Cascade

test('blocking company owner blocks employees', function () {
    actingAs($admin)
        ->post(route('admin.users.block', $owner), ['reason_id' => 1]);

    actingAs($employee)
        ->get(route('dashboard'))
        ->assertRedirect(route('company.payment.blocked'));
});

test('blocked user can access support tickets', function () {
    actingAs($blockedUser)
        ->get(route('tickets.index'))
        ->assertOk();
});

Events & Jobs

Event::fake();
Queue::fake();

actingAs($admin)
    ->post(route('admin.users.block', $user), ['reason_id' => 1]);

Event::assertDispatched(UserBlocked::class);
Queue::assertPushed(NotifyUserAboutBlocked::class);

Impersonation

test('admin can impersonate user', function () {
    actingAs($admin)
        ->post(route('admin.impersonate.take', $user))
        ->assertRedirect(route('home'));
});

test('cannot impersonate blocked user', function () {
    // Follow button hidden in UI; route-level protection
});

Pest v4 + Laravel's HTTP testing. No mocking middleware. No testing implementation details. Assert what users experience.

Design Decisions

Timestamps, not booleans. user_blocked_at instead of is_blocked. You need to know WHEN it happened. "Blocked 3 days ago" is actionable. "Blocked: yes" tells you nothing.
Events + jobs, not inline logic. Blocking fires an event (for logging) and a job (for notification). Two concerns, two mechanisms. The admin response isn't blocked by SMTP.
Config-driven ban reasons. Adding a reason shouldn't require a migration or a code change. Config array entry is enough.
Filter auto-discovery reuse. Same abstract Filter class from the Traits module. AdminUsersFilter just defines the methods. Zero framework code duplicated.
Async geo lookup. Activity log stores device data synchronously (it's already in the request). Geo data resolved via queue job. Speed vs completeness trade-off.
Separate timestamps for block and delete. A user can be blocked and later unblocked. Or blocked and then deleted (clearing block status). Different states, different semantics.
Impersonation with guardrails. 2FA required. Activity logged. Frontend awareness built in. "Leave" route always available.

What's Next

This module is part of LaraFoundry - an open-source SaaS framework for Laravel, extracted from a production CRM/ERP.

GitHub: github.com/dmitryisaenko/larafoundry
Previous modules: Registration, Authentication, Multi-Tenancy, Logging, Multilanguage, Navigation, Vue Frontend, Traits & Middlewares

Follow for the next module deep-dive.

11 Middlewares and 6 Traits That Power a Multi-Tenant Laravel SaaS

Dmitry Isaenko — Mon, 20 Apr 2026 09:14:13 +0000

Every request in a multi-tenant SaaS needs to answer a dozen questions before your controller runs. Which company context? Is the session valid? Is the user banned? Has the subscription expired? Should the screen be locked? What language?

I built Kohana.io - a production CRM/ERP - and ended up with 11 custom middlewares and 6 traits. Not because I wanted to over-engineer, but because each one solved a recurring problem. Now I'm extracting them into LaraFoundry, an open-source SaaS framework for Laravel.

This post covers the full middleware stack, all custom traits, and the design decisions behind them.

The Middleware Stack

Order matters. Here's the complete stack with execution sequence:

 1. HandleInertiaRequests         → shares props with Vue frontend
 2. SetActiveCompanyMiddleware    → resolves company context
 3. UpdateLastSessionActivity     → tracks activity + device info
 4. AddLinkHeadersForPreloadedAssets → HTTP/2 push
 5. StoreIntendedUrl              → saves URL for post-auth redirects
 6. SetLocale                     → detects language
 7. EnsureEmailIsVerified         → gates unverified users
 8. CheckPinLockMiddleware        → locks after inactivity
 9. CheckAccessMiddleware         → user bans, owner bans, payment
10. CheckSessionExists            → validates session in DB
11. CheckForSessionValidity       → regenerates token if needed

Why order matters:

SetActiveCompanyMiddleware MUST run before CheckAccessMiddleware - access checks need company context to verify payment status
UpdateLastSessionActivity MUST run before CheckPinLockMiddleware - PIN timeout calculated from last_activity timestamp
SetLocale MUST run before EnsureEmailIsVerified - verification page needs correct language

In Laravel 12, middlewares are configured in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        HandleInertiaRequests::class,
        SetActiveCompanyMiddleware::class,
        UpdateLastSessionActivityMiddleware::class,
        AddLinkHeadersForPreloadedAssets::class,
        StoreIntendedUrl::class,
        SetLocale::class,
        EnsureEmailIsVerified::class,
        CheckPinLockMiddleware::class,
        CheckAccessMiddleware::class,
        CheckSessionExists::class,
        CheckForSessionValidityMiddleware::class,
    ]);
})

One declaration. Full picture. No Kernel.php scattering.

Middleware Deep-Dives

SetActiveCompanyMiddleware - Company Context Resolution

A user can own Company A and be an employee at Company B simultaneously. This middleware determines which company context each request runs in.

public function handle(Request $request, Closure $next)
{
    if (!auth()->check() || !$request->user()->hasVerifiedEmail()) {
        return $next($request);
    }

    $user = $request->user();
    $sessionCompanyId = session('active_company_id');

    // Validate: does user still belong to this company?
    if ($sessionCompanyId && !$user->companies->contains('id', $sessionCompanyId)) {
        session()->forget('active_company_id');
        $sessionCompanyId = null;
    }

    // Priority: owned company, then employee company
    $companies = $user->companies()->whereNull('deleted_at')->get();
    $activeCompany = $companies->firstWhere('pivot.is_owner', true)
                  ?? $companies->first();

    $this->setActiveCompany($activeCompany);
    return $next($request);
}

Resolution priority:

Valid session company (user switched manually) → keep it
First company where user is owner
First company where user is employee

Edge cases handled: deleted companies filtered. Invalid session values cleared. Users who lost company access don't keep stale context.

CheckPinLockMiddleware - Inactivity Screen Lock

After 30 minutes without activity, the screen locks. PIN code required to continue.

public function handle(Request $request, Closure $next)
{
    $session = UserSession::where('session_id', session()->getId())->first();

    if (!$session || !$session->last_activity) {
        $session?->update(['last_activity' => now()]);
        return $next($request);
    }

    $secondsSinceActivity = now()->diffInSeconds($session->last_activity);

    if ($secondsSinceActivity >= config('security.pin_lock_timeout', 1800)) {
        $session->update(['pin_locked' => true]);

        if ($request->expectsJson()) {
            return response()->json(['message' => 'session_locked'], 423);
        }

        return redirect()->route('pin.enter');
    }

    return $next($request);
}

Design decisions:

Database-backed state - PIN lock stored in user_sessions.pin_locked, not in PHP session. Can't bypass by manipulating cookies.
HTTP 423 for APIs - JSON requests get a proper status code, not a redirect to an HTML page.
Configurable timeout - config('security.pin_lock_timeout') defaults to 1800 seconds (30 min).
Unlock redirects back - After entering PIN, user returns to last_route_name stored by UpdateLastSessionActivity.

CheckAccessMiddleware - Three-Level Access Control

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

    // Level 1: User ban
    if ($user->user_blocked_at !== null) {
        $allowed = ['user.blocked', 'logout', 'notifications.*', 'tickets.*'];
        if (!$request->routeIs(...$allowed)) {
            return redirect()->route('user.blocked');
        }
    }

    // Level 2: Company owner ban
    $company = activeCompany();
    if ($company && $company->owner->user_blocked_at !== null) {
        return redirect()->route('company.payment.blocked', ['type' => 'owner_banned']);
    }

    // Level 3: Payment status
    if ($company && !$company->isInSetup() && !$company->hasAccess()) {
        $allowed = ['new_company.*', 'my_company.service_payment', 'company.payment.blocked'];
        if (!$request->routeIs(...$allowed)) {
            return redirect()->route('company.payment.blocked');
        }
    }

    return $next($request);
}

Three levels with specific route whitelists:

Level	Condition	Allowed Routes	Everything Else
User ban	`user_blocked_at != null`	logout, notifications, tickets, tutorials	→ user.blocked
Owner ban	Company owner is banned	(none for employees)	→ company.payment.blocked
Payment	Trial/subscription expired	payment pages, company settings	→ company.payment.blocked

Banned users can still reach support. Expired subscriptions still allow reaching payment pages. Practical, not punitive.

SetLocale - Language Detection Chain

// Authenticated user detection chain
private function detectAuthenticatedLocale(User $user, Request $request): string
{
    // 1. User profile preference
    if ($user->locale && in_array($user->locale, $availableLanguages)) {
        return $user->locale;
    }

    // 2. Session locale
    if (session('locale') && in_array(session('locale'), $availableLanguages)) {
        return session('locale');
    }

    // 3. Browser Accept-Language header
    $browserLocale = $this->detectFromBrowser($request);
    if ($browserLocale) return $browserLocale;

    // 4. IP geolocation (2s timeout)
    $geoLocale = $this->detectFromIp($request->ip());
    if ($geoLocale) return $geoLocale;

    // 5. App default
    return config('app.locale');
}

For guests, the chain uses cookies (10-year lifetime) instead of user profile. IP geolocation calls ip-api.com with a 2-second timeout - if it fails, we silently fall back. No broken pages from API downtime.

Config-driven mappings:

// config/app.php
'browser_locale_map' => ['de' => 'de', 'uk' => 'ua', 'ru' => 'ru'],
'country_locale_map' => ['DE' => 'de', 'UA' => 'ua', 'US' => 'en'],

Adding a new language = two array entries. No code changes.

UpdateLastSessionActivityMiddleware - Activity + Device Tracking

public function handle(Request $request, Closure $next)
{
    $response = $next($request);

    if (!auth()->check()) return $response;

    // Skip non-trackable requests
    if ($this->shouldSkip($request, $response)) return $response;

    $session = UserSession::where('session_id', session()->getId())->first();
    if (!$session) return $response;

    $agent = new Agent();

    $session->update([
        'last_activity' => now(),
        'last_route_name' => $request->route()?->getName(),
        'device_type' => $agent->isDesktop() ? 'desktop' : ($agent->isTablet() ? 'tablet' : 'mobile'),
        'device_name' => $agent->device(),
        'os' => $agent->platform(),
        'browser' => $agent->browser(),
    ]);

    $request->user()->update(['last_activity_at' => now()]);

    return $response;
}

Skipped for: PIN routes (would reset timeout), non-HTML requests, redirects, excluded routes (profile, notifications, API).

Result: admin panel shows "User X on Chrome/Windows/Desktop, last active 3 minutes ago on orders page." Useful for support, analytics, and security monitoring.

Session Validation - Anti-Hijacking

Two middlewares work together:

CheckSessionExists - validates session for all requests:

$exists = UserSession::where('user_id', $user->id)
    ->where('session_id', session()->getId())
    ->exists();

if (!$exists) {
    Auth::logout();
    $request->session()->invalidate();

    return $request->expectsJson()
        ? response()->json(['message' => 'session_expired'], 401)
        : redirect('/');
}

CheckForSessionValidity - additional cleanup for browser requests:

if (!$exists) {
    Cookie::queue(Cookie::forget('remember_web_*'));
    $request->session()->invalidate();
    $request->session()->regenerateToken();
    return redirect('/');
}

Why two? Different cleanup for different scenarios. The first handles JSON/API (returns 401). The second handles full browser cleanup (forget cookies, regenerate CSRF token).

Force logout from admin panel = delete the user_sessions row. Next request from that device = instant rejection.

Custom Traits

HasPagination

trait HasPagination
{
    protected function getPaginationData($paginator): array
    {
        if (!$paginator instanceof LengthAwarePaginator
            && !$paginator instanceof Paginator) {
            return [];
        }

        return [
            'current_page' => $paginator->currentPage(),
            'last_page'    => $paginator->lastPage(),
            'per_page'     => $paginator->perPage(),
            'total'        => $paginator->total(),
            'from'         => $paginator->firstItem(),
            'to'           => $paginator->lastItem(),
        ];
    }
}

Used in every controller that lists data. Type-safe - returns empty array if input isn't a paginator. The frontend PagePaginator component expects this exact structure. 15 list views, zero pagination code duplication.

Controller usage:

$paginated = $query->filter($filter)->paginate($perPage)->withQueryString();

return Inertia::render('warehouse/Products', [
    'products'   => ProductResource::collection($paginated),
    'pagination' => $this->getPaginationData($paginated),
]);

.withQueryString() preserves all filter parameters in pagination links.

Filter Auto-Discovery

abstract class Filter
{
    protected Builder $builder;
    protected Request $request;

    public function apply(Builder $builder)
    {
        $this->builder = $builder;
        foreach ($this->request->all() as $name => $value) {
            if (method_exists($this, $name)) {
                call_user_func_array([$this, $name], [$value]);
            }
        }
        return $this->builder;
    }
}

Request param country=DE → calls $filter->country('DE'). Method exists = filter applied. No routing config. No switch statements. No registration.

Concrete example:

class ContragentsFilter extends Filter
{
    public function search_string($value = null)
    {
        $words = preg_split('/\s+/', trim($value));
        return $this->builder->where(function ($query) use ($words) {
            foreach ($words as $word) {
                $query->whereRaw('LOWER(name) LIKE ?', ['%'.mb_strtolower($word).'%']);
            }
        });
    }

    public function sort_by($value = null)
    {
        $allowed = ['name', 'country', 'balance', 'created_at'];
        if (in_array($value, $allowed)) {
            $direction = $this->request->input('sort_direction', 'asc');
            return $this->builder->orderBy($value, $direction);
        }
        return $this->builder->orderBy('name', 'asc');
    }

    public function starts_with($value = null)
    {
        return $this->builder->where('name', 'LIKE', $value . '%');
    }

    public function country($value = null)
    {
        return $this->builder->where('country', $value);
    }
}

Key security: whitelisted sort columns prevent SQL injection. Word-by-word search for partial matching. Alphabetical navigation via starts_with().

NotificationDataHandler

trait NotificationDataHandler
{
    protected function prepareNotificationData(array $validated, string $status = 'draft'): array
    {
        return [
            'code' => $validated['code'],
            'notification_type' => $validated['notification_type'],
            'status' => $status,
            // Multilingual content
            'title' => ['en' => $validated['title_en'], 'de' => $validated['title_de'] ?? null],
            'body' => ['en' => $validated['body_en'], 'de' => $validated['body_de'] ?? null],
            // Recipient filters
            'filter_country' => $validated['filter_country'] ?? null,
            'filter_sex' => $validated['filter_sex'] ?? null,
            'filter_age_from' => $validated['filter_age_from'] ?? null,
            'filter_age_to' => $validated['filter_age_to'] ?? null,
            'filter_registered' => $validated['filter_registered'] ?? null,
            'filter_activity' => $validated['filter_activity'] ?? null,
            'filter_email_verified' => $validated['filter_email_verified'] ?? null,
            'filter_phone_verified' => $validated['filter_phone_verified'] ?? null,
            // Visibility window
            'visible_from' => $validated['visible_from'] ?? null,
            'visible_until' => $validated['visible_until'] ?? null,
        ];
    }
}

Notifications in a SaaS can target user segments: users from Germany, aged 25-40, registered this month, with verified email. This trait centralizes data transformation so create and update controllers use the same mapping. No drift between them.

HasUserFilterRules (Companion to NotificationDataHandler)

trait HasUserFilterRules
{
    protected function getUserFilterRules(): array
    {
        return [
            'filter_country' => ['nullable', Rule::in(config('app.available_countries'))],
            'filter_sex' => ['nullable', Rule::in(['m', 'f'])],
            'filter_age_from' => ['nullable', 'integer', 'min:16', 'max:100'],
            'filter_age_to' => ['nullable', 'integer', 'min:16', 'max:100'],
            'filter_registered' => ['nullable', Rule::in(['all', 'today', 'this_month', 'this_year'])],
            'filter_activity' => ['nullable', Rule::in(['recently_active', 'inactive'])],
            'filter_email_verified' => ['nullable', 'boolean'],
            'filter_phone_verified' => ['nullable', 'boolean'],
        ];
    }
}

Used in Form Requests for notification create/update. Validation rules defined once, shared across endpoints. Country list from config, age range constrained, activity levels enumerated.

LogsActivity (Audit Trail)

trait LogsActivity
{
    public static function bootLogsActivity(): void
    {
        foreach (['created', 'updated', 'deleted'] as $event) {
            static::$event(function ($model) use ($event) {
                static::logModelEvent($model, $event);
            });
        }
    }

    protected static function logModelEvent($model, $event): void
    {
        CustomActivity::create([
            'log_name' => 'model_changes',
            'description' => $event,
            'subject_type' => get_class($model),
            'subject_id' => $model->id,
            'causer_type' => auth()->check() ? get_class(auth()->user()) : null,
            'causer_id' => auth()->id(),
            'properties' => [
                'old' => $event === 'created' ? [] : $model->getOriginal(),
                'attributes' => $model->getDirty(),
            ],
        ]);
    }
}

Built on top of Spatie's ActivityLog. Records who changed what, when, and the exact before/after values. Only logs dirty attributes - no noise from unchanged fields. Add use LogsActivity to any model and every create/update/delete gets audit-logged automatically.

How They Work Together

HTTP Request arrives
    │
    ├── HandleInertiaRequests: share frontend props
    ├── SetActiveCompanyMiddleware: resolve company context
    │       └── uses BelongsToCompany trait on models
    ├── UpdateLastSessionActivity: record timestamp + device
    ├── SetLocale: detect language
    ├── EnsureEmailIsVerified: gate check
    ├── CheckPinLockMiddleware: uses last_activity from step 3
    ├── CheckAccessMiddleware: uses company from step 2
    ├── CheckSessionExists: validates session in DB
    │
    v
Controller runs
    ├── HasPagination: format pagination data
    ├── Filter auto-discovery: apply query filters
    ├── NotificationDataHandler: prepare notification data
    │
    v
Model operations
    ├── BelongsToCompany: automatic tenant isolation
    ├── HasRolesAndPermissions: permission checks
    └── LogsActivity: audit trail

Middleware handles the request lifecycle. Traits handle the business logic. Each layer independent, each layer tested separately.

Testing

Behavior-driven tests using Pest:

// Middleware: PIN lock
it('locks session after pin timeout', function () {
    $user = User::factory()->withPinCode()->create();
    UserSession::factory()->create([
        'user_id' => $user->id,
        'last_activity' => now()->subMinutes(31),
    ]);

    actingAs($user)->get('/dashboard')
        ->assertRedirect(route('pin.enter'));
});

// Middleware: Access control
it('blocks banned user but allows support tickets', function () {
    $user = User::factory()->blocked()->create();

    actingAs($user)->get('/dashboard')
        ->assertRedirect(route('user.blocked'));

    actingAs($user)->get('/tickets')
        ->assertOk();
});

// Middleware: Session validation
it('rejects invalid session with 401 for API', function () {
    $user = User::factory()->create();

    actingAs($user)->getJson('/api/data')
        ->assertStatus(401)
        ->assertJson(['message' => 'session_expired']);
});

// Trait: Filter auto-discovery
it('filters by country via query param', function () {
    Contragent::factory()->create(['country' => 'DE', 'company_id' => $company->id]);
    Contragent::factory()->create(['country' => 'US', 'company_id' => $company->id]);

    actingAs($user)->get('/contragents/customers?country=DE')
        ->assertInertia(fn ($page) => $page->has('contragents', 1));
});

// Trait: Pagination
it('returns consistent pagination structure', function () {
    Contragent::factory(30)->create(['company_id' => $company->id]);

    actingAs($user)->get('/contragents/customers?page=2')
        ->assertInertia(fn ($page) =>
            $page->has('pagination', fn ($p) =>
                $p->where('current_page', 2)
                   ->where('per_page', 20)
            )
        );
});

No middleware mocking. Real HTTP requests. Assert what users experience. If someone reorders the middleware stack but behavior stays the same - tests pass. If someone removes a middleware - tests catch it.

Design Principles

Middleware order is explicit - documented, tested, justified. Each position depends on what runs before it.
Traits are composable - BelongsToCompany + HasRolesAndPermissions + LogsActivity on any model = full tenant isolation + RBAC + audit trail.
Security is layered - Session validation → PIN lock → access control → permission checks. Multiple barriers, not one big gate.
Behavior over implementation - Tests verify user experience, not internal code paths.
Config over code - Locale mappings, timeout values, sort whitelists - all configurable without touching logic.

LaraFoundry is an open-source Laravel SaaS framework, being built in public and extracted from a production CRM/ERP.

GitHub: github.com/dmitryisaenko/larafoundry
Website: larafoundry.com

laravel #php #saas #middleware #larafoundry

Building a Production Vue Frontend for Multi-Tenant Laravel SaaS with Inertia v2

Dmitry Isaenko — Mon, 13 Apr 2026 12:28:11 +0000

Most Vue + Laravel tutorials stop at "here's how to render a page with Inertia." Real SaaS apps need dynamic layouts per user type, overlay management, pagination that preserves filter state, modals that stack, and all of this without the complexity of a full state management library.

I built a complete frontend module for Kohana.io - a production CRM/ERP - and I'm extracting it into LaraFoundry, an open-source SaaS framework for Laravel.

This post covers the full frontend architecture: layout switching, overlay system, pagination + filters, modal patterns, Inertia wiring, and testing.

The Problem

A multi-tenant SaaS needs more than one layout. In Kohana.io, I needed five:

Layout	When	What it contains
GuestLayout	Not logged in	Landing page, login/register modals
AuthLayout	Regular user	Full app: header, pullout menus, notifications
AdminLayout	Admin user	Admin panel with different navigation
AuthBlockedLayout	Blocked account	Limited access, support tickets only
AuthDeletedLayout	Deleted account	Minimal UI for data requests

Each layout has a completely different component tree. Different headers, different pullout menus, different modal systems. And Inertia's persistent layouts mean they stay mounted across page navigations - you can't just swap a CSS class.

Architecture Overview

HTTP Request
  |
  v
HandleInertiaRequests middleware
  |── visitor_status: 'admin' | 'auth' | 'authBlocked' | 'authDeleted' | 'guest'
  |── layout: { layoutData, authUserData } (lazy-loaded)
  |── flash, translations, ziggy, locale, ui_settings
  |
  v
app.js - createInertiaApp()
  |── import.meta.glob('./pages/**/*.vue')     → code-split pages
  |── page.layout = page.layout || LayoutSwitcher  → default layout
  |── i18n, ZiggyVue, Head, Link               → plugins
  |
  v
LayoutSwitcher.vue
  |── reads visitor_status from Inertia props
  |── renders matching layout component
  |
  v
AuthLayout / AdminLayout / GuestLayout / etc.
  |── pullout menus, overlays, modals
  |── <slot /> → page content

The LayoutSwitcher Pattern

The core of the system is LayoutSwitcher.vue:

<script setup>
import { computed } from 'vue';
import { usePage } from '@inertiajs/vue3';
import AdminLayout from '@/layouts/AdminLayout.vue';
import AuthLayout from '@/layouts/AuthLayout.vue';
import AuthBlockedLayout from '@/layouts/AuthBlockedLayout.vue';
import AuthDeletedLayout from '@/layouts/AuthDeletedLayout.vue';
import GuestLayout from '@/layouts/GuestLayout.vue';

const visitorStatus = computed(() => usePage().props.visitor_status);
</script>

<template>
    <component :is="
        visitorStatus === 'admin' ? AdminLayout
        : visitorStatus === 'auth' ? AuthLayout
        : visitorStatus === 'authBlocked' ? AuthBlockedLayout
        : visitorStatus === 'authDeleted' ? AuthDeletedLayout
        : GuestLayout
    ">
        <slot />
    </component>
</template>

Under 40 lines. The server determines visitor_status via middleware, and the frontend renders the matching layout. No auth checks in Vue. No route guards. No conditional rendering scattered across components.

The assignment happens in app.js:

resolve: async (name) => {
    const pages = import.meta.glob('./pages/**/*.vue');
    let module = await pages[`./pages/${name}.vue`]();
    let page = module.default;
    page.layout = page.layout || LayoutSwitcher;
    return page;
}

Every page automatically gets LayoutSwitcher unless it explicitly defines its own layout. Pages don't import layouts. Pages don't know which layout wraps them.

The Overlay System

A production SaaS layout isn't just a header and a sidebar. The authenticated layout in Kohana.io has 7 pullout panels:

Mobile menu (slides from left)
Right profile menu (slides from right)
Notifications panel
Language selector
Company switcher
Contragent filter drawer
Product filter drawer

And they stack. Opening the language selector while the mobile menu is open creates a double overlay - two backdrop layers, independently dismissable.

State Management (No Library)

// AuthLayout.vue - all overlay state
const viewPulloutMobilemenu = ref(false);
const viewPulloutMenuRight = ref(false);
const viewPulloutNotifications = ref(false);
const viewPulloutMenuChangeLanguage = ref(false);
const viewPulloutMenuChangeCompany = ref(false);
const viewPulloutContragentFilter = ref(false);
const viewPulloutProductFilter = ref(false);
const viewOverlay = ref(false);
const viewDoubleOverlay = ref(false);
const viewModalWrapper = ref(false);

Plain reactive refs. No Vuex store. No Pinia. No event bus.

Overlay Logic

Opening any pullout → shows single overlay + disables body scroll via document.body.classList.add('non-overflow')
Opening a second panel on top → shows double overlay
ESC key → dismisses top layer first using onKeyStroke from @vueuse/core
Clicking backdrop → closes everything
CSS transitions: 0.3s for single overlay, 0.1s for double (feels snappy)

Child Component Communication

Pages deep in the component tree trigger layout overlays via provide/inject:

// AuthLayout.vue (parent)
provide('showPulloutContragentFilter', showPulloutContragentFilter);
provide('showViewContragentModal', showViewContragentModal);

// ContragentsList.vue (child page)
const showFilter = inject('showPulloutContragentFilter');

The page calls showFilter(). The layout handles z-indexes, backdrops, body scroll, and transition timing. Clean separation.

Transition Animations

.overlay-enter-active, .overlay-leave-active {
    transition: opacity 0.3s ease;
}
.overlay-enter-from, .overlay-leave-to {
    opacity: 0;
}

/* Pullout menus use GPU-accelerated transforms */
.pullout-menu__left {
    will-change: transform;
    transform: translateZ(0);
    backface-visibility: hidden;
    transition: transform 0.3s ease;
}

CSS-only animations. GPU-accelerated for mobile. No JavaScript animation libraries.

Pagination + Filter Architecture

Backend: HasPagination Trait

Every controller that paginates uses the same trait:

trait HasPagination
{
    protected function getPaginationData($paginator): array
    {
        return [
            'current_page' => $paginator->currentPage(),
            'last_page'    => $paginator->lastPage(),
            'per_page'     => $paginator->perPage(),
            'total'        => $paginator->total(),
            'from'         => $paginator->firstItem(),
            'to'           => $paginator->lastItem(),
        ];
    }
}

Controller usage:

$paginated = $query->filter($filter)->paginate($perPage)->withQueryString();

return Inertia::render('warehouse/Products', [
    'products'   => ProductResource::collection($paginated),
    'pagination' => $this->getPaginationData($paginated),
]);

.withQueryString() is critical - it preserves all filter parameters when generating pagination links.

Frontend: PagePaginator Component

The paginator component lives in the layout, not in pages. AppMainContentLayout.vue auto-renders it when pagination data exists:

const isPaginationPresent = computed(() => {
    const total = page.props.pagination?.total ?? 0;
    const perPage = page.props.pagination?.per_page ?? 0;
    return total > perPage;
});

The component rebuilds pagination links while preserving all current query parameters:

const queryString = computed(() => {
    const url = new URL(window.location.href);
    url.searchParams.delete('page');
    const qs = url.searchParams.toString();
    return qs ? `&${qs}` : '';
});

// Smart page range: max 7 buttons + ellipsis
const pages = computed(() => {
    const total = p.value.last_page;
    const current = p.value.current_page;
    if (total <= 7) return Array.from({ length: total }, (_, i) => i + 1);
    if (current <= 4) return [1, 2, 3, 4, 5, '...', total];
    if (current >= total - 3) return [1, '...', total-4, total-3, total-2, total-1, total];
    return [1, '...', current-1, current, current+1, '...', total];
});

Each page button uses Inertia's <Link> for SPA navigation:

<Link :href="`?page=${item}&${queryString}`">{{ item }}</Link>

Country filter active? Preserved. Sort direction? Preserved. Search query? Preserved. No state management needed.

Filter Auto-Discovery Pattern

The filter system uses method auto-discovery:

abstract class Filter
{
    public function apply(Builder $builder)
    {
        $this->builder = $builder;
        foreach ($this->request->all() as $name => $value) {
            if (method_exists($this, $name)) {
                call_user_func_array([$this, $name], [$value]);
            }
        }
        return $this->builder;
    }
}

Request parameter country=DE → calls $filter->country('DE'). No routing config. No switch statements. Method exists = filter applied.

Concrete filter example:

class ContragentsFilter extends Filter
{
    public function search_string($value = null)
    {
        $words = preg_split('/\s+/', trim($value));
        return $this->builder->where(function ($query) use ($words) {
            foreach ($words as $word) {
                $query->whereRaw('LOWER(name) LIKE ?', ['%'.mb_strtolower($word).'%']);
            }
        });
    }

    public function sort_by($value = null)
    {
        $allowed = ['name', 'country', 'balance', 'created_at'];
        if (in_array($value, $allowed)) {
            $direction = $this->request->input('sort_direction', 'asc');
            return $this->builder->orderBy($value, $direction);
        }
        return $this->builder->orderBy('name', 'asc');
    }
}

Whitelisted sort columns prevent SQL injection. Word-by-word search matching. Alphabetical navigation via starts_with() method. Quick filter presets for products (min_stock, has_reserved).

Frontend Filter Integration

// Inertia router navigation with state preservation
const performSearch = () => {
    const params = {};
    if (filters.value.search) params.search_string = filters.value.search;
    if (filters.value.country) params.country = filters.value.country;
    // ... all filter params

    router.get(route(routeName.value), params, {
        preserveState: true,    // Component state survives
        preserveScroll: true,   // Scroll position maintained
        replace: true,          // Single history entry
    });
};

preserveState: true is the key. Component reactive state persists across Inertia navigations. No need to store filters in a Vuex store or local storage.

Modal & Popup System

LaraFoundry uses a hybrid approach: custom modals for complex interactions, SweetAlert2 for confirmations.

Custom Form Modal (Inertia useForm)

<script setup>
import { useForm } from '@inertiajs/vue3';

const form = useForm({ email: '', role_id: '' });

const submit = () => {
    form.post(route('my_company.employees.invite'), {
        preserveScroll: true,
        onSuccess: () => emit('invited'),
    });
};
</script>

<template>
    <Transition name="modal">
        <div class="modal-overlay" @click.self="emit('close')">
            <div class="modal">
                <form @submit.prevent="submit">
                    <InputField v-model="form.email" :class="{ 'input--error': form.errors.email }" />
                    <span v-if="form.errors.email">{{ form.errors.email }}</span>
                    <button type="submit" :disabled="form.processing">
                        {{ form.processing ? t('Sending...') : t('Send') }}
                    </button>
                </form>
            </div>
        </div>
    </Transition>
</template>

form.processing disables the submit button. form.errors shows server-side validation. onSuccess closes the modal. Three features, zero custom code.

Async Data-Loading Modal

const loading = ref(false);
const contragent = ref(null);

watch(() => props.visible, (newVal) => {
    if (newVal && props.contragentUuid) {
        fetchContragentData();
    }
});

const fetchContragentData = async () => {
    loading.value = true;
    try {
        const response = await axios.get(route('contragents.view_data', props.contragentUuid));
        contragent.value = response.data.contragent;
    } catch (err) {
        error.value = t('Failed to load data');
    } finally {
        loading.value = false;
    }
};

Data fetched only when modal becomes visible. Loading spinner. Error state. Tabs for different data views. ESC key to close.

SweetAlert2 for Confirmations

const result = await Swal.fire({
    title: t('Remove Employee?'),
    text: t('This action will immediately remove the employee.'),
    icon: 'error',
    showCancelButton: true,
    confirmButtonColor: '#ef4444',
});

if (result.isConfirmed) {
    router.delete(route('my_company.employees.remove', employee.id));
}

One await. No custom component. Accessible. Styled.

Layout-Level Modal Orchestration

Generic modals are managed in the layout via provide/inject:

// AuthLayout.vue
const modal = reactive({
    view: false,
    title: t('Confirm the action'),
    content: null,
    targetUrl: null,
    modalType: 'confirmable',
});

provide('showViewContragentModal', showViewContragentModal);

Pages inject trigger functions. The layout handles z-indexes, overlay stacking, and transition timing.

Full Inertia Wiring

Blade Template

<head>
    <title inertia>{{ config('app.name') }}</title>
    @vite(['resources/js/app.js', 'resources/css/app.css'])
    @inertiaHead
    @routes
</head>
<body>
    @inertia
</body>

@routes dumps Ziggy routes. @inertiaHead enables dynamic head management from Vue. @inertia mounts the SPA.

app.js Entry Point

createInertiaApp({
    title: (title) => `${title} - ${appName}`,

    resolve: async (name) => {
        const pages = import.meta.glob('./pages/**/*.vue');
        let module = await pages[`./pages/${name}.vue`]();
        let page = module.default;
        page.layout = page.layout || LayoutSwitcher;
        return page;
    },

    setup({ el, App, props, plugin }) {
        const i18n = createI18n({
            legacy: false,
            locale: pageProps.locale || 'en',
            messages: { [locale]: translations },
        });

        createApp({ render: () => h(App, props) })
            .use(plugin)
            .use(i18n)
            .use(ZiggyVue)
            .component('Head', Head)
            .component('Link', Link)
            .mount(el);

        // Global translation function
        app.config.globalProperties.t = (...args) => i18n.global.t(...args);
        globalThis.t = (...args) => i18n.global.t(...args);
    },

    progress: { delay: 0, color: '#3b82f6', showSpinner: false },
});

Key decisions:

import.meta.glob - Vite code-splits every page. Only the current page is loaded.
Global t() function - registered on both globalProperties (Options API) and globalThis (Composition API). No imports needed anywhere.
Progress bar delay: 0 - appears immediately on navigation. Users see instant feedback.

Shared Props (Middleware)

public function share(Request $request): array
{
    return [
        'layout'          => fn () => $layout->getLayout(),       // lazy
        'flash'           => fn () => session messages,            // lazy
        'ziggy'           => [...(new Ziggy)->toArray()],
        'locale'          => fn () => App::getLocale(),
        'translations'    => fn () => merged translations,         // lazy
        'visitor_status'  => visitor status closure,
        'ui_settings'     => fn () => user UI preferences,         // lazy
    ];
}

Everything wrapped in closures for lazy evaluation. Layout data is only computed when the frontend reads page.props.layout.

Vite Aliases

resolve: {
    alias: {
        '@': path.resolve(__dirname, './resources/js'),
        '@css': path.resolve(__dirname, './resources/css'),
        '@assets': path.resolve(__dirname, './public/assets'),
        'ziggy-js': resolve(__dirname, 'vendor/tightenco/ziggy'),
    },
}

@/components/PagePaginator.vue instead of relative path chains.

Testing

Frontend behavior is tested through Pest feature tests that assert on Inertia props:

it('serves auth layout for authenticated users', function () {
    actingAs(User::factory()->create())
        ->get('/dashboard')
        ->assertInertia(fn ($page) =>
            $page->where('visitor_status', 'auth')
        );
});

it('returns pagination data with filter state', function () {
    Product::factory(30)->create(['company_id' => $company->id]);

    actingAs($user)
        ->get('/warehouse/products?page=2')
        ->assertInertia(fn ($page) =>
            $page->has('pagination', fn ($p) =>
                $p->where('current_page', 2)
                    ->where('per_page', 20)
                    ->where('total', 30)
            )
        );
});

it('shares flash messages via Inertia', function () {
    actingAs($user)->post('/contragents', $validData);

    actingAs($user)
        ->get('/contragents/customers')
        ->assertInertia(fn ($page) => $page->has('flash.info'));
});

it('returns contragent data for view modal', function () {
    $contragent = Contragent::factory()->create();

    actingAs($user)
        ->get(route('contragents.view_data', $contragent->uuid))
        ->assertJson(['contragent' => ['name' => $contragent->name]]);
});

The pattern: test what the server sends. If Inertia props are correct, Vue renders correctly. This covers layout switching, pagination, filters, flash messages, and modal data.

For complex interactive components (filter watchers, URL manipulation), unit tests with Vitest would supplement this. But for the majority of frontend behavior, Pest feature tests are sufficient.

Directory Structure

resources/js/
├── app.js                          # Entry point, plugins, LayoutSwitcher default
├── layouts/
│   ├── LayoutSwitcher.vue          # Dynamic layout router
│   ├── AuthLayout.vue              # Authenticated users (7 pullout menus)
│   ├── AdminLayout.vue             # Admin panel
│   ├── GuestLayout.vue             # Public + login/register modals
│   ├── AuthBlockedLayout.vue       # Blocked users
│   ├── AuthDeletedLayout.vue       # Deleted accounts
│   └── app/                        # Sub-layout components
│       ├── AppHeaderDesktopLayout.vue
│       ├── AppMainContentLayout.vue    # Wraps content + auto-renders pagination
│       ├── AppModalLayout.vue
│       ├── AppFooterLayout.vue
│       ├── AppPulloutMobilemenuLayout.vue
│       ├── AppPulloutMenuRightLayout.vue
│       ├── AppPulloutMenuNotificationsLayout.vue
│       └── ... (7 more pullout components)
├── pages/                          # Inertia pages (auto-resolved)
├── components/                     # Reusable components
│   ├── PagePaginator.vue
│   ├── contragents/ViewContragentModal.vue
│   ├── SendTestEmailModal.vue
│   └── ui/                         # Form inputs, filters, etc.
├── composables/                    # Vue composition functions
└── store/
    └── unreadCountStore.js         # Simple ref-based store

What's Included

Feature	Implementation
Layout switching	LayoutSwitcher + visitor_status prop (5 layouts)
Overlay system	7 pullout panels, double-layer stacking, ESC dismissal
Pagination	HasPagination trait + PagePaginator component (auto-render)
Filters	Auto-discovery pattern, alphabetical nav, quick presets
Modals	Custom (useForm, async axios) + SweetAlert2 (confirmations)
State management	Reactive refs + provide/inject (no Vuex/Pinia)
i18n	vue-i18n v11 with Laravel translations, global t()
Routing	Ziggy named routes in Vue templates
Code splitting	Vite import.meta.glob per page
Testing	Pest feature tests asserting Inertia props

Key Takeaway

Push complexity to the backend. Vue renders pre-computed data.

No permission checks in Vue components. No auth guards. No client-side menu filtering. No state calculations. The server sends exactly what each user type needs. The frontend renders it.

The LayoutSwitcher pattern, the overlay system, the pagination auto-rendering, the filter auto-discovery - they all follow the same principle. The backend is the source of truth. The frontend is a rendering engine.

LaraFoundry is an open-source Laravel SaaS framework, being built in public and extracted from a production CRM/ERP.

GitHub: github.com/dmitryisaenko/larafoundry
Website: larafoundry.com
laravel #vue #inertia #saas #larafoundry

DEV Community: Dmitry Isaenko

I extracted an audit log into my SaaS core, and the review caught it logging the wrong thing

I did not invent an audit log

The one decision worth explaining: this is not a tenant feature

The context wrapper

Then the review found it logging the wrong thing

A quieter one in the geo path

The model-audit trait, fixed

What it deliberately is not

Tests, and the close

I wrote my own RBAC instead of reaching for Spatie, and the review caught a privilege-escalation hole

I didn't use Spatie

The shape of it

The hook that finally fired

Then the review found the hole

And a second one, hiding in the flow

What it deliberately is not

Tests, and the close

Multi-Tenancy from a Live CRM, and the Two Holes the Second Review Found

What multi-tenancy actually means here

The decision that mattered: fail-closed

The resolver, and why it's behind an interface

The user side is a trait, not a base class

Invitations, and the email-spoof guard I kept

Now the two holes

Hole 1: company takeover through the invite flow

Hole 2: privilege resurrection back to owner

Why the second pass caught what the first didn't

The tests

Where this leaves the core

I Rebuilt My Laravel Auth on Top of Fortify (and Two Bugs the Integration Caught)

The decision that mattered: don't hand-roll auth

What the core actually adds around Fortify

The OAuth guard worth talking about

Now the two bugs

Bug 1: session tracking on the wrong event

Bug 2: views => false is a trap with Inertia

The takeaway

Extracting a Production Laravel App Into a Reusable Core Package (and the Bugs Pest Caught Doing It)

Why extract instead of rewrite

What's in v0.1.0

Locale detection: the rewrite that paid for itself

Query filters: a reflection trick with a sharp edge

The frontend: making Inertia + Vue survive inside vendor/

The review gate, and a bug it caught

Testing

What I'd tell myself before starting

Honest scope

laravel #vue #php #opensource #larafoundry

Building a Multi-Currency Payment System with Promo Codes for a Laravel SaaS

Table of Contents

Architecture Overview

Database Schema

company_payments

promo_codes

Promo Code System

Validation Chain

Discount Calculation

Status Detection

Personal Promo Codes

Admin Dashboard & Statistics

Revenue Totals

Latest Payment Per Company

AdminPaymentResource

Promo Code CRUD

Validation Rules

Toggle

User Search

Filtering & Multi-Currency

AdminPaymentsFilter

AdminPromoCodesFilter

Frontend: Payments & Promo Codes

Payments Table (PaymentsTable.vue)

Promo Codes (PromoCodesTab.vue)

Create/Edit Promo Code

Events & Notifications

Testing

PaymentControllerTest (Feature)

PromoCodeControllerTest (Feature)

PromoCodeTest (Unit)

Bug 2: `views => false` is a trap with Inertia

The frontend: making Inertia + Vue survive inside `vendor/`