Forem: Dmitry Isaenko

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

Building a Dynamic, Permission-Aware Navigation System for Multi-Tenant Laravel SaaS

Dmitry Isaenko — Mon, 06 Apr 2026 09:02:03 +0000

Most SaaS navigation tutorials show you how to render a <nav> with 5 links. Real multi-tenant apps need something very different: menus that change based on who's logged in, what company they're in, and what permissions they have.

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

This post covers the full system: backend menu building, permission filtering, sub-menu routing, the First Allowed Route pattern, frontend rendering (desktop + mobile), and testing.

The Problem

In a multi-tenant SaaS with role-based access, navigation has to solve several problems at once:

Admins see a completely different menu than regular users (admin panel vs business modules)
Company owners see all modules (Orders, Warehouse, Accounting, Production...)
Employees see only modules they have permissions for
Each module has sub-pages with potentially different permission requirements
When a user switches companies, the menu must recalculate
The same data must render on desktop (two-tier header) and mobile (hamburger with collapsible sections)
Users should be able to set a default landing page
There should be zero 403 pages - if a user hits a forbidden page, redirect them gracefully

Architecture Overview

Request
  |
  v
LayoutController::getLayout()
  |
  v
LayoutDataService
  |
  ├── getNav('upLevel')          → Desktop top-level tabs
  ├── getNav('bottomLevel')      → Desktop sub-page tabs
  ├── getNav('myCompanySidebar') → Company management sidebar
  ├── getNav('mobile')           → Full mobile tree
  ├── getFirstAllowedRouteName() → Smart redirect target
  |
  └── Each method calls:
        getNavItems($items, $level)
          └── checkUserAndCompanyPolicy($policyName)
                ├── Admin → always allowed
                ├── 'public' → any authenticated user
                └── else → $user->hasPermissionTo($policy, $company)
  |
  v
HandleInertiaRequests (middleware)
  |── Shares layout data as Inertia prop (lazy-loaded)
  |
  v
Vue frontend
  ├── Desktop: two-tier header
  └── Mobile: hamburger pullout menu

Backend: LayoutDataService

The entire navigation system lives in one service class - LayoutDataService. It handles four distinct navigation contexts from a single source of truth.

Menu Item Structure

Every menu item follows the same shape:

[
    'linkName'        => __('Orders'),              // Translated label
    'linkUrl'         => route('orders.incoming'),   // Target URL
    'policyName'      => 'orders.view',             // Permission slug
    'routeName'       => 'orders',                   // Route name for matching
    'linkIconSvg'     => 'icon_orders.svg',         // Icon file
    'isLinkActive'    => Route::currentRouteNamed('orders.*'),
    'companyItem'     => true,                       // Company-specific item
]

Permission Filtering

The core of the system is checkUserAndCompanyPolicy():

private function checkUserAndCompanyPolicy($policyName): bool
{
    // Admins see everything
    if (self::isAdmin()) return true;

    // Empty policy = blocked (security measure)
    if (empty($policyName)) return false;

    // Public items (notifications, support, profile)
    if ($policyName === 'public') return auth()->check();

    // Company-specific permission check
    $user = auth()->user();
    $company = $user->activeCompany;

    if ($user->isOwnerOf($company)) return true;

    return $user->hasPermissionTo($policyName, $company);
}

This one method handles all three user types. No separate admin menu builder. No role-checking conditionals scattered across the codebase.

Three User Types, Three Menus

User type	Menu	Modules
Admin	Admin panel	Users, Companies, Payments, Notifications, Support
Owner	Business modules	All 8 modules + company management sidebar
Employee	Filtered business modules	Only modules with explicit permissions

The key design decision: owners always see all modules, even if their subscription expired. Subscription blocking is handled at the page level with a separate overlay, not by hiding navigation. This way users know what they're paying for.

Sub-Menu Routing

Clicking "Orders" doesn't go to /orders. It goes to the user's default sub-page for that module.

// GetDefaultBottomLevelRouteNameAction
'orders'       => 'orders.incoming',
'warehouse'    => 'warehouse.products',
'accounting'   => 'accounting.funds_movement',
'contragents'  => 'contragents.customers',
'production'   => 'production.main_workshop',

Sub-routes also have their own permissions:

// Warehouse sub-routes
[
    ['routeName' => 'warehouse.report',      'policyName' => 'warehouse.view'],
    ['routeName' => 'warehouse.products',    'policyName' => 'warehouse.view'],
    ['routeName' => 'warehouse.consumables', 'policyName' => 'warehouse.view'],
    ['routeName' => 'warehouse.settings',    'policyName' => 'warehouse.manageCategories'],
]

An employee with warehouse.view but without warehouse.manageCategories will see Products, Consumables, and Report tabs, but not Settings.

The First Allowed Route (FAR) Pattern

This pattern eliminates 403 pages entirely. I covered it in detail in my multi-tenancy series, but here's the core:

public function getFirstAllowedRouteName(): string
{
    if (self::isAdmin()) return 'admin.dashboard.index';

    if (!$this->authUserData->hasUserCompanyOrRole()) {
        return 'notifications.index';
    }

    // Check user's saved default route
    $saved = auth()->user()->getDefaultRouteForActiveCompany();
    if ($saved && $this->isBottomLevelRouteAccessible($saved)) {
        return $saved;
    }

    // Walk the menu, find first accessible page
    foreach ($this->getNavUpLevelItemsArray() as $item) {
        if (!empty($item['unvisibly'])) continue;

        if ($this->checkUserAndCompanyPolicy($item['policyName'])) {
            $route = $this->getFirstAllowedBottomLevelRoute($item['routeName']);
            return $route ?? $item['routeName'];
        }
    }

    return 'notifications.index';
}

This handles four critical scenarios:

After login - where should the user land?
After 403 - redirect instead of showing error page
After company switch - permissions may differ
Home link - always points to an accessible page

The 403 exception handler ties it all together:

// bootstrap/app.php
$exceptions->renderable(function (AccessDeniedHttpException $e, Request $request) {
    $layoutService = app(LayoutDataService::class);
    return redirect()
        ->route($layoutService->getFirstAllowedRouteName())
        ->with('message-disappear-error', __('You do not have permission to access this page'));
});

User-Configurable Default Page

Users can set their preferred landing page in profile settings. It's stored per company in the company_user pivot table. If permissions change and that page becomes inaccessible, the system clears the default automatically and shows a warning.

Data Flow to Frontend

LayoutController::getLayout() returns everything the frontend needs:

[
    'layoutData' => [
        'homeRoute'                  => $this->getFirstAllowedRoute(),
        'navDesktopUpLevel'          => $this->getNav('upLevel'),
        'navDesktopBottomLevel'      => $this->getNav('bottomLevel'),
        'navDesktopMycompanySidebar' => $this->getNav('myCompanySidebar'),
        'navMobile'                  => $this->getNav('mobile'),
        'defaultRoute'               => $savedDefaultRoute,
        'breadcrumbsString'          => $breadcrumbs,
    ],
    'authUserData' => [
        'currentCompanyName' => $company->name,
        'currentRole'        => $role->slug,
        'isAuthUserOwnerOfCurrentCompany' => $isOwner,
        // ... 15+ more fields
    ]
]

This is shared via HandleInertiaRequests middleware as a lazy-loaded prop. One request, all navigation data included. Zero extra API calls.

Frontend: Desktop Navigation

The desktop layout uses a two-tier header:

<template>
    <!-- Top: module tabs -->
    <nav class="header-nav">
        <Link v-for="item in layoutData.navDesktopUpLevel"
              :key="item.routeName"
              :href="item.linkUrl"
              :class="{ 'header-nav__link--active': item.linkActive }">
            {{ item.linkName }}
        </Link>
    </nav>

    <!-- Bottom: sub-pages for current module -->
    <nav class="header-nav-bottom">
        <Link v-for="item in layoutData.navDesktopBottomLevel"
              :key="item.routeName"
              :href="item.linkUrl"
              :class="{ 'header-nav__link--active': item.linkActive }">
            {{ item.linkName }}
        </Link>
    </nav>
</template>

Active states are computed server-side via Route::currentRouteNamed(). The frontend doesn't need to match URLs or check permissions - it's all in the data.

Frontend: Mobile Navigation

Mobile gets a completely different data structure. navMobile is a hierarchical tree:

[
    {
        linkName: "Orders",
        linkUrl: "/orders/incoming",
        linkActive: true,
        linkIconUrl: "/icons/icon_orders.svg",
        child: [
            { linkName: "Report", linkUrl: "/orders/report", linkActive: false },
            { linkName: "Incoming", linkUrl: "/orders/incoming", linkActive: true },
            { linkName: "Outgoing", linkUrl: "/orders/outgoing", linkActive: false },
        ]
    }
]

The mobile menu is a slide-out pullout from the left, built with CSS transitions and GPU acceleration:

.pullout-menu__left {
    will-change: transform;
    transform: translateZ(0);
    backface-visibility: hidden;
    transition: transform 0.3s ease;
}

It has a settings mode toggle where users can select their default landing page via radio buttons. This fires a PUT request to the backend.

Responsive strategy: Mobile-first with Custom SCSS breakpoints:

<div class="lg:hidden"><!-- Mobile menu --></div>
<div class="hidden lg:flex"><!-- Desktop menu --></div>

Right-Side Pullout

A separate right pullout handles user profile, company info, language selection, and quick actions. On mobile it slides from the right. On ultra-wide screens (2xl+) it drops from the top.

State Management

No Vuex. No Pinia. Navigation state is managed with reactive refs in the layout component:

const viewPulloutMobilemenu = ref(false);
const viewPulloutMenuRight = ref(false);
const viewOverlay = ref(false);

Child components communicate via emits. Overlays use CSS transitions with JS cleanup timeouts.

Testing

Navigation is authorization. If the menu is wrong, security is wrong.

it('shows all modules to company owner', function () {
    $owner = User::factory()->owner()->create();

    actingAs($owner)
        ->get('/dashboard')
        ->assertInertia(fn ($page) =>
            $page->has('layout.layoutData.navDesktopUpLevel', 8)
        );
});

it('hides modules without permission from employee', function () {
    $employee = User::factory()->employee()->create();
    grantPermission($employee, 'orders.view');

    actingAs($employee)
        ->get('/orders/incoming')
        ->assertInertia(fn ($page) =>
            $page->where('layout.layoutData.navDesktopUpLevel', fn ($nav) =>
                collect($nav)->pluck('routeName')->contains('orders')
                && !collect($nav)->pluck('routeName')->contains('warehouse')
            )
        );
});

it('redirects to first allowed route when default is revoked', function () {
    $employee = User::factory()->employee()->create();
    $employee->setDefaultRoute('warehouse.products');
    revokePermission($employee, 'warehouse.view');

    actingAs($employee)
        ->get('/')
        ->assertRedirect(route('orders.incoming'));
});

Test coverage includes:

Admin menu isolation
Owner sees all 8 modules
Employee sees only permitted modules
Sub-level permission filtering (warehouse.view vs warehouse.manageCategories)
Default route save/clear/fallback
Company switch recalculation
Mobile menu tree consistency
Hidden items (notifications, support) remain accessible via URL

What's Included

Feature	Details
Menu building	Dynamic per-request via LayoutDataService
User types	Admin, Owner, Employee - distinct menus
Permissions	Module-level + sub-page-level filtering
FAR pattern	Zero 403 pages, smart redirects
Default pages	User-configurable per company
Desktop	Two-tier header (modules + sub-pages)
Mobile	Hamburger with collapsible parent/child
Transitions	GPU-accelerated CSS (will-change, translateZ)
i18n	All labels translated via __()
Testing	Pest tests for all user types and edge cases

Key Takeaway

Push complexity to the backend. The frontend should render data, not compute it. LaraFoundry's Vue components don't check permissions, don't calculate active states, don't filter menu items. They receive clean, pre-filtered arrays and render them. That's it.

One service class. One source of truth. The menu, the permissions, and the routing all share the same data. Change a permission - the menu updates. Add a module - add an entry to the items array. No config files to sync. No database tables to maintain.

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

Building a Production-Grade Multilanguage System for Laravel SaaS (with Inertia + Vue)

Dmitry Isaenko — Mon, 30 Mar 2026 10:41:29 +0000

Most Laravel tutorials on i18n stop at "use __() helper and create translation files." That's maybe 10% of what a real SaaS application needs. What about automatic language detection? What about passing 1700+ translation strings to a Vue frontend without extra API calls? What about translating user-generated content?

I built all of this for Kohana.io - a production CRM/ERP system - and I'm now extracting it into LaraFoundry, an open-source SaaS framework for Laravel.

This post covers the complete Multilanguage module: backend, frontend, translation APIs, and testing.

The Problem

Every SaaS boilerplate handles i18n the same way: "We support it. Here's a __() function. Good luck."

But in production you need answers to:

How do you detect a user's preferred language before they've even signed up?
Where do you persist that preference across sessions, devices, and auth states?
How do you efficiently pass translations to a JavaScript frontend?
What about translating actual user content, not just UI labels?

Architecture Overview

Request
  |
  v
SetLocale Middleware
  |-- Check user.locale (DB)
  |-- Check session
  |-- Check browser Accept-Language
  |-- Check IP geolocation (ip-api.com)
  |-- Fall back to default 'en'
  |
  v
app()->setLocale($locale)
  |
  v
HandleInertiaRequests
  |-- Load lang/{locale}.json
  |-- Load lang/{locale}/*.php
  |-- Pass as Inertia shared props
  |
  v
Vue + vue-i18n
  |-- Global t() function
  |-- Language switcher component

Backend: The Locale Detection Chain

The core of the system is the SetLocale middleware. It runs on every request and uses a 5-step fallback chain.

For Authenticated Users

// app/Http/Middleware/SetLocale.php

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

    if (auth()->check()) {
        // Step 1: User's saved preference
        $locale = auth()->user()->locale;

        // Step 2: Session
        if (!$locale) {
            $locale = session('locale');
        }

        // Step 3: Browser Accept-Language
        if (!$locale) {
            $locale = $this->detectFromBrowser($request);
        }

        // Step 4: IP Geolocation
        if (!$locale) {
            $locale = $this->detectFromIp($request->ip());
        }

        // Step 5: Default
        $locale = $locale ?: config('app.locale');

        // Persist
        auth()->user()->update(['locale' => $locale]);
        session(['locale' => $locale]);
    }

    app()->setLocale($locale);
    return $next($request);
}

For Guest Users

Guests follow a similar chain but persist to a cookie instead of the database:

Check locale cookie (set for 10 years after first detection)
Session
Browser language
IP geolocation
Default

The IP geolocation calls ip-api.com to detect the visitor's country, then maps it via config:

// config/app.php
'country_locale_map' => [
    'US' => 'en',
    'GB' => 'en',
    'UA' => 'uk',
    'RU' => 'ru',
    'PL' => 'pl',
    'DE' => 'de',
],

'browser_locale_map' => [
    'en' => 'en',
    'uk' => 'uk',
    'ru' => 'ru',
],

Language Switching

Manual language switching is a simple controller:

// app/Http/Controllers/LanguageController.php

public function languageSwitch($locale = 'en')
{
    if (array_key_exists($locale, config('app.available_languages'))) {
        app()->setLocale($locale);
        Session::put('locale', $locale);

        if (auth()->check()) {
            auth()->user()->update(['locale' => $locale]);
        }

        Cookie::queue('locale', $locale, 525600); // 1 year
    }

    return redirect()->back();
}

Exposed via a single route:

Route::get('/language_switch/{locale?}', [LanguageController::class, 'languageSwitch'])
    ->name('language_switch');

Translation Files Structure

LaraFoundry uses two formats:

JSON files for UI strings (the bulk of translations):

lang/
  en.json    -> {} (empty - English keys are the strings)
  uk.json    -> 1700+ key-value pairs
  pl.json    -> Polish translations
  de.json    -> German translations

PHP array files for framework-specific strings:

lang/
  en/
    auth.php
    validation.php
    pagination.php
    passwords.php
  uk/
    auth.php
    validation.php
    ...

The empty en.json is intentional. English strings serve as their own keys. t('Dashboard') returns 'Dashboard' for English users with no translation file needed. This means adding a new string to the app requires zero changes to translation files for the default language.

Frontend: Laravel to Vue via Inertia

This is where it gets interesting. No extra API calls, no lazy loading of translations - they travel with every Inertia response.

Sharing Translations via Inertia Props

// app/Http/Middleware/HandleInertiaRequests.php

public function share(Request $request): array
{
    return [
        // ...
        'locale' => fn () => App::getLocale(),
        'translations' => function () {
            $locale = App::getLocale();
            $data = [];

            // Load JSON translations
            $jsonPath = base_path("lang/{$locale}.json");
            if (File::exists($jsonPath)) {
                $data = array_merge($data,
                    json_decode(File::get($jsonPath), true) ?? []
                );
            }

            // Load PHP array translations
            $dir = base_path("lang/{$locale}");
            if (File::exists($dir)) {
                foreach (File::files($dir) as $file) {
                    $name = pathinfo($file, PATHINFO_FILENAME);
                    $data[$name] = Lang::get($name);
                }
            }

            return $data;
        },
    ];
}

Vue i18n Setup

In app.js, vue-i18n is initialized with the translations from Inertia props:

import { createI18n } from 'vue-i18n';

const locale = pageProps.locale || 'en';
const translations = pageProps.translations || {};

const i18n = createI18n({
    legacy: false,
    locale,
    fallbackLocale: 'en',
    messages: {
        [locale]: translations,
    },
});

const app = createApp({ render: () => h(App, props) })
    .use(plugin)
    .use(i18n)
    .use(ZiggyVue);

// Global t() - no imports needed anywhere
app.config.globalProperties.t = (...args) => i18n.global.t(...args);
globalThis.t = (...args) => i18n.global.t(...args);

Using Translations in Components

<template>
    <h1>{{ t('Dashboard') }}</h1>
    <p>{{ t('Welcome back') }}</p>
    <button>{{ t('Save changes') }}</button>
</template>

No imports. No useI18n(). No composables. Just t() and it works everywhere.

Language Switcher Component

The language switcher gets its data from Inertia layout props:

<template>
    <div v-for="lang in availableLanguages" :key="lang.locale">
        <img :src="lang.flagUrl" alt="" />
        <div v-if="lang.locale === currentLocale" class="active-lang">
            {{ lang.title }}
        </div>
        <a v-else :href="lang.routeUrl">
            {{ lang.title }}
        </a>
    </div>
</template>

The backend provides everything the component needs:

// app/Services/LayoutDataService.php

public function getAvailableLanguages()
{
    return collect(config('app.available_languages'))
        ->map(fn ($title, $locale) => [
            'title' => $title,
            'shortTitle' => $locale,
            'flagUrl' => url("/icons/flag-{$locale}-icon.png"),
            'locale' => $locale,
            'routeUrl' => route('language_switch', ['locale' => $locale]),
        ])->toArray();
}

Bonus: Pluggable Translation API

Beyond UI translations, LaraFoundry includes a translation service for user-generated content. Two providers out of the box:

// app/Contracts/Translator.php

interface Translator
{
    public function translateText(string $text, string $from, array $to): array;
    public function getSupportedLanguages(): array;
    public function isLanguageSupported(string $code): bool;
    public function getUsageInfo(): ?array;
}

Implementations: DeepLTranslator and GoogleTranslator. Swap via environment variable:

'translator_default' => env('TRANSLATION_SERVICE', 'deepl'),

REST endpoints included:

POST /translate        - translate text
GET  /translate/usage  - check API quota
GET  /translate/languages - list supported languages

Testing

The multilanguage module has comprehensive test coverage using Pest:

it('detects locale from user profile', function () {
    $user = User::factory()->create(['locale' => 'uk']);

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

    expect(app()->getLocale())->toBe('uk');
});

it('switches language and persists to database', function () {
    $user = User::factory()->create(['locale' => 'en']);

    actingAs($user)
        ->get('/language_switch/uk')
        ->assertRedirect();

    expect($user->fresh()->locale)->toBe('uk');
});

it('ignores unsupported locale', function () {
    actingAs($user)
        ->get('/language_switch/xx')
        ->assertRedirect();

    expect($user->fresh()->locale)->toBe('en');
});

Test coverage includes:

All 5 detection fallback levels for both auth and guest
Language switching with DB, session, and cookie persistence
Translation loading and merging (JSON + PHP)
Invalid/unsupported locale handling
Mocked DeepL and Google Translate API responses
Inertia props validation (locale + translations present)

What's Included

Feature	Details
Languages	EN, UK, PL, DE (2 active, 2 ready)
Detection	Browser + IP geolocation + fallback chain
Persistence	DB (auth) + Cookie (guest) + Session
Frontend	vue-i18n v3 + global t() + Inertia props
Translation files	JSON (UI) + PHP arrays (framework)
Content translation	DeepL + Google Translate API
UI	Language switcher with flags (auth + guest)
Testing	Pest tests for all detection paths

Wrapping Up

Most SaaS i18n implementations are either too simple (just __()) or too complex (dedicated translation management services, CDN-hosted locale files, runtime language switching via WebSockets).

LaraFoundry's approach sits in the middle: comprehensive enough for production, simple enough to understand in 30 minutes. The entire system is ~10 files and zero external dependencies beyond vue-i18n.

If you're building a SaaS with Laravel + Inertia + Vue and need multilanguage support, this module gives you everything you need.

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 #i18n #saas #larafoundry

How I Built a Production-Grade Activity Logging System for a Laravel SaaS (Event-Driven, Zero Manual Calls)

Dmitry Isaenko — Mon, 23 Mar 2026 09:44:53 +0000

Introduction

"We'll add logging later."

Every developer has said it. Few actually go back and do it properly. And when they do, it's usually after something breaks in production and nobody can figure out what happened.

When I started building Kohana.io - a production CRM/ERP system - I decided logging would be a Day 1 feature. Not a nice-to-have. Not a "sprint 47" backlog item.

Now I'm extracting the core of Kohana into LaraFoundry - a reusable SaaS engine. And the logging module is one of the most important pieces.

In this article, I'll walk through the complete architecture: the event-driven approach, device fingerprinting, async geolocation, multi-channel notifications, and the admin UI that makes it all actionable.

The Problem with Manual Logging

Most logging in Laravel apps looks like this:

// Scattered across 40 controllers
Log::info('User logged in', ['user_id' => $user->id]);
Log::info('Product created', ['product_id' => $product->id]);
Log::warning('Login failed', ['email' => $email]);

Problems:

Inconsistent - every developer formats logs differently
Incomplete - someone always forgets to add a log call
Flat - no device info, no geo, no request context
Unqueryable - good luck searching through text files for patterns

LaraFoundry takes a different approach: event-driven, structured, and automatic.

Architecture Overview

User Action (HTTP Request)
    |
    v
Event Fired (e.g. ProductCreated::class)
    |
    v
ActivityLogServiceProvider (listener)
    |
    v
ActivityLogService::logActivity()
    |
    +---> Creates CustomActivity record
    |       - Request metadata (IP, URL, method)
    |       - Device info (browser, OS, device type)
    |       - Event properties (custom per event)
    |       - Response status code
    |
    +---> Dispatches RetrieveActivityGeoData job
            |
            v
        GetGeoDataByIpAction (cached 24h)
            |
            v
        Updates CustomActivity with geo data

Package Stack

Package	Purpose
`spatie/laravel-activitylog`	Core activity tracking (extended)
`jenssegers/agent`	Device/browser/OS detection
`opcodesio/log-viewer`	Web UI for Monolog file logs
`laravel/telescope`	Dev/testing debugger

Plus a free geo API (ip-api.com) with smart caching.

Step 1: The Event Map

The heart of the system is ActivityLogServiceProvider. It defines a single array mapping events to log metadata:

class ActivityLogServiceProvider extends ServiceProvider
{
    protected array $events = [
        // Auth events
        Registered::class    => ['Auth', 'New user registered', 200],
        Login::class         => ['Auth', 'Login', 200],
        Logout::class        => ['Auth', 'Logout', 200],
        Failed::class        => ['Auth', 'Login failed', 401],
        PasswordReset::class => ['Auth', 'Password reset', 200],

        // Company events
        CompanyCreate::class           => ['Company', 'New company created', 200],
        CompanyDeleted::class          => ['Company', 'Company deleted', 200],
        EmployeeInvitationSent::class  => ['Company', 'Employee invitation sent', 200],
        RoleCreated::class             => ['Company', 'Custom role created', 201],

        // Warehouse events
        ProductCreated::class        => ['Warehouse', 'Product created', 201],
        ProductUpdated::class        => ['Warehouse', 'Product updated', 200],
        ProductDeleted::class        => ['Warehouse', 'Product deleted', 200],
        ProductCreationFailed::class => ['Warehouse', 'Product creation failed', 500],

        // Contragent events
        ContragentCreated::class => ['Contragent', 'Contragent created', 201],
        ContragentDeleted::class => ['Contragent', 'Contragent deleted', 200],

        // ... 60+ events total
    ];
}

Format: [EventGroupName, Description, HTTP ResponseCode].

In the boot() method, all listeners are registered dynamically:

public function boot()
{
    Activity::unguard();

    foreach ($this->events as $eventClass => [$group, $desc, $code]) {
        Event::listen($eventClass, function ($event) use ($eventClass, $group, $desc, $code) {
            $eventClassName = class_basename($eventClass);

            $eventProperties = method_exists($event, 'getLogProperties')
                ? ['event_properties' => $event->getLogProperties()]
                : [];

            ActivityLogService::logActivity(
                $event, $eventClassName, $group, $desc, $code, $eventProperties
            );
        });
    }
}

The key insight: each event can optionally implement getLogProperties() to provide module-specific context:

// In TicketCreate event
public function getLogProperties(): array
{
    return [
        'ticket_id' => $this->ticket->id,
        'ticket_title' => $this->ticket->title,
        'ticket_priority' => $this->ticket->priority,
        'categories' => $this->ticket->categories->pluck('name')->implode(', '),
    ];
}

No coupling between events and the logging system. Events don't know they're being logged. The ServiceProvider handles everything.

Step 2: The Custom Activity Model

Spatie's default Activity model stores the basics: log_name, description, properties, causer. For a SaaS, that's not enough.

CustomActivity extends Spatie's model with 15 additional fields:

class CustomActivity extends Activity
{
    protected $table = 'activity_log';

    protected $fillable = [
        'user_agent', 'log_name', 'description',
        'subject_type', 'subject_id',
        'causer_type', 'causer_id', 'properties',
        // Device fingerprint
        'user_ip', 'user_device_type', 'user_device_name',
        'user_os', 'user_browser',
        // Request context
        'route_name', 'request_method', 'full_url', 'response_code',
        // Status
        'is_successful', 'user_email',
        // Geolocation
        'geo_country', 'geo_city', 'geo_updated_at',
    ];

    protected $casts = [
        'properties' => 'collection',
        'is_successful' => 'boolean',
        'geo_updated_at' => 'datetime',
    ];
}

Now every event is structured and queryable. Want failed logins from a specific country? One Eloquent query.

Step 3: The Activity Log Service

ActivityLogService is the central piece that creates log records and enriches them with device data:

class ActivityLogService
{
    public static function logActivity($event, string $eventClassName, string $eventGroupName, string $description, int $responseCode, array $eventProperties = []): void
    {
        $request = request();
        $ip = $request->ip();

        $properties = [
            'event_group_name' => $eventGroupName,
            'middleware' => request()->route()?->gatherMiddleware() ?? [],
        ] + $eventProperties;

        $activity = CustomActivity::create([
            'log_name'         => $eventClassName,
            'description'      => $description,
            'properties'       => $properties,
            'response_code'    => $responseCode,
            'is_successful'    => ($responseCode < 400),
            'user_ip'          => $ip,
            'user_device_type' => Agent::isDesktop() ? 'desktop' : (Agent::isTablet() ? 'tablet' : 'mobile'),
            'user_device_name' => Agent::device(),
            'user_os'          => Agent::platform(),
            'user_browser'     => Agent::browser(),
            'route_name'       => $request->route()?->getName(),
            'request_method'   => $request->method(),
            'full_url'         => $request->fullUrl(),
            // Geo filled async
            'geo_country'      => null,
            'geo_city'         => null,
        ]);

        RetrieveActivityGeoData::dispatch($activity->id, $ip);
    }
}

Notice: geolocation fields are null on creation. They get filled asynchronously via a queued job.

Step 4: Async Geolocation

A geo API call adds ~200ms per request. unacceptable for synchronous execution. LaraFoundry handles this in the background:

class RetrieveActivityGeoData implements ShouldQueue
{
    public $timeout = 30;
    public $tries = 3;

    public function handle()
    {
        $activity = CustomActivity::find($this->activityId);
        if (!$activity) return;

        $geoData = app(GetGeoDataByIpAction::class)($this->ip);
        $activity->update([
            'geo_country'    => $geoData['country'],
            'geo_city'       => $geoData['city'],
            'geo_updated_at' => now(),
        ]);
    }

    public function failed(\Throwable $exception)
    {
        Log::error("Failed to get geo data for activity {$this->activityId}: " . $exception->getMessage());
        $activity = CustomActivity::find($this->activityId);
        $activity?->update([
            'geo_country' => 'Unknown',
            'geo_city'    => 'Unknown',
            'geo_updated_at' => now(),
        ]);
    }
}

The GetGeoDataByIpAction itself is a clean, invokable action class with smart caching:

class GetGeoDataByIpAction
{
    public function __invoke(string $ip): array
    {
        if (self::isLocalIp($ip)) {
            return ['country' => 'Local network', 'city' => 'Local network'];
        }

        return Cache::remember("geo_data_{$ip}", 24 * 60 * 60, function () use ($ip) {
            try {
                $response = Http::timeout(5)->get("http://ip-api.com/json/{$ip}");
                if ($response->successful()) {
                    $data = $response->json();
                    return [
                        'country' => $data['country'] ?? 'Unknown',
                        'city'    => $data['city'] ?? 'Unknown',
                    ];
                }
            } catch (Exception $e) {
                Log::warning("Geo API error for IP {$ip}: " . $e->getMessage());
            }
            return ['country' => 'Unknown', 'city' => 'Unknown'];
        });
    }
}

Key decisions:

24-hour cache per IP (same user, same IP, no redundant API calls)
Local IP detection (127.0.0.1, 192.168., 10., 172.* skip the API)
Graceful fallback ("Unknown" if the API is down)
5-second timeout (don't hang on slow API responses)

Step 5: Multi-Channel Admin Notifications

Some events need more than a log entry. Admin login attempts in LaraFoundry trigger instant notifications via email and Telegram:

class AdminLoginAttemptNotification extends Notification implements ShouldQueue
{
    public function __construct($step)
    {
        $this->ip = request()->ip();
        $geoData = app(GetGeoDataByIpAction::class)($this->ip);
        $this->location = 'Country: '.$geoData['country'].', City: '.$geoData['city'];

        // Capture device data DURING request, BEFORE queue serialization
        $this->deviceType = Agent::isDesktop() ? 'desktop' : (Agent::isTablet() ? 'tablet' : 'mobile');
        $this->deviceName = Agent::device();
        $this->deviceOS = Agent::platform();
        $this->deviceBrowser = Agent::browser();
        $this->userAgent = request()->userAgent();
    }

    public function via($notifiable)
    {
        return ['mail', 'telegram'];
    }
}

Important gotcha: Device data must be captured in the constructor (during the HTTP request), not in the toMail()/toTelegram() methods. The Agent facade needs the actual request context. once the notification is serialized to the queue, that context is gone.

Step 6: File-Based Logging (Monolog)

Activity logs are for business events. For system-level debugging, LaraFoundry uses Monolog with split channels:

// config/logging.php
'stack' => [
    'driver' => 'stack',
    'channels' => ['daily', 'critical'],
],
'daily' => [
    'driver' => 'daily',
    'path' => storage_path('logs/laravel.log'),
    'level' => 'debug',
    'days' => 14,
],
'critical' => [
    'driver' => 'daily',
    'path' => storage_path('logs/critical.log'),
    'level' => 'error',
    'days' => 30,
],

Every log entry goes to daily. Only errors go to critical (with 30-day retention instead of 14). This means you can freely rotate daily logs without losing error history.

For browsing these logs, opcodesio/log-viewer provides a web UI at /admin/log-viewer with search, filtering, and stack trace viewing.

Step 7: Telescope for Development

Laravel Telescope is the developer's microscope. In LaraFoundry, it's enabled only in local and testing:

'enabled' => in_array(env('APP_ENV'), ['local', 'testing']),

Configured watchers:

QueryWatcher - flags slow queries > 100ms
ModelWatcher - tracks all eloquent.* events
EventWatcher - every event dispatched
JobWatcher - queue job processing
ExceptionWatcher - all exceptions
MailWatcher, NotificationWatcher, GateWatcher, etc.

Zero overhead in production. Full visibility in development.

Step 8: The Admin UI

Logs are useless if nobody looks at them. LaraFoundry provides two Inertia/Vue views:

User-specific logs (/admin/logs/{user}):

Time range filter: 1h, 6h, 12h, 24h, 48h, 72h
Device info in tooltips
Success/error badges
Responsive: tables on desktop, expandable cards on mobile

General system logs (/admin/generalLogs):

All events across all users
Event group filtering (Auth, Company, Warehouse...)
Response code + result columns
100 per page with pagination

The controller is minimal:

public function userLogs(Request $request, User $user)
{
    $hours = $request->get('hours', 1);
    $logs = CustomActivity::where('causer_id', $user->id)
        ->where('created_at', '>=', Carbon::now()->subHours($hours))
        ->orderBy('created_at', 'desc')
        ->with('user')
        ->paginate(50);

    return Inertia::render('admin/logs/UserLogs', [
        'logs' => ActivityLogResource::collection($logs),
        'selectedHours' => $hours,
        'availableHours' => [1, 6, 12, 24, 48, 72],
    ]);
}

Testing

Every link in the logging chain gets tested with Pest PHP:

Events fire correctly from user actions
ServiceProvider intercepts events and calls ActivityLogService
CustomActivity records are created with all expected fields
Device fingerprint data is captured
Geo-data job dispatches and handles failures
Admin notifications fire on critical events
Time range filters return correct datasets
Log viewer routes require authentication

A logging system that silently breaks is worse than no logging at all.

Summary

Layer	Tool	Environment	Audience
Business activity	CustomActivity + Inertia UI	All	Admins
System debugging	Laravel Telescope	Dev/Testing	Developers
File logs	Monolog + Log Viewer	All	DevOps
Real-time alerts	Notifications (Mail + Telegram)	All	Admins

Adding logging to a new module? Add your events to the $events array in ActivityLogServiceProvider. That's it.

If you're building a SaaS and logging isn't a Day 1 feature - reconsider. Your future self debugging a production issue at 2 AM will thank you.

LaraFoundry is a production-proven SaaS engine extracted from Kohana.io. Follow the build-in-public journey and join the waitlist at larafoundry.com.

laravel #php #saas #webdev #larafoundry

How I Built a Complete Multi-Tenancy System for My Laravel SaaS - Without Spatie

Dmitry Isaenko — Mon, 16 Mar 2026 10:39:52 +0000

Every SaaS application needs to answer one question on every single request: "who can do what in which company?"

Sounds simple. It's not.

I've been building Kohana.io - a SaaS CRM/ERP for small businesses. The multi-tenancy module took longer than any other module to get right. Not because the code is complex, but because the decisions are complex: single database or separate databases? Config-driven or database-driven permissions? How do you handle permission overrides? What happens when a user gets a 403?

Now I'm extracting this module into LaraFoundry - an open-source Laravel SaaS framework - so nobody has to make these decisions from scratch again.

Here's exactly how it works.

Architecture Overview

Component	Purpose
'BelongsToCompany' trait	Automatic query filtering by active company
'config/roles-and-permissions.php'	All permissions defined in one place
Gate classes (8 files)	Complex authorization logic per module
'HasRolesAndPermissions' trait	5-level permission hierarchy on User model
'SetActiveCompanyMiddleware'	Auto-resolves tenant context
'CheckAccessMiddleware'	Ban + payment status checks
'LayoutDataService'	Permission-aware menu + FAR routing

Tech stack: Laravel 12, Inertia.js v2, Vue 3, Pest PHP

1. Data Isolation - The BelongsToCompany Trait

The scariest bug in multi-tenancy is a data leak. Showing Company A's orders to Company B.

It only takes one forgotten 'where('company_id', ...)' and you've got a GDPR nightmare.

LaraFoundry solves this at the Eloquent model level:

trait BelongsToCompany
{
    protected static function bootBelongsToCompany(): void
    {
        static::addGlobalScope('company', function (Builder $builder) {
            if (auth()->check()) {
                $companyId = auth()->user()->getCurrentCompanyId();
                if ($companyId) {
                    $builder->where(
                        $builder->getModel()->getTable() . '.company_id',
                        $companyId
                    );
                }
            }
        });
    }

    public function scopeForCompany(Builder $query, int $companyId): Builder
    {
        return $query->withoutGlobalScope('company')
            ->where($this->getTable() . '.company_id', $companyId);
    }

    public function scopeForAdmin(Builder $query): Builder
    {
        return $query->withoutGlobalScope('company');
    }
}

Usage:

// Controller - no filtering needed
$orders = Order::query()->latest()->paginate(20);
// Automatically: SELECT * FROM orders WHERE company_id = 5

// Admin dashboard - see everything
$allOrders = Order::forAdmin()->latest()->paginate(50);

// Specific company query
$report = Order::forCompany(7)->where('status', 'completed')->get();

The table prefix ('$builder->getModel()->getTable() . '.company_id'') prevents ambiguous column errors in joins. Small detail, saves hours of debugging.

2. Config-Driven Permission Registration

All permissions are defined in 'config/roles-and-permissions.php':

'permissions' => [
    'orders' => [
        'label' => 'Orders',
        'permissions' => [
            'orders.view' => 'View orders',
            'orders.create' => 'Create orders',
            'orders.update' => 'Update orders',
            'orders.delete' => 'Delete orders',
            'orders.approve' => 'Approve orders',
            'orders.status_change' => 'Change order status',
            'orders.export' => 'Export orders',
        ],
    ],
    'warehouse' => [
        'label' => 'Warehouse',
        'permissions' => [
            'warehouse.view' => 'View warehouse',
            'warehouse.create' => 'Add to warehouse',
            'warehouse.update' => 'Update warehouse',
            'warehouse.delete' => 'Delete from warehouse',
            'warehouse.inventory' => 'Inventory',
            'warehouse.transfer' => 'Transfer goods',
            'warehouse.reserve' => 'Reserve goods',
            'warehouse.assembly' => 'Order assembly',
        ],
    ],
    // 20+ modules, 100+ permissions total
],

'AuthServiceProvider' reads this config and registers a Gate for each permission:

protected function registerPermissionGates(): void
{
    $permissions = $this->getAllPermissionsFromConfig();

    foreach ($permissions as $permissionSlug) {
        Gate::define($permissionSlug, function (User $user, ?Company $company = null) use ($permissionSlug) {
            $company = $company ?? $user->getActiveCompany();
            return $user->hasPermissionTo($permissionSlug, $company);
        });
    }
}

One loop. All permissions registered. Add a new permission? Add one line to config, run 'php artisan permissions:sync'.

3. Dedicated Gate Classes for Complex Logic

Config handles 90% of permissions (simple CRUD). But some authorization logic has business rules. Like removing an employee:

// app/Gates/EmployeeGates.php
class EmployeeGates
{
    public static function register(): void
    {
        Gate::define('employees.remove', function (User $user, User $employee) {
            $company = $user->getActiveCompany();

            if ($user->id === $employee->id) return false;        // can't remove yourself
            if ($employee->isOwnerOf($company)) return false;      // can't remove the owner
            if (!$employee->companies->contains($company)) return false; // wrong company

            if ($user->isOwnerOf($company)) return true;           // owner can remove anyone

            return $user->hasPermissionTo('company.employees.remove', $company);
        });

        // employees.assignRole, employees.grantPermissions,
        // employees.manageRolesAndPermissions, employees.requestRemoval,
        // employees.confirmRemoval...
    }
}

Each module gets its own Gate class. All registered from AuthServiceProvider:

protected function registerCustomGates(): void
{
    CompanyGates::register();
    EmployeeGates::register();
    RoleGates::register();
    ContragentGates::register();
    WarehouseGates::register();
    ProductionGates::register();
}

Result: AuthServiceProvider stays under 60 lines. Each Gate class is independently testable.

4. The 5-Level Permission Hierarchy

This is the core of the system. Five levels, checked top to bottom:

Level 1: Super Admin  -> bypass everything
Level 2: Company Owner -> full access to their company
Level 3: Revoked       -> explicitly blocked (overrides roles!)
Level 4: Individual    -> explicitly granted (overrides roles)
Level 5: Role-based    -> permissions inherited from role

The implementation:

public function hasPermissionTo(string $permissionSlug, Company|int|null $company = null): bool
{
    // Level 1: Super admin
    if ($this->isSuperAdmin()) return true;

    // Level 2: Company owner
    if ($company && $this->isOwnerOf($company)) return true;

    $companyId = $company instanceof Company ? $company->id : $company;

    // Level 3: Check if explicitly revoked
    $isRevoked = $this->permissions()
        ->where('permissions.slug', $permissionSlug)
        ->wherePivot('company_id', $companyId)
        ->wherePivot('is_revoked', true)
        ->exists();
    if ($isRevoked) return false;

    // Level 4: Check if explicitly granted
    $isGranted = $this->permissions()
        ->where('permissions.slug', $permissionSlug)
        ->wherePivot('company_id', $companyId)
        ->wherePivot('is_revoked', false)
        ->exists();
    if ($isGranted) return true;

    // Level 5: Check role permissions (company-scoped)
    return $this->roles()
        ->wherePivot('company_id', $companyId)
        ->whereHas('permissions', fn($q) => $q->where('slug', $permissionSlug))
        ->exists();
}

Why this order matters:

Imagine a "Manager" role with 'orders.delete'. But one specific manager shouldn't delete orders. Instead of creating a new role, the company owner just revokes that one permission. Done.

The opposite works too - a "Worker" role doesn't have 'production.assign', but one senior worker needs it. Grant it individually.

The 'is_revoked' flag in the 'user_permissions' pivot table is what makes it all possible:

user_permissions: user_id, permission_id, company_id, is_revoked, granted_by_id

One boolean. So much flexibility.

5. Role Templates & Custom Roles

When a new company is created, 5 role templates are automatically cloned:

'role_templates' => [
    'manager' => [
        'name' => 'Manager',
        'description' => 'Manage orders, contragents, view reports',
        'permissions' => [
            'orders.view', 'orders.create', 'orders.update', 'orders.delete',
            'contragents.viewAny', 'contragents.view', 'contragents.create',
            'production.view', 'production.create', 'dashboard.view',
            // ...20+ permissions
        ],
    ],
    'accountant' => [ /* ... */ ],
    'storekeeper' => [ /* ... */ ],
    'logistician' => [ /* ... */ ],
    'worker' => [ /* ... */ ],
],

The company owner can:

Edit template roles (add/remove permissions)
Create completely custom roles
Assign multiple roles to one employee
Override any role permission per individual user
Delete custom roles (if no users are assigned)

All from the UI. No developer needed.

6. Middleware Stack - Tenant Context

Three middleware components handle the multi-tenancy lifecycle:

SetActiveCompanyMiddleware

Runs on every web request. Sets the active company context:

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

    $user = auth()->user();

    // Already has active company? Verify ownership
    if (session()->has('active_company_id')) {
        $companyBelongsToUser = $user->companies()
            ->wherePivot('is_deleted', false)
            ->where('companies.id', session('active_company_id'))
            ->exists();

        if ($companyBelongsToUser) return $next($request);
        session()->forget('active_company_id');
    }

    // Priority: owned company > employee company
    $ownedCompany = $user->companies->first(
        fn($company) => $user->isOwnerOf($company)
    );
    $user->setActiveCompany($ownedCompany ?? $user->companies->first());

    return $next($request);
}

If a user gets removed from a company, the middleware auto-switches on the next request. No stale state.

CheckAccessMiddleware

Checks ban status (user + owner) and payment status (trial + subscription). Even banned users can access support tickets.

CheckCompanyAccess

Owner-only routes: company settings, employee management, role configuration.

Middleware order in bootstrap/app.php:

1. HandleInertiaRequests
2. SetActiveCompanyMiddleware      <- tenant context
3. UpdateLastSessionActivity
4. SetLocale
5. EnsureEmailIsVerified
6. CheckPinLockMiddleware
7. CheckAccessMiddleware           <- ban + payment check
8. CheckSessionExists

Order matters. You can't check company permissions before you know which company.

7. Permission-Aware Navigation

Every menu item has a 'policyName':

[
    'linkName' => __('Orders'),
    'policyName' => 'orders.view',
    'routeName' => 'orders',
],
[
    'linkName' => __('Warehouse'),
    'policyName' => 'warehouse.view',
    'routeName' => 'warehouse',
],

Each item runs through 'checkUserAndCompanyPolicy()':

private function checkUserAndCompanyPolicy($policyName)
{
    if ($this->isAdmin()) return true;
    if (empty($policyName)) return false;
    if ($policyName === 'public') return auth()->check();

    $user = auth()->user();
    $company = $user->getActiveCompany();
    if (!$company) return false;

    if ($user->isOwnerOf($company)) return true;

    return $user->hasPermissionTo($policyName, $company);
}

A "Storekeeper" sees: Warehouse. A "Manager" sees: Orders, Production, Contragents. An owner sees everything. If you can't access it - you don't see it.

8. The First Allowed Route (FAR) Pattern

The pattern that eliminated 403 pages from my SaaS entirely.

Instead of showing a 403 error page, redirect the user to the first page they CAN access:

// bootstrap/app.php - exception handler
$exceptions->renderable(function (AccessDeniedHttpException $e, Request $request) {
    $layoutService = app(LayoutDataService::class);

    return redirect()
        ->route($layoutService->getFirstAllowedRouteName())
        ->with('message-disappear-error', __('You do not have permission to access this page'));
});

The 'getFirstAllowedRouteName()' method:

Checks if user has a saved default page for this company
If that page is still accessible - go there
If not - clear it, show warning, fall back
Walk through menu items, find the first accessible one
Fallback to notifications

public function getFirstAllowedRouteName(): string
{
    if (self::isAdmin()) return 'admin.dashboard.index';

    if (!$this->authUserData->hasUserCompanyOrRole()) {
        return 'notifications.index';
    }

    // Check saved default route
    $saved = auth()->user()->getDefaultRouteForActiveCompany();
    if ($saved && $this->isBottomLevelRouteAccessible($saved)) {
        return $saved;
    }

    // Walk menu items
    foreach ($this->getNavUpLevelItemsArray() as $navItem) {
        if (!empty($navItem['unvisibly'])) continue;
        if ($this->checkUserAndCompanyPolicy($navItem['policyName'])) {
            return $this->getFirstAllowedBottomLevelRoute($navItem['routeName'])
                ?? $navItem['routeName'];
        }
    }

    return 'notifications.index';
}

Used in 4 places: after login, after 403, after company switch, in sidebar "Home" link.

9. Testing - Proof It Works

Multi-tenancy bugs are silent data leaks. Automated tests are mandatory.

Permission hierarchy test:

it('respects priority: revoked > granted > role', function () {
    $employee->assignRole($managerRole, $company);

    // Manager has orders.view from role
    $employee->revokePermissionFrom($ordersView, $company);
    // Manager doesn't have warehouse.delete
    $employee->givePermissionTo($warehouseDelete, $company);

    expect($employee->hasPermissionTo('orders.view', $company))->toBeFalse()
        ->and($employee->hasPermissionTo('warehouse.delete', $company))->toBeTrue();
});

Cross-company isolation:

it('denies updating role from different company', function () {
    $roleFromCompany2 = Role::create([
        'company_id' => $company2->id,
    ]);

    $this->actingAs($ownerOfCompany1);
    expect(Gate::denies('roles.update', $roleFromCompany2))->toBeTrue();
});

Menu visibility:

it('employee with orders permission sees only orders', function () {
    $employee->givePermissionTo($ordersPermission, $company);

    $menu = $service->getNav('upLevel');
    $labels = collect($menu)->pluck('linkName')->toArray();

    expect($labels)
        ->toContain('Orders')
        ->not->toContain('Production')
        ->not->toContain('Warehouse')
        ->not->toContain('My company');
});

Owner-only routes:

it('employee cannot access company settings page', function () {
    $response = $this->withCookie($cookieName, $sessionId)
        ->get(route('my_company.company_settings'));

    $response->assertRedirect();
    $response->assertSessionHas('message-disappear-error');
});

Total test coverage: 19 test files covering permission hierarchy, cross-company isolation, Gate authorization, menu visibility, middleware chain, owner-only routes, role CRUD, employee management, and edge cases (no company, expired trial, banned owner, unverified email).

Database Schema

companies          id, name, created_by_id, trial_ends_at, subscription_ends_at
company_user       user_id, company_id, is_owner, is_deleted, default_route
roles              id, name, slug, company_id, is_global, is_template, is_custom
permissions        id, name, slug, module
role_permissions   role_id, permission_id
user_roles         user_id, role_id, company_id, assigned_by_id
user_permissions   user_id, permission_id, company_id, is_revoked, granted_by_id

Why Not Spatie?

Spatie Permission is great for simpler setups. But it doesn't handle:

Company-scoped roles (same role slug, different permissions per company)
Permission overrides (revoke/grant individual permissions that override roles)
Role templates that clone on company creation
The 'is_revoked' pattern for granular control
Config-driven permission registration with artisan sync

LaraFoundry's system is purpose-built for multi-tenant SaaS where company owners manage their own teams.

What's Next

All of this is extracted from Kohana.io, where it runs in production handling real companies with real employees.

Star the repo or join the waitlist: larafoundry.com

This is part of a series where I'm building LaraFoundry in public. Previously: Registration Module, Authentication Module.

I Built 6 Authentication Methods for My Laravel SaaS - Here's the Full Architecture

Dmitry Isaenko — Mon, 09 Mar 2026 08:15:12 +0000

Every SaaS project starts with authentication. And every time, developers face the same choice: use a starter kit and outgrow it in a month, or build from scratch and spend weeks on something that isn't your core product.

I've been building Kohana.io - a SaaS CRM/ERP for small businesses - and I got tired of this cycle. So I built a comprehensive authentication module that handles everything from basic email login to QR code authentication and real-time admin security alerts.

Now I'm extracting it into LaraFoundry - an open-source SaaS framework for Laravel - so nobody has to build this again.

Here's how it all works.

The Authentication Stack

Method	Use Case
Email/Password	Standard login with rate limiting
OAuth (Google, Facebook, Twitter)	One-click social login
QR Code	Cross-device login (scan from phone)
PIN Code	Session lock for shared workstations
2FA (TOTP)	Admin account protection
IP Whitelisting	Admin access restriction

Tech stack: Laravel 12, Inertia.js v2, Vue 3, Custom SCSS

Key packages: Laravel Socialite v5, PragmaRX Google2FA, SimpleSoftwareIO QrCode, Jenssegers Agent

1. Email/Password Authentication

The foundation. But with important production-grade additions.

Rate Limiting

// LoginRequest.php
public function ensureIsNotRateLimited(): void
{
    if (!RateLimiter::tooManyAttempts($this->throttleKey(), 5)) {
        return;
    }

    event(new Lockout($this));

    $seconds = RateLimiter::availableIn($this->throttleKey());

    throw ValidationException::withMessages([
        'email' => trans('auth.throttle', [
            'seconds' => $seconds,
            'minutes' => ceil($seconds / 60),
        ]),
    ]);
}

public function throttleKey(): string
{
    return Str::transliterate(
        Str::lower($this->string('email')) . '|' . $this->ip()
    );
}

Session Tracking

Every successful login creates a detailed session record:

$request->user()->userSessions()->create([
    'session_id' => $request->session()->getId(),
    'ip_address' => $request->getClientIp(),
    'user_agent' => $request->userAgent(),
    'last_activity' => now(),
    'pin_locked' => false,
    'user_device_type' => self::getUserDeviceType(),
    'user_device_name' => Agent::device(),
    'user_os' => Agent::platform(),
    'user_browser' => Agent::browser(),
]);

This gives users a "Active Sessions" view where they can see all their logged-in devices and clear the ones they don't recognize - similar to what Google and GitHub offer.

Remember Me

Works for both email and OAuth login. For OAuth, the remember me preference is stored in the session before the redirect and applied after the callback:

// Before OAuth redirect
if ($request->boolean('oauth_remeber_me')) {
    session(['oauth_remember_me' => true]);
}

// After OAuth callback
$remember = session('oauth_remember_me', false);
Auth::login($user, $remember);

2. OAuth Authentication

Three providers out of the box: Google, Facebook, and Twitter. Powered by Laravel Socialite v5.

public function callback(string $provider, UserLogoService $userLogo)
{
    if (!in_array($provider, ['google', 'facebook', 'twitter'])) {
        return redirect()->route('guest_index')
            ->with('message-error', 'Invalid OAuth provider');
    }

    $socialUser = Socialite::driver($provider)->user();

    $user = User::updateOrCreate(
        ['email' => $socialUser->email],
        [
            'provider_id' => $socialUser->id,
            'provider_name' => $provider,
            'name' => $socialUser->name,
            'email_verified_at' => now(), // OAuth = auto-verified
            'provider_token' => $socialUser->token,
            'provider_refresh_token' => $socialUser->refreshToken,
            'last_login_at' => now(),
            'last_activity_at' => now(),
        ]
    );

    Auth::login($user, $remember);
}

Key design decisions:

Email as the unique identifier - if a user registers via email and later logs in with Google using the same email, the account is linked automatically
OAuth emails are auto-verified - no need to send a verification email when Google already confirmed it
Provider tokens are stored - useful for future integrations (e.g., importing contacts from Google)
Login method is tracked per session - so the "Active Sessions" view shows whether the user logged in natively or via OAuth

3. QR Code Authentication

This is the feature I'm most proud of. It works like WhatsApp Web: scan a QR code from your already-authenticated phone to log in on desktop.

The Architecture

┌──────────────────┐        ┌──────────────┐        ┌──────────────────┐
│  Desktop Browser │        │    Server    │        │  Mobile (Auth'd) │
│    (Guest)       │        │              │        │                  │
├──────────────────┤        ├──────────────┤        ├──────────────────┤
│ 1. Request QR    │───────>│ 2. Generate  │        │                  │
│                  │<───────│    UUID +    │        │                  │
│ 3. Display QR    │        │    SignIn    │        │                  │
│                  │        │    Request   │        │                  │
│ 4. Poll every 3s │───────>│              │        │                  │
│                  │        │              │<───────│ 5. Scan QR code  │
│                  │        │ 6. Verify +  │───────>│ 7. Show "Success"│
│                  │        │    Approve   │        │                  │
│ 8. Poll detects  │<───────│              │        │                  │
│    approval      │        │              │        │                  │
│ 9. Auto-login    │        │              │        │                  │
└──────────────────┘        └──────────────┘        └──────────────────┘

Token Generation

public function codeGenerate()
{
    $token = Uuid::uuid4();
    session()->put('token', Crypt::encrypt($token));

    $signInRequest = SignInRequest::create([
        'token' => $token,
        'expires_at' => now()->addMinutes(5),
        'ip_address' => request()->ip(),
        'user_agent' => request()->userAgent(),
    ]);

    session()->put('signInId', Crypt::encrypt($signInRequest->id));

    $qrCodeUrl = route('qr.verifyLogin', [
        'id' => Crypt::encrypt($signInRequest->id),
        'token' => $token,
    ]);

    $qrCode = base64_encode(
        QrCode::size(400)->format('svg')->generate($qrCodeUrl)
    );

    return response()->json([
        'qrCode' => $qrCode,
        'activeUntil' => $signInRequest->expires_at,
    ]);
}

Approval from Authenticated Device

public function verifyLogin(string $id, string $token)
{
    // Admins cannot approve QR logins (security)
    if (auth()->user()->is_admin) {
        return response()->json([
            'error' => 'Admin QR login is forbidden.'
        ], 404);
    }

    $signInRequest = SignInRequest::query()
        ->where('expires_at', '>', now())
        ->where('id', Crypt::decrypt($id))
        ->where('token', $token)
        ->first();

    if (!$signInRequest) {
        return response()->json(['error' => 'Code incorrect!'], 404);
    }

    $signInRequest->update([
        'user_id' => auth()->id(),
        'approved' => true,
        'approved_at' => now(),
        'approved_ip' => request()->ip(),
        'approved_user_agent' => request()->userAgent(),
    ]);

    return response()->json(['message' => 'Code recognized'], 200);
}

Browser Polling

public function pollLogin()
{
    $signInRequest = SignInRequest::query()
        ->where('id', Crypt::decrypt(session('signInId')))
        ->where('token', Crypt::decrypt(session('token')))
        ->where('expires_at', '>', now())
        ->first();

    if ($signInRequest && $signInRequest->approved) {
        Auth::login(User::find($signInRequest->user_id));
        $request->session()->regenerate();
        // Create session record...
        return response()->json(['result' => true]);
    }

    return response()->json(['result' => false]);
}

Security measures:

Tokens expire in 5 minutes
Request IDs are encrypted - never exposed in URLs raw
Admins cannot approve QR logins (prevents privilege escalation)
Both requesting and approving devices are fingerprinted
Session is regenerated after login

4. PIN Code Screen Lock

This feature was born from a real need. In Kohana.io, warehouse workers and sales managers often use shared computers. Logging out and back in every break is painful. Session timeout destroys unsaved work.

How It Works

Users enable a 4-digit PIN from their profile:

public function enable(Request $request)
{
    $request->validate(['pin' => 'required|digits:4']);
    $request->user()->update([
        'pin_code' => bcrypt($request->pin)
    ]);
}

The CheckPinLockMiddleware runs on every request:

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

    if (!$user || !$user->pin_code) {
        return $next($request);
    }

    $session = $user->userSessions()
        ->where('session_id', $request->session()->getId())
        ->first();

    // Already locked in DB?
    if ($session && $session->pin_locked) {
        return redirect()->route('pin.enter');
    }

    // Inactivity timeout check
    $timeout = config('security.pin_lock_timeout', 1800);
    if ($session && $session->last_activity
            ->diffInSeconds(now()) > $timeout) {
        $session->update(['pin_locked' => true]);
        return redirect()->route('pin.enter');
    }

    $session?->update(['last_activity' => now()]);

    return $next($request);
}

Why This Is Better Than Session Timeout

Feature	Session Timeout	PIN Lock
Unlock speed	Full password + possible 2FA	4 digits
Session data	Lost	Preserved
Unsaved work	Gone	Safe
Per-device control	No	Yes
Bypass via background requests	Easy	Impossible (DB-persisted)

The lock state is stored in the database, not the session. This means background API calls or WebSocket connections can't accidentally reset the inactivity timer.

5. Admin Security - The 3-Layer System

Layer 1: IP Whitelisting

private function checkAdminByIP(): bool
{
    if (empty(config('own.admin_ips'))) {
        return true;
    }

    $allowedIps = explode(',', config('own.admin_ips'));
    return in_array(request()->ip(), $allowedIps);
}

Wrong IP? Instant force-logout. No error page. The GetVisitorStatusAction returns 'forcelogout' and the controller handles it:

if (($this->getVisitorStatus)() === 'forcelogout') {
    return app(AuthenticatedSessionController::class)
        ->destroy(request());
}

Layer 2: Google Authenticator 2FA

After successful email+password login, admins see a 2FA screen. The Require2FA middleware enforces this on all admin routes:

public function handle(Request $request, Closure $next)
{
    if (($this->getVisitorStatus)() === 'admin') {
        if (!session('2fa_verified')) {
            if (!$request->routeIs('admin.2fa.*')) {
                return Inertia::location(route('admin.2fa.show'));
            }
        }
    }

    return $next($request);
}

Layer 3: Real-Time Notifications

Every failed admin login attempt triggers an email AND Telegram notification:

public static function notifyAdminOnLoginFail($step = 'During login input')
{
    Notification::route('mail', config('own.admin_email'))
        ->route('telegram', config('own.telegram_chat_id'))
        ->notify(new AdminLoginAttemptNotification($step));
}

The notification includes: IP + geolocation, device fingerprint, user agent, and which step failed (login, 2FA, or IP).

Trigger points:

Wrong password with admin email
Wrong 2FA code
Correct credentials but unauthorized IP

6. The Visitor Status System

The GetVisitorStatusAction is the central piece that ties everything together:

public function __invoke(): string
{
    if (!auth()->check()) return 'guest';

    $user = auth()->user();

    if ($user->is_admin && $this->checkAdminByEmail()) {
        if ($this->checkAdminByIP()) {
            return 'admin';
        } else {
            AdminHelper::notifyAdminOnLoginFail('IPs denied');
            return 'forcelogout';
        }
    }

    if ($user->user_blocked_at) return 'authBlocked';
    if ($user->user_deleted_at) return 'authDeleted';

    return 'auth';
}

Six possible states. Used in middleware, controllers, and frontend via Inertia shared data. Every component in the system knows exactly who the current user is and what they can do.

Route Architecture

// Guest routes
Route::middleware('guest')->group(function () {
    Route::post('register', [RegisteredUserController::class, 'store']);
    Route::post('login', [AuthenticatedSessionController::class, 'store']);

    // OAuth
    Route::controller(OAuthLoginController::class)
        ->prefix('oauth')->name('oauth.')->group(function () {
            Route::get('{provider}/callback', 'callback');
            Route::get('{provider}', 'redirect');
        });

    // Password reset
    Route::controller(ResetPasswordController::class)
        ->prefix('password')->name('password.')->group(function () {
            Route::post('forgot-password', 'sendEmail');
            Route::get('reset-password/{token}', 'resetForm');
            Route::post('reset-password', 'resetHandler');
        });
});

// QR Code (mixed middleware)
Route::controller(LoginWithQrCode::class)
    ->prefix('qr')->name('qr.')->group(function () {
        Route::post('code-generate', 'codeGenerate')->middleware('guest');
        Route::post('poll-login', 'pollLogin')->middleware('guest');
        Route::get('verify/{id}/{token}', 'verifyLogin')
            ->middleware(['auth', 'prevent.nonadmin.routes']);
    });

// Authenticated routes
Route::middleware(['auth'])->group(function () {
    // Email verification
    Route::controller(EmailVerificationController::class)
        ->middleware('prevent.nonadmin.routes')
        ->prefix('email')->name('verification.')->group(function () {
            Route::get('verify-email', 'notice');
            Route::get('verify-email/{id}/{hash}', 'verify')
                ->middleware(['signed', 'throttle:6,1']);
            Route::post('email/verification-notification', 'send')
                ->middleware('throttle:6,1');
        });

    // PIN code
    Route::controller(PinController::class)
        ->prefix('pin')->name('pin.')->group(function () {
            Route::get('/', fn () => inertia('auth/EnterPin'));
            Route::post('check', 'check');
            Route::post('enable', 'enable');
            Route::post('disable', 'disable');
            Route::post('lock', 'lock');
        });
});

// Admin routes (2FA + IP protected)
Route::middleware([AdminAccess::class, '2fa'])->group(function () {
    Route::prefix('admin/2fa')->name('admin.2fa.')
        ->controller(TwoFactorController::class)->group(function () {
            Route::get('/', 'show');
            Route::post('/', 'verify');
        });
});

7. Testing - Proof It All Works

Authentication is the front door to your SaaS. If it breaks, nobody gets in. If it has a hole, everyone gets in. Automated tests are non-negotiable.

PIN lock testing:

it('persists pin_locked=true to DB when auto-lock fires due to inactivity', function () {
    $user = User::factory()->create(['pin_code' => bcrypt('1234')]);
    $sessionId = actingAsWithSession($user);

    UserSession::where('session_id', $sessionId)
        ->update(['last_activity' => now()->subMinutes(31)->utc()]);

    $this->withCookie($cookieName, $sessionId)->get(route('home'));

    $session = UserSession::where('session_id', $sessionId)->first();
    expect((bool) $session->pin_locked)->toBeTrue();
});

it('keeps lock active when last_activity is reset while pin_locked=true', function () {
    // This test caught a real bug:
    // a background AJAX request was resetting last_activity,
    // which accidentally unlocked PIN-locked screens
    UserSession::where('session_id', $sessionId)
        ->update(['pin_locked' => true, 'last_activity' => now()->subMinutes(31)]);

    // Background request resets last_activity
    UserSession::where('session_id', $sessionId)
        ->update(['last_activity' => now()]);

    $response = $this->withCookie($cookieName, $sessionId)->get(route('home'));
    $response->assertRedirect(route('pin.enter')); // still locked!
});

Ban system testing:

it('blocks banned user from accessing main routes', function () {
    $this->user->update(['user_blocked_at' => now()]);
    $response = $this->withCookie($cookieName, $sessionId)->get(route('home'));
    $response->assertRedirect(route('user.blocked'));
});

it('allows banned user to access tickets (support)', function () {
    $this->user->update(['user_blocked_at' => now()]);
    $response = $this->withCookie($cookieName, $sessionId)->get(route('tickets.index'));
    $response->assertSuccessful();
});

it('blocks entire company when owner is banned', function () {
    // When the owner gets banned, ALL employees in that company lose access
});

Blocked user page:

it('blocked user can view user.blocked page', function () {
    $this->user->update([
        'user_blocked_at' => now(),
        'user_blocked_status' => 1,
    ]);

    $response->assertInertia(fn ($page) => $page
        ->component('auth/UserBlocked')
        ->has('blockReason')
        ->has('blockDate')
    );
});

it('redirects previously blocked user after unblocking', function () {
    $this->user->update(['user_blocked_at' => now()]);
    $this->user->update(['user_blocked_at' => null]);

    $response->assertRedirect(); // goes to first allowed route
});

What the test suite covers:

Login/logout flow (valid + invalid credentials)
PIN auto-lock (inactivity timeout, DB persistence, correct/wrong PIN, edge cases)
PIN manual lock (lock, unlock, wrong PIN)
User ban (blocking, allowed routes, support ticket access, logout)
Company owner ban (cascade to all employees)
Session management (isolation, ordering by last_activity)
Blocked user page (display, unblock redirect)
CheckAccess middleware priority (user ban > owner ban > payment check)
Email verification (valid hash, invalid hash, signed URLs)

What's Next

This authentication module ships with LaraFoundry out of the box. No configuration beyond your .env file.

Coming up next in the LaraFoundry series:

Roles & Permissions - Spatie + custom gates
Team Management - multi-company, invitations, member roles
Subscription Billing - Stripe integration

Star the repo on GitHub or join the waitlist at larafoundry.com to get notified.

LaraFoundry is being extracted from Kohana.io - a production SaaS CRM/ERP. Every feature described in this article is running in production today.

larafoundry #laravel #php #saas #authentication #webdev #security #opensource

Building a Production-Grade Registration Module for Laravel SaaS - The Complete Breakdown

Dmitry Isaenko — Mon, 02 Mar 2026 09:32:01 +0000

The Problem

Every SaaS project starts the same way. You scaffold authentication, wire up OAuth, handle email verification, build avatar logic, and set up session tracking. Then you do it all over again for your next project.

After my fourth SaaS project in three years, I decided to stop copy-pasting and start extracting.

LaraFoundry is a modular SaaS engine I'm building in public - extracted from Kohana.io, a production CRM/ERP system. Every module is battle-tested with real users before it's packaged.

This article is a complete technical breakdown of the first module: Registration.

What's Inside

The Registration module isn't just "create user + hash password." Here's what it handles:

Multi-provider authentication - Form + OAuth2 (Google, Facebook, Twitter)
Smart avatar system - Gravatar detection with generated fallback
Session & device tracking - Full device fingerprinting on every login
Auth event logging - 7 events logged automatically from Day 1
Team onboarding - Company invitation with auto-acceptance

Let's dive into each one.

1. Multi-Provider Authentication

Form Registration

The traditional path. User submits name, email, password - standard Laravel validation with a configurable password minimum.

// RegisteredUserController.php
public function store(Request $request, UserLogoService $userLogo)
{
    $credentials = $request->validate([
        'name'     => 'required|string|max:255',
        'email'    => 'required|string|lowercase|email|max:255|unique:' . User::class,
        'password' => ['required', 'confirmed', 'min:' . config('own.minmal_password_lenght')],
    ]);

    $credentials['avatar']           = $userLogo->assignDefaultUserLogo($credentials, true);
    $credentials['last_login_at']    = now();
    $credentials['last_activity_at'] = now();
    $credentials['locale']           = Session::get('locale', config('app.locale', 'en'));

    $user = User::create($credentials);

    event(new Registered($user));   // Email verification
    $user->notify(new WelcomeEmailNotification);  // Queued welcome email

    Auth::login($user);

    return Inertia::location(route('home'));
}

Notice what happens in a single request:

User created with auto-generated avatar
Registered event fires (triggers email verification)
Welcome email queued (non-blocking)
User logged in immediately
Session recorded with device info

OAuth2 Flow

LaraFoundry supports Google, Facebook, and Twitter via Laravel Socialite. The callback handler does everything in one request:

// OAuthLoginController.php
public function callback(string $provider, UserLogoService $userLogo)
{
    $socialUser = Socialite::driver($provider)->user();

    $user = User::updateOrCreate(
        ['email' => $socialUser->email],
        [
            'provider_id'            => $socialUser->id,
            'provider_name'          => $provider,
            'name'                   => $socialUser->name,
            'email_verified_at'      => now(),  // OAuth = pre-verified
            'provider_token'         => $socialUser->token,
            'provider_refresh_token' => $socialUser->refreshToken,
            'avatar'                 => $userLogo->assignDefaultUserLogo([
                'name'  => $socialUser->name,
                'email' => $socialUser->email,
            ], true),
            'last_login_at'  => now(),
            'locale'         => Session::get('locale', config('app.locale', 'en')),
        ]
    );

    Auth::login($user, session('oauth_remember_me', false));

    // Record session with device fingerprint
    $user->userSessions()->create([
        'session_id'       => request()->session()->getId(),
        'ip_address'       => request()->getClientIp(),
        'login_method'     => $provider,
        'user_agent'       => request()->userAgent(),
        'last_activity'    => now(),
        'user_device_type' => self::getUserDeviceType(),
        'user_device_name' => Agent::device(),
        'user_os'          => Agent::platform(),
        'user_browser'     => Agent::browser(),
    ]);

    // Auto-accept team invitation if token exists
    if (session()->has('invitation_token')) {
        $this->acceptInvitation(session('invitation_token'), $user);
    }

    return redirect()->route('home');
}

Key design decisions:

updateOrCreate on email - If the user already exists (registered via form), their account is linked to the OAuth provider. No duplicate accounts.
email_verified_at = now() - OAuth providers have already verified the email. Skip the verification step.
Invitation token in session - Since OAuth redirects leave the page, the invitation token is stored in the session before the redirect and retrieved in the callback.

Frontend (Vue 3 + Inertia v2)

The registration form is a modal component using Inertia's useForm:

<!-- AppGuestRegisterModalLayout.vue -->
<script setup>
import { useForm } from '@inertiajs/vue3';

const form = useForm({
    name: '',
    email: props.invitation?.email || '',
    password: '',
    password_confirmation: '',
    invitation_token: props.invitation?.token || '',
});

const submit = () => {
    form.post(route('register'), {
        onSuccess: () => {
            form.reset('password', 'password_confirmation');
        },
    });
};
</script>

OAuth buttons redirect to /oauth/{provider} with optional parameters for remember-me and invitation tokens.

2. Smart Avatar System

This is one of those "small details, big impact" features.

The Problem

When a user signs up, what do you show as their avatar? A grey circle? A generic silhouette? That screams "unfinished product."

The Solution: UserLogoService

LaraFoundry uses a 2-layer avatar pipeline:

User registers
    ↓
Check Gravatar (creativeorange/gravatar)
    ↓
Found? → Download → Resize to 128px → Save as JPEG
    ↓ No
Generate initials avatar (laravolt/avatar)
    → 15 curated colors
    → Bold typography (OpenSans/Rockwell)
    → Deterministic (same name = same color)
    ↓
Save to date-organized storage (user-logos/2026/02/{uuid}.jpg)

Here's the actual service:

// UserLogoService.php
class UserLogoService
{
    public function assignDefaultUserLogo($userDataArray, $useGravatar = false)
    {
        $userLogoName = null;

        // Step 1: Try Gravatar
        if ($useGravatar && self::isGravatarExists($userDataArray['email'])) {
            $userLogoName = self::getAndStorageGravatar($userDataArray['email']);
        }

        // Step 2: Fallback to generated avatar
        if (!$useGravatar || $userLogoName === null) {
            $paths = self::userLogoPathPrepear();
            $avatar = new Avatar(config('laravolt.avatar'));
            $avatar->create($userDataArray['name'])
                   ->save($fullPath . '/' . $paths['uniqJpegFileName'], 100);
            return $paths['subfolder'] . '/' . $paths['uniqJpegFileName'];
        }

        return $userLogoName;
    }

    public static function isGravatarExists($email)
    {
        return Gravatar::exists($email);
    }

    public static function resizeAndSaveImage($image, $path)
    {
        return Image::read($image)->scale(height: 128)->toJpeg(90)->save($path);
    }

    public static function userLogoPathPrepear()
    {
        $folder    = config('own.user_logo_folder');
        $subfolder = Carbon::now()->format('Y') . '/' . Carbon::now()->format('m');

        Storage::disk('public')->makeDirectory($folder . '/' . $subfolder);

        return [
            'folder'           => $folder,
            'subfolder'        => $subfolder,
            'uniqJpegFileName' => Str::uuid() . '.jpg',
        ];
    }
}

Why this matters

Gravatar users get their existing avatar - consistency across platforms
Everyone else gets a unique, colorful avatar - the app feels polished from second one
Deterministic colors - "John Smith" always gets the same color, making users recognizable in lists and comments
UUID filenames - zero collision risk, even at scale
Date-organized storage - easy cleanup, backup, and archival

Packages

Package	Purpose
`creativeorange/gravatar` ~1.0	Check & download Gravatar
`laravolt/avatar` ^6.2	Generate initials-based avatars
`intervention/image`	Resize & convert to JPEG

3. Session & Device Tracking

Every login in LaraFoundry creates a UserSession record:

$user->userSessions()->create([
    'session_id'       => $request->session()->getId(),
    'ip_address'       => $request->getClientIp(),
    'login_method'     => $provider,  // 'google', 'facebook', 'form'
    'user_agent'       => $request->userAgent(),
    'last_activity'    => now(),
    'user_device_type' => $this->getUserDeviceType(),  // desktop/tablet/mobile
    'user_device_name' => Agent::device(),              // e.g., 'Macintosh'
    'user_os'          => Agent::platform(),            // e.g., 'macOS'
    'user_browser'     => Agent::browser(),             // e.g., 'Chrome'
]);

Device detection is handled by jenssegers/agent - a wrapper around Mobiledetect with a clean API.

What this enables

Security: Show users "Active Sessions" with device details (like GitHub does)
Analytics: Which devices are your users on? Do you need a mobile-optimized experience?
Support: "I can see you last logged in from Chrome on Windows at 3:42 PM - was that you?"
Compliance: GDPR access logs with full context

4. Auth Event Logging

This is the feature I wish I'd built from Day 1 in my first SaaS.

LaraFoundry uses spatie/laravel-activitylog with a declarative configuration:

// ActivityLogServiceProvider.php
protected array $events = [
    Registered::class     => ['Auth', 'New user registered', 200],
    Login::class          => ['Auth', 'Login', 200],
    Logout::class         => ['Auth', 'Logout', 200],
    Failed::class         => ['Auth', 'Login failed', 401],
    ProfileUpdate::class  => ['Auth', 'Profile update', 200],
    PasswordUpdate::class => ['Auth', 'Password update', 200],
    PasswordReset::class  => ['Auth', 'Password reset', 200],
];

public function boot()
{
    foreach ($this->events as $eventClass => [$group, $description, $code]) {
        Event::listen($eventClass, function ($event) use ($eventClass, $group, $description, $code) {
            ActivityLogService::logActivity(
                $event,
                class_basename($eventClass),
                $group,
                $description,
                $code
            );
        });
    }
}

The design

Declarative: Adding a new event = one line in the array
Grouped: Events belong to groups (Auth, Company, Tickets...) for filtering
HTTP-code aligned: Success = 200, failure = 401/500
Extensible: Events can implement getLogProperties() for custom data

Each log entry captures

User info (email, ID)
IP address
Device type, name, OS, browser
Route name + HTTP method
Full URL
Response code
Geo location (country, city)
Timestamp

Real-world value

Suspicious activity: 5 failed logins from a new country → trigger alert
OAuth analytics: 73% Google, 20% form, 7% Facebook → invest in Google UX
GDPR compliance: Full audit trail of who accessed what, when, from where
Support debugging: Instantly see a user's auth history when they report issues

5. Team Onboarding

In a B2B SaaS, registration doesn't end at "create account." Users often join through team invitations.

LaraFoundry handles this seamlessly:

// Works for both form registration and OAuth
private function acceptInvitation(string $token, User $user): void
{
    $invitation = CompanyInvitation::where('token', $token)
        ->with(['company', 'role'])
        ->first();

    if (!$invitation || !$invitation->canBeAccepted()) return;

    // CRITICAL: Prevent email spoofing
    if ($user->email !== $invitation->email) return;

    DB::transaction(function () use ($user, $invitation) {
        $invitation->company->addEmployee($user, $invitation->invited_by, $invitation->role);
        $invitation->markAsAccepted();
        event(new EmployeeInvitationAccepted($user, $invitation, $invitation->company));
    });
}

The flow

Admin sends invitation → generates unique token
Invitee clicks link → registers or logs in (form or OAuth)
Registration detects invitation token
Validates email match (security)
Adds user to company with assigned role
Fires event for downstream processing (notifications, logging)

Tech Stack Summary

Layer	Technology	Version
Backend	Laravel	12.x
PHP		8.3
Frontend	Vue 3 + Inertia v2	3.x / 2.x
OAuth	Laravel Socialite	^5.23
Avatars	Gravatar + Laravolt Avatar	~1.0 / ^6.2
Logging	Spatie Activity Log	^4.10
Device Detection	Jenssegers Agent	^2.6
Image Processing	Intervention Image	latest
QR Codes	SimpleQRCode	^4.2

6. Testing - Proof It Works

A registration module without tests is just a demo. Here's how I prove it works with Pest PHP.

Company creation flow:

it('user can create company with step 1 (basic info)', function () {
    Event::fake([CompanyCreate::class]);

    $response = $this->withCookie($cookieName, $sessionId)
        ->post(route('new_company.create.step1'), [
            'name' => 'Test Company',
            'country' => 'ukraine',
        ]);

    $response->assertRedirect();
    $this->assertDatabaseHas('companies', [
        'name' => 'Test Company',
        'created_by_id' => $user->id,
    ]);

    $company = Company::where('name', 'Test Company')->first();
    expect($company->uuid)->not->toBeNull();
    expect($company->slug)->toContain('test-company');

    $this->assertDatabaseHas('company_user', [
        'company_id' => $company->id,
        'user_id' => $user->id,
        'is_owner' => true,
    ]);

    Event::assertDispatched(CompanyCreate::class);
});

Email verification:

test('email can be verified', function () {
    $user = User::factory()->unverified()->create();
    Event::fake();

    $verificationUrl = URL::temporarySignedRoute(
        'verification.verify',
        now()->addMinutes(60),
        ['id' => $user->id, 'hash' => sha1($user->email)]
    );

    $this->actingAs($user)->get($verificationUrl);

    Event::assertDispatched(Verified::class);
    expect($user->fresh()->hasVerifiedEmail())->toBeTrue();
});

test('email is not verified with invalid hash', function () {
    $user = User::factory()->unverified()->create();

    $verificationUrl = URL::temporarySignedRoute(
        'verification.verify',
        now()->addMinutes(60),
        ['id' => $user->id, 'hash' => sha1('wrong-email')]
    );

    $this->actingAs($user)->get($verificationUrl);
    expect($user->fresh()->hasVerifiedEmail())->toBeFalse();
});

Edge cases:

it('step 1 generates unique slug when company name exists', function () {
    // Two companies with name "Duplicate Company"
    // Must get different slugs
    expect($company1->slug)->not->toBe($company2->slug);
});

it('sends company created email notification after step 1', function () {
    Queue::fake();
    // ...
    Queue::assertPushed(SendCompanyCreatedJob::class);
});

it('does not include sessions from other users', function () {
    // Session isolation test
    $sessions = collect($response->getData()['user']['user_sessions']);
    expect($sessions->pluck('session_id'))
        ->not->toContain('other-user-session');
});

What the test suite covers:

Registration form (render, create, authenticate)
Email verification (valid hash, invalid hash, signed URLs)
Company creation (4-step flow, events, emails, slug uniqueness)
Session isolation (no cross-user leaks)
Invitation flow (job dispatch, promo codes)
Password reset (token-based flow)

What's Next

LaraFoundry is being built in public, module by module. Each module gets extracted from production code running on Kohana.io.

Coming up:

Roles & Permissions
Multi-tenancy & Team Management
Activity Logging (the full system)
Subscription & Billing

Want to follow along?

Join the waitlist: larafoundry.com
Follow on Twitter/X: @d_isaenko_dev
Connect on LinkedIn: Dmitry Isaenko

LaraFoundry is not a starter kit. It's a production-proven SaaS engine - extracted from a real product, battle-tested with real users. Build faster. Ship sooner. Focus on what makes your SaaS unique.

Solving Flaky Session Tests in Laravel: From Chaos to Stability

Dmitry Isaenko — Wed, 28 Jan 2026 16:13:08 +0000

The Problem: Flaky Tests That Drive You Crazy

Picture this: You're building a multi-tenant Laravel CRM with custom session tracking. You have a UserSession model that stores active company context, last activity, and device info. You write tests. They pass. You run them again. They fail. You run them a third time. They pass.

Welcome to flaky test hell 🔥

Understanding the Root Cause

In our application, we have middleware that checks for active user sessions:

// CheckSessionExists middleware
public function handle($request, Closure $next)
{
    if (Auth::check()) {
        $sessionExists = UserSession::where('user_id', Auth::id())
            ->where('session_id', session()->getId())
            ->exists();

        if (!$sessionExists) {
            Auth::logout();
            return redirect()->route('login');
        }
    }

    return $next($request);
}

Simple, right? But when testing features protected by this middleware, our tests would randomly fail because the UserSession record couldn't be found.

First Attempt: The Naive Approach

function actingAsWithSession($user)
{
    $sessionId = Str::random(40);
    session()->setId($sessionId);
    session()->start();

    test()->actingAs($user);

    DB::table('user_sessions')->insert([
        'user_id' => $user->id,
        'session_id' => $sessionId,
        'active_company_id' => null,
        'ip_address' => '127.0.0.1',
        'last_activity' => now(),
        'created_at' => now(),
        'updated_at' => now(),
    ]);

    return $sessionId;
}

Why This Failed

it('can access protected route', function () {
    $user = User::factory()->create();
    actingAsWithSession($user); // Creates session with ID "abc123"

    $response = $this->get('/dashboard'); // Laravel creates NEW session!

    $response->assertOk(); // FAILS - middleware can't find UserSession
});

The Issue: Each HTTP request ($this->get(), $this->post(), etc.) in Pest/PHPUnit creates a fresh application instance. Without proper session persistence, Laravel generates a new session ID, making our UserSession record orphaned.

Second Attempt: Static Session ID

function actingAsWithSession($user)
{
    static $staticSessionId = null;

    if ($staticSessionId === null) {
        $staticSessionId = Str::random(40);
    }

    session()->setId($staticSessionId);
    session()->start();
    test()->actingAs($user);

    session()->save(); // Key addition!

    UserSession::updateOrCreate(
        ['session_id' => $staticSessionId],
        [
            'user_id' => $user->id,
            'active_company_id' => null,
            'ip_address' => '127.0.0.1',
            'last_activity' => now(),
        ]
    );

    return $staticSessionId;
}

The Breakthrough (and New Problem)

Adding session()->save() was crucial - it forces Laravel to persist session data to the configured driver (file/redis/database).

But now we hit a different wall:

it('admin and user can coexist', function () {
    $admin = User::factory()->admin()->create();
    $user = User::factory()->create();

    actingAsWithSession($admin); // Sets static session ID "xyz789"
    actingAsWithSession($user);  // REUSES SAME "xyz789"!

    // Both users now share the same session - chaos!
});

Problem: The static variable is shared across the entire test suite. Multiple users = session collision.

Final Solution: User-Scoped Session Management

function actingAsWithSession($user)
{
    // Key insight: Index sessions by user ID
    static $sessionIds = [];

    if (!isset($sessionIds[$user->id])) {
        $sessionIds[$user->id] = Str::random(40);
    }

    $sessionId = $sessionIds[$user->id];

    session()->setId($sessionId);
    session()->start();

    test()->actingAs($user);

    // CRITICAL: Add data to ensure session is written
    session()->put('auth_check', true);
    session()->save();

    UserSession::updateOrCreate(
        ['session_id' => $sessionId],
        [
            'user_id' => $user->id,
            'ip_address' => '127.0.0.1',
            'last_activity' => now(),
        ]
    );

    return $sessionId;
}

Why This Works

User Isolation: Each user gets their own session ID stored in $sessionIds[$user->id]
Session Persistence: Calling session()->save() writes to the driver
Data Guarantee: Adding a marker (auth_check) ensures non-empty session data gets saved
Eloquent Integration: Using updateOrCreate() instead of raw query handles updates gracefully

Real-World Usage

it('redirects blocked users from dashboard', function () {
    $user = User::factory()->blocked()->create();
    actingAsWithSession($user);

    $response = $this->get(route('dashboard'));

    $response->assertRedirect(route('user_blocked'));
});

it('allows multiple user contexts in same test', function () {
    $admin = User::factory()->admin()->create();
    $user = User::factory()->create();

    // Each gets their own session
    actingAsWithSession($admin);
    $adminSession = session()->getId();

    actingAsWithSession($user);
    $userSession = session()->getId();

    expect($adminSession)->not->toBe($userSession);
});

Critical Configuration: phpunit.xml

Don't forget to set the session driver correctly:

<php>
    <env name="SESSION_DRIVER" value="file"/>
    <!-- NOT "array" - file/redis/database ensure persistence -->
</php>

Using array driver in tests will cause sessions to not persist between requests!

Results

✅ 100% test pass rate (previously ~60-70% due to flakiness)
✅ Stable CI/CD pipeline (no more random failures)
✅ Multi-user test scenarios work reliably
✅ Team confidence in test suite restored

Key Takeaways

Understand Laravel's test lifecycle: Each HTTP request creates a new app instance
Session persistence matters: Always session()->save() when testing session-dependent features
Scope your static data: Use arrays indexed by entity ID, not single static values
Choose the right driver: File/redis/database drivers persist; array driver doesn't
Test determinism: If a test passes sometimes and fails others, you have a state management issue

Bonus: Testing Custom Middleware

With stable sessions, testing our session-checking middleware became trivial:

it('logs out users with invalid sessions', function () {
    $user = User::factory()->create();
    test()->actingAs($user); // NO UserSession record

    $response = $this->get('/dashboard');

    $response->assertRedirect(route('login'));
    expect(Auth::check())->toBeFalse();
});

it('allows users with valid sessions', function () {
    $user = User::factory()->create();
    actingAsWithSession($user); // CREATES UserSession

    $response = $this->get('/dashboard');

    $response->assertOk();
    expect(Auth::check())->toBeTrue();
});

Resources

Have you encountered similar testing challenges? Share your war stories in the comments! 👇

This article is based on real debugging experience in a production Laravel 12 + Vue 3 + Inertia.js CRM system. The complete test suite is available in our open-source project.

Building Multi-Tenant SaaS with Laravel: The LaraFoundry Way

Dmitry Isaenko — Tue, 20 Jan 2026 12:40:42 +0000

Over the past few weeks, I've been building LaraFoundry - a modular SaaS engine for Laravel. The biggest challenge? Getting multi-tenancy right.

In this article, I'll share my approach: database structure, automatic isolation with traits, and comprehensive testing strategies.

The Multi-Tenancy Challenge

When building SaaS applications, you need to isolate data between tenants (companies, organizations, accounts). Get it wrong, and Company A might see Company B's data. 😱

There are three main approaches:

Separate databases per tenant - Full isolation, complex operations
Separate schemas per tenant - Medium isolation, medium complexity
Shared database, row-level isolation - Simple operations, requires discipline

For LaraFoundry, I chose option 3. Here's why.

Why Shared Database?

Pros:

✅ Simpler operations (one database to manage)
✅ Better for 100-1000 tenants
✅ Cost-effective
✅ Easier backups and migrations
✅ Cross-tenant reporting (for admins)

Cons:

⚠️ Requires careful coding (no manual filtering!)
⚠️ Global scopes are critical
⚠️ Testing is essential

For Kohana (my testing ground for LaraFoundry), shared database made sense. If I needed to scale to 10,000+ tenants, I'd reconsider.

Database Schema

Here's the core structure:

CREATE TABLE companies (
    id BIGINT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    subdomain VARCHAR(100) UNIQUE,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    company_id BIGINT NOT NULL,
    name VARCHAR(255),
    email VARCHAR(255),
    FOREIGN KEY (company_id) REFERENCES companies(id) ON DELETE CASCADE,
    UNIQUE(company_id, email),
    INDEX(company_id)
);

CREATE TABLE orders (
    id BIGINT PRIMARY KEY,
    company_id BIGINT NOT NULL,
    user_id BIGINT,
    total DECIMAL(10,2),
    FOREIGN KEY (company_id) REFERENCES companies(id) ON DELETE CASCADE,
    INDEX(company_id, created_at)
);

Key decisions:

company_id on every tenant-scoped table - Non-nullable
Foreign keys with CASCADE - Delete company = delete all data
Composite indexes - (company_id, created_at) for performance
Unique constraints - (company_id, email) prevents duplicates within company

The BelongsToCompany Trait

Manual where('company_id', ...) everywhere is error-prone. One mistake = data leak.

Solution: Global scopes via a trait.

<?php

namespace App\Traits;

use Illuminate\Database\Eloquent\Builder;

trait BelongsToCompany
{
    protected static function bootBelongsToCompany(): void
    {
        static::addGlobalScope('company', function (Builder $builder) {
            if (auth()->check() && auth()->user()->company_id) {
                $builder->where(
                    $builder->getModel()->getTable() . '.company_id',
                    auth()->user()->company_id
                );
            }
        });
    }

    public function company()
    {
        return $this->belongsTo(Company::class);
    }

    public function scopeForCompany(Builder $query, int $companyId): Builder
    {
        return $query->withoutGlobalScope('company')
            ->where($this->getTable() . '.company_id', $companyId);
    }
}

Usage:

class Order extends Model
{
    use BelongsToCompany;  // ← One line!
}

// Now ALL queries are automatically filtered:
Order::all();  // Only current company's orders
Order::find(1);  // Only if it belongs to current company

Admin queries:

// See all orders across companies
Order::withoutGlobalScope('company')->get();

// Or use dedicated scope
Order::forCompany(5)->get();

The Relationship Gotcha

Global scopes don't auto-apply to relationships. This is a common pitfall:

$order = Order::find(1);  // ✅ Filtered by company
$order->items;  // ⚠️ Might include other companies' items!

Solution: Explicitly scope relationships:

// In Order model
public function items()
{
    return $this->hasMany(OrderItem::class)
        ->where('company_id', auth()->user()->company_id);
}

// Or use a scope
public function items()
{
    return $this->hasMany(OrderItem::class)->forCompany();
}

Explicit is better than implicit for multi-tenancy.

Testing Multi-Tenancy

This is critical. I have 47 tests dedicated to tenant isolation.

Here's a sample with Pest PHP:

it('filters orders by company', function () {
    // Arrange: Create two companies with data
    $companyA = Company::factory()->create();
    $companyB = Company::factory()->create();

    $orderA = Order::factory()->for($companyA)->create();
    $orderB = Order::factory()->for($companyB)->create();

    // Act: Login as user from Company A
    actingAs(User::factory()->for($companyA)->create());

    // Assert: Should only see Company A's order
    expect(Order::count())->toBe(1)
        ->and(Order::first()->id)->toBe($orderA->id);
});

it('prevents cross-company access', function () {
    $companyA = Company::factory()->create();
    $companyB = Company::factory()->create();

    $orderB = Order::factory()->for($companyB)->create();

    actingAs(User::factory()->for($companyA)->create());

    // Should not find Company B's order
    expect(Order::find($orderB->id))->toBeNull();
});

Test categories I use:

Isolation tests - Company A can't see Company B's data
Relationship tests - Relationships are properly scoped
Admin tests - Admins can bypass scopes when needed
Performance tests - Queries use proper indexes

Lessons Learned

1. Start with tests

Write multi-tenancy tests FIRST, before implementing features. It's your safety net.

2. Use database constraints

Don't rely solely on Laravel. Add NOT NULL and foreign keys at the database level.

3. Explicit > implicit for relationships

Global scopes are great, but explicitly scope relationships. Better safe than sorry.

4. Monitor query performance

Composite indexes (company_id, id) are essential. Use Laravel Debugbar or Telescope.

5. Document assumptions

Write comments like // Automatically filtered by BelongsToCompany trait. Future you will thank past you.

What's Next

For LaraFoundry, I'm now working on:

Role-based permissions (multi-tenant aware)
Activity logging (per company)
API versioning with tenant context

Follow my journey on X/Twitter where I share daily updates, code snippets, and challenges.

Building in public has been incredible - the Laravel community is amazing!

Questions? Drop a comment below! 💬

Resources

This article is part of my Building in Public series on creating LaraFoundry, a modular SaaS engine for Laravel. Follow along on X for updates!

Forem: Dmitry Isaenko

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

The Middleware Stack

Middleware Deep-Dives

SetActiveCompanyMiddleware - Company Context Resolution

CheckPinLockMiddleware - Inactivity Screen Lock

CheckAccessMiddleware - Three-Level Access Control

SetLocale - Language Detection Chain

UpdateLastSessionActivityMiddleware - Activity + Device Tracking

Session Validation - Anti-Hijacking

Custom Traits

HasPagination

Filter Auto-Discovery

NotificationDataHandler

HasUserFilterRules (Companion to NotificationDataHandler)

LogsActivity (Audit Trail)

How They Work Together

Testing

Design Principles

laravel #php #saas #middleware #larafoundry

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

The Problem

Architecture Overview

The LayoutSwitcher Pattern

The Overlay System

State Management (No Library)

Overlay Logic

Child Component Communication

Transition Animations

Pagination + Filter Architecture

Backend: HasPagination Trait

Frontend: PagePaginator Component

Filter Auto-Discovery Pattern

Frontend Filter Integration

Modal & Popup System

Custom Form Modal (Inertia useForm)

Async Data-Loading Modal

SweetAlert2 for Confirmations

Layout-Level Modal Orchestration

Full Inertia Wiring

Blade Template

app.js Entry Point

Shared Props (Middleware)

Vite Aliases

Testing

Directory Structure

What's Included

Key Takeaway

laravel #vue #inertia #saas #larafoundry

Building a Dynamic, Permission-Aware Navigation System for Multi-Tenant Laravel SaaS

The Problem

Architecture Overview

Backend: LayoutDataService

Menu Item Structure

Permission Filtering

Three User Types, Three Menus

Sub-Menu Routing

The First Allowed Route (FAR) Pattern

User-Configurable Default Page

Data Flow to Frontend

Frontend: Desktop Navigation

Frontend: Mobile Navigation

Right-Side Pullout

State Management

Testing

What's Included

Key Takeaway

Building a Production-Grade Multilanguage System for Laravel SaaS (with Inertia + Vue)

The Problem

Architecture Overview

Backend: The Locale Detection Chain

For Authenticated Users

For Guest Users

Language Switching

Translation Files Structure

Frontend: Laravel to Vue via Inertia

Sharing Translations via Inertia Props

Vue i18n Setup

Using Translations in Components

Language Switcher Component