DEV Community: Dmitry Isaenko

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

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

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

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

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

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

Dual Architecture

LaraFoundry has two notification types that coexist in one system:

Admin notifications - created manually in the admin panel:

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

System notifications - created programmatically by queued jobs:

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

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

Database Schema

Notifications Table

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

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

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

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

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

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

Notification-User Pivot

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

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

Model

class Notification extends Model
{
    use HasFactory;

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

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

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

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

Multilingual Content

The same getLocalizedTitle() method handles both notification types:

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

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

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

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

Auto-Translate in Admin Panel

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

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

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

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

Recipient Segmentation

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

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

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

Recipients matching filters: 847 users

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

Filter Implementation

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

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

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

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

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

Admin CRUD and Workflow

Routes

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

Workflow

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

The form request validates everything:

class AdminNotificationStoreRequest extends FormRequest
{
    use HasUserFilterRules;

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

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

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

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

System Notifications

System notifications are created by queued jobs when events happen:

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

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

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

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

System Notification Triggers

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

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

Delivery and Read Statistics

The admin panel shows per-notification statistics:

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

All computed from the pivot table:

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

Visibility Status

Computed from timestamps, displayed as a colored badge:

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

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

Frontend UX

User Notification Panel

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

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

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

Real-Time Unread Count

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

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

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

Bulk Operations

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

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

One query regardless of notification count.

User API Endpoints

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

Admin Creation Form

Three sections:

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

The form is disabled for sent notifications except resend action.

Testing

Notifications get tested end-to-end with Pest:

CRUD

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

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

Segmentation

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

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

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

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

Read Tracking

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

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

System Notifications

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

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

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

Design Decisions

Why One Table Instead of Two?

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

Why JSON Translations Instead of a Translations Table?

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

Why Polling Instead of WebSockets?

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

Why Auto-Mark-as-Read on Expand?

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

Why Exclude Admin From Recipients?

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

What's Next

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

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

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

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

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

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

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

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

Company Dashboard

What the Admin Sees

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

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

The Query

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

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

Key decisions:

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

AdminCompanyResource

The resource does heavy lifting:

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

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

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

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

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

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

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

Subscription Status Engine

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

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

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

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

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

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

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

Each status gets a visual indicator in the admin panel:

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

Company Model Access Methods

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

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

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

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

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

Blocking System

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

GetBlockStatusAction

The single source of truth for access status:

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

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

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

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

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

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

        return $status;
    }
}

Three blocking scenarios with clear priority:

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

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

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

CheckAccessMiddleware

Enforces blocking at the request level:

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

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

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

        return $next($request);
    }
}

Banned user whitelist - even banned users can access:

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

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

Gates

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

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

Subscription Expiry Notifications

The system warns users before blocking them.

Scheduled Command

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

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

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

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

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

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

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

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

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

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

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

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

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

Frontend Blocked Pages

CompanyBlocked.vue

One component handles all three blocking scenarios:

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

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

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

Inertia Shared Props

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

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

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

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

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

Payment Model

CompanyPayment

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

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

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

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

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

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

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

Events

Every successful payment fires CompanyPaymentProcessed:

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

Full audit trail. Every dollar tracked.

Admin View

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

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

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

Admin Filtering and Search

AdminCompaniesFilter

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

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

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

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

Validation

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

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

Quick Search

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

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

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

Testing

Subscription Status

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

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

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

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

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

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

Ban Cascade

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

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

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

Payment Events

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

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

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

Expiry Notifications

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

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

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

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

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

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

Admin Filtering

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

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

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

Design Decisions

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

What's Next

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

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

Follow for the next module deep-dive.

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

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

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

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

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

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

CRUD Architecture

Create

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

Validated fields:

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

Password handling:

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

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

Social links are validated as an array:

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

Read (Index)

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

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

Three key decisions here:

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

What the Admin Sees Per User

Every row in the admin users table shows:

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

The UserResource handles all transformation:

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

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

Update

Social links are managed in a database transaction:

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

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

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

Email uniqueness on update ignores the current user:

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

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

Delete (Soft)

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

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

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

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

Restoring is the reverse: clear user_deleted_at.

Ban System

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

Block Reasons (Config-Driven)

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

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

Block Flow

When an admin clicks "Block":

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

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

Access Enforcement

CheckAccessMiddleware runs on every authenticated request. Three levels:

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

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

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

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

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

Blocked User Page

The blocked user sees their ban reason and date:

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

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

Unblock

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

Event Logging

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

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

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

Impersonation

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

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

Implementation

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

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

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

Frontend Awareness

Every page knows if impersonation is active:

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

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

Security

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

UI

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

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

Activity Logging

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

What Gets Stored

Extended Spatie's Activity model with CustomActivity:

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

Plus custom event properties in the properties JSON column.

Logging Flow

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

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

Admin UI - User Activity Log

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

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

Table with interactive tooltips:

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

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

General Activity Log

Route: GET /admin/logs?hours=24

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

Data Transformation

ActivityLogResource prepares the data:

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

Search and Filtering

Multi-Field Search

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

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

Filter Auto-Discovery

Same pattern from the Traits & Middlewares module:

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

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

Validation

Every filter parameter goes through AdminUserFilterRequest:

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

Real-Time Search

Separate endpoint: GET /admin/users/search

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

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

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

Testing

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

CRUD

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

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

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

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

Ban Cascade

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

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

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

Events & Jobs

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

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

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

Impersonation

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

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

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

Design Decisions

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

What's Next

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

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

Follow for the next module deep-dive.

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

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

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

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

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

The Middleware Stack

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

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

Why order matters:

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

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

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

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

Middleware Deep-Dives

SetActiveCompanyMiddleware - Company Context Resolution

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

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

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

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

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

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

Resolution priority:

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

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

CheckPinLockMiddleware - Inactivity Screen Lock

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

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

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

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

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

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

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

    return $next($request);
}

Design decisions:

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

CheckAccessMiddleware - Three-Level Access Control

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

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

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

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

    return $next($request);
}

Three levels with specific route whitelists:

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

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

SetLocale - Language Detection Chain

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

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

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

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

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

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

Config-driven mappings:

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

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

UpdateLastSessionActivityMiddleware - Activity + Device Tracking

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

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

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

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

    $agent = new Agent();

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

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

    return $response;
}

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

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

Session Validation - Anti-Hijacking

Two middlewares work together:

CheckSessionExists - validates session for all requests:

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

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

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

CheckForSessionValidity - additional cleanup for browser requests:

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

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

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

Custom Traits

HasPagination

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

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

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

Controller usage:

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

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

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

Filter Auto-Discovery

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

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

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

Concrete example:

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

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

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

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

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

NotificationDataHandler

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

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

HasUserFilterRules (Companion to NotificationDataHandler)

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

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

LogsActivity (Audit Trail)

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

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

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

How They Work Together

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

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

Testing

Behavior-driven tests using Pest:

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

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

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

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

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

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

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

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

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

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

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

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

Design Principles

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

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

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

laravel #php #saas #middleware #larafoundry

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

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

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

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

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

The Problem

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

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

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

Architecture Overview

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

The LayoutSwitcher Pattern

The core of the system is LayoutSwitcher.vue:

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

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

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

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

The assignment happens in app.js:

resolve: async (name) => {
    const pages = import.meta.glob('./pages/**/*.vue');
    let module = await pages[`./pages/${name}.vue`]();
    let page = module.default;
    page.layout = page.layout || LayoutSwitcher;
    return page;
}

Every page automatically gets LayoutSwitcher unless it explicitly defines its own layout. Pages don't import layouts. Pages don't know which layout wraps them.

The Overlay System

A production SaaS layout isn't just a header and a sidebar. The authenticated layout in Kohana.io has 7 pullout panels:

Mobile menu (slides from left)
Right profile menu (slides from right)
Notifications panel
Language selector
Company switcher
Contragent filter drawer
Product filter drawer

And they stack. Opening the language selector while the mobile menu is open creates a double overlay - two backdrop layers, independently dismissable.

State Management (No Library)

// AuthLayout.vue - all overlay state
const viewPulloutMobilemenu = ref(false);
const viewPulloutMenuRight = ref(false);
const viewPulloutNotifications = ref(false);
const viewPulloutMenuChangeLanguage = ref(false);
const viewPulloutMenuChangeCompany = ref(false);
const viewPulloutContragentFilter = ref(false);
const viewPulloutProductFilter = ref(false);
const viewOverlay = ref(false);
const viewDoubleOverlay = ref(false);
const viewModalWrapper = ref(false);

Plain reactive refs. No Vuex store. No Pinia. No event bus.

Overlay Logic

Opening any pullout → shows single overlay + disables body scroll via document.body.classList.add('non-overflow')
Opening a second panel on top → shows double overlay
ESC key → dismisses top layer first using onKeyStroke from @vueuse/core
Clicking backdrop → closes everything
CSS transitions: 0.3s for single overlay, 0.1s for double (feels snappy)

Child Component Communication

Pages deep in the component tree trigger layout overlays via provide/inject:

// AuthLayout.vue (parent)
provide('showPulloutContragentFilter', showPulloutContragentFilter);
provide('showViewContragentModal', showViewContragentModal);

// ContragentsList.vue (child page)
const showFilter = inject('showPulloutContragentFilter');

The page calls showFilter(). The layout handles z-indexes, backdrops, body scroll, and transition timing. Clean separation.

Transition Animations

.overlay-enter-active, .overlay-leave-active {
    transition: opacity 0.3s ease;
}
.overlay-enter-from, .overlay-leave-to {
    opacity: 0;
}

/* Pullout menus use GPU-accelerated transforms */
.pullout-menu__left {
    will-change: transform;
    transform: translateZ(0);
    backface-visibility: hidden;
    transition: transform 0.3s ease;
}

CSS-only animations. GPU-accelerated for mobile. No JavaScript animation libraries.

Pagination + Filter Architecture

Backend: HasPagination Trait

Every controller that paginates uses the same trait:

trait HasPagination
{
    protected function getPaginationData($paginator): array
    {
        return [
            'current_page' => $paginator->currentPage(),
            'last_page'    => $paginator->lastPage(),
            'per_page'     => $paginator->perPage(),
            'total'        => $paginator->total(),
            'from'         => $paginator->firstItem(),
            'to'           => $paginator->lastItem(),
        ];
    }
}

Controller usage:

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

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

.withQueryString() is critical - it preserves all filter parameters when generating pagination links.

Frontend: PagePaginator Component

The paginator component lives in the layout, not in pages. AppMainContentLayout.vue auto-renders it when pagination data exists:

const isPaginationPresent = computed(() => {
    const total = page.props.pagination?.total ?? 0;
    const perPage = page.props.pagination?.per_page ?? 0;
    return total > perPage;
});

The component rebuilds pagination links while preserving all current query parameters:

const queryString = computed(() => {
    const url = new URL(window.location.href);
    url.searchParams.delete('page');
    const qs = url.searchParams.toString();
    return qs ? `&${qs}` : '';
});

// Smart page range: max 7 buttons + ellipsis
const pages = computed(() => {
    const total = p.value.last_page;
    const current = p.value.current_page;
    if (total <= 7) return Array.from({ length: total }, (_, i) => i + 1);
    if (current <= 4) return [1, 2, 3, 4, 5, '...', total];
    if (current >= total - 3) return [1, '...', total-4, total-3, total-2, total-1, total];
    return [1, '...', current-1, current, current+1, '...', total];
});

Each page button uses Inertia's <Link> for SPA navigation:

<Link :href="`?page=${item}&${queryString}`">{{ item }}</Link>

Country filter active? Preserved. Sort direction? Preserved. Search query? Preserved. No state management needed.

Filter Auto-Discovery Pattern

The filter system uses method auto-discovery:

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

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

Concrete filter example:

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

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

Whitelisted sort columns prevent SQL injection. Word-by-word search matching. Alphabetical navigation via starts_with() method. Quick filter presets for products (min_stock, has_reserved).

Frontend Filter Integration

// Inertia router navigation with state preservation
const performSearch = () => {
    const params = {};
    if (filters.value.search) params.search_string = filters.value.search;
    if (filters.value.country) params.country = filters.value.country;
    // ... all filter params

    router.get(route(routeName.value), params, {
        preserveState: true,    // Component state survives
        preserveScroll: true,   // Scroll position maintained
        replace: true,          // Single history entry
    });
};

preserveState: true is the key. Component reactive state persists across Inertia navigations. No need to store filters in a Vuex store or local storage.

Modal & Popup System

LaraFoundry uses a hybrid approach: custom modals for complex interactions, SweetAlert2 for confirmations.

Custom Form Modal (Inertia useForm)

<script setup>
import { useForm } from '@inertiajs/vue3';

const form = useForm({ email: '', role_id: '' });

const submit = () => {
    form.post(route('my_company.employees.invite'), {
        preserveScroll: true,
        onSuccess: () => emit('invited'),
    });
};
</script>

<template>
    <Transition name="modal">
        <div class="modal-overlay" @click.self="emit('close')">
            <div class="modal">
                <form @submit.prevent="submit">
                    <InputField v-model="form.email" :class="{ 'input--error': form.errors.email }" />
                    <span v-if="form.errors.email">{{ form.errors.email }}</span>
                    <button type="submit" :disabled="form.processing">
                        {{ form.processing ? t('Sending...') : t('Send') }}
                    </button>
                </form>
            </div>
        </div>
    </Transition>
</template>

form.processing disables the submit button. form.errors shows server-side validation. onSuccess closes the modal. Three features, zero custom code.

Async Data-Loading Modal

const loading = ref(false);
const contragent = ref(null);

watch(() => props.visible, (newVal) => {
    if (newVal && props.contragentUuid) {
        fetchContragentData();
    }
});

const fetchContragentData = async () => {
    loading.value = true;
    try {
        const response = await axios.get(route('contragents.view_data', props.contragentUuid));
        contragent.value = response.data.contragent;
    } catch (err) {
        error.value = t('Failed to load data');
    } finally {
        loading.value = false;
    }
};

Data fetched only when modal becomes visible. Loading spinner. Error state. Tabs for different data views. ESC key to close.

SweetAlert2 for Confirmations

const result = await Swal.fire({
    title: t('Remove Employee?'),
    text: t('This action will immediately remove the employee.'),
    icon: 'error',
    showCancelButton: true,
    confirmButtonColor: '#ef4444',
});

if (result.isConfirmed) {
    router.delete(route('my_company.employees.remove', employee.id));
}

One await. No custom component. Accessible. Styled.

Layout-Level Modal Orchestration

Generic modals are managed in the layout via provide/inject:

// AuthLayout.vue
const modal = reactive({
    view: false,
    title: t('Confirm the action'),
    content: null,
    targetUrl: null,
    modalType: 'confirmable',
});

provide('showViewContragentModal', showViewContragentModal);

Pages inject trigger functions. The layout handles z-indexes, overlay stacking, and transition timing.

Full Inertia Wiring

Blade Template

<head>
    <title inertia>{{ config('app.name') }}</title>
    @vite(['resources/js/app.js', 'resources/css/app.css'])
    @inertiaHead
    @routes
</head>
<body>
    @inertia
</body>

@routes dumps Ziggy routes. @inertiaHead enables dynamic head management from Vue. @inertia mounts the SPA.

app.js Entry Point

createInertiaApp({
    title: (title) => `${title} - ${appName}`,

    resolve: async (name) => {
        const pages = import.meta.glob('./pages/**/*.vue');
        let module = await pages[`./pages/${name}.vue`]();
        let page = module.default;
        page.layout = page.layout || LayoutSwitcher;
        return page;
    },

    setup({ el, App, props, plugin }) {
        const i18n = createI18n({
            legacy: false,
            locale: pageProps.locale || 'en',
            messages: { [locale]: translations },
        });

        createApp({ render: () => h(App, props) })
            .use(plugin)
            .use(i18n)
            .use(ZiggyVue)
            .component('Head', Head)
            .component('Link', Link)
            .mount(el);

        // Global translation function
        app.config.globalProperties.t = (...args) => i18n.global.t(...args);
        globalThis.t = (...args) => i18n.global.t(...args);
    },

    progress: { delay: 0, color: '#3b82f6', showSpinner: false },
});

Key decisions:

import.meta.glob - Vite code-splits every page. Only the current page is loaded.
Global t() function - registered on both globalProperties (Options API) and globalThis (Composition API). No imports needed anywhere.
Progress bar delay: 0 - appears immediately on navigation. Users see instant feedback.

Shared Props (Middleware)

public function share(Request $request): array
{
    return [
        'layout'          => fn () => $layout->getLayout(),       // lazy
        'flash'           => fn () => session messages,            // lazy
        'ziggy'           => [...(new Ziggy)->toArray()],
        'locale'          => fn () => App::getLocale(),
        'translations'    => fn () => merged translations,         // lazy
        'visitor_status'  => visitor status closure,
        'ui_settings'     => fn () => user UI preferences,         // lazy
    ];
}

Everything wrapped in closures for lazy evaluation. Layout data is only computed when the frontend reads page.props.layout.

Vite Aliases

resolve: {
    alias: {
        '@': path.resolve(__dirname, './resources/js'),
        '@css': path.resolve(__dirname, './resources/css'),
        '@assets': path.resolve(__dirname, './public/assets'),
        'ziggy-js': resolve(__dirname, 'vendor/tightenco/ziggy'),
    },
}

@/components/PagePaginator.vue instead of relative path chains.

Testing

Frontend behavior is tested through Pest feature tests that assert on Inertia props:

it('serves auth layout for authenticated users', function () {
    actingAs(User::factory()->create())
        ->get('/dashboard')
        ->assertInertia(fn ($page) =>
            $page->where('visitor_status', 'auth')
        );
});

it('returns pagination data with filter state', function () {
    Product::factory(30)->create(['company_id' => $company->id]);

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

it('shares flash messages via Inertia', function () {
    actingAs($user)->post('/contragents', $validData);

    actingAs($user)
        ->get('/contragents/customers')
        ->assertInertia(fn ($page) => $page->has('flash.info'));
});

it('returns contragent data for view modal', function () {
    $contragent = Contragent::factory()->create();

    actingAs($user)
        ->get(route('contragents.view_data', $contragent->uuid))
        ->assertJson(['contragent' => ['name' => $contragent->name]]);
});

The pattern: test what the server sends. If Inertia props are correct, Vue renders correctly. This covers layout switching, pagination, filters, flash messages, and modal data.

For complex interactive components (filter watchers, URL manipulation), unit tests with Vitest would supplement this. But for the majority of frontend behavior, Pest feature tests are sufficient.

Directory Structure

resources/js/
├── app.js                          # Entry point, plugins, LayoutSwitcher default
├── layouts/
│   ├── LayoutSwitcher.vue          # Dynamic layout router
│   ├── AuthLayout.vue              # Authenticated users (7 pullout menus)
│   ├── AdminLayout.vue             # Admin panel
│   ├── GuestLayout.vue             # Public + login/register modals
│   ├── AuthBlockedLayout.vue       # Blocked users
│   ├── AuthDeletedLayout.vue       # Deleted accounts
│   └── app/                        # Sub-layout components
│       ├── AppHeaderDesktopLayout.vue
│       ├── AppMainContentLayout.vue    # Wraps content + auto-renders pagination
│       ├── AppModalLayout.vue
│       ├── AppFooterLayout.vue
│       ├── AppPulloutMobilemenuLayout.vue
│       ├── AppPulloutMenuRightLayout.vue
│       ├── AppPulloutMenuNotificationsLayout.vue
│       └── ... (7 more pullout components)
├── pages/                          # Inertia pages (auto-resolved)
├── components/                     # Reusable components
│   ├── PagePaginator.vue
│   ├── contragents/ViewContragentModal.vue
│   ├── SendTestEmailModal.vue
│   └── ui/                         # Form inputs, filters, etc.
├── composables/                    # Vue composition functions
└── store/
    └── unreadCountStore.js         # Simple ref-based store

What's Included

Feature	Implementation
Layout switching	LayoutSwitcher + visitor_status prop (5 layouts)
Overlay system	7 pullout panels, double-layer stacking, ESC dismissal
Pagination	HasPagination trait + PagePaginator component (auto-render)
Filters	Auto-discovery pattern, alphabetical nav, quick presets
Modals	Custom (useForm, async axios) + SweetAlert2 (confirmations)
State management	Reactive refs + provide/inject (no Vuex/Pinia)
i18n	vue-i18n v11 with Laravel translations, global t()
Routing	Ziggy named routes in Vue templates
Code splitting	Vite import.meta.glob per page
Testing	Pest feature tests asserting Inertia props

Key Takeaway

Push complexity to the backend. Vue renders pre-computed data.

No permission checks in Vue components. No auth guards. No client-side menu filtering. No state calculations. The server sends exactly what each user type needs. The frontend renders it.

The LayoutSwitcher pattern, the overlay system, the pagination auto-rendering, the filter auto-discovery - they all follow the same principle. The backend is the source of truth. The frontend is a rendering engine.

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

GitHub: github.com/dmitryisaenko/larafoundry
Website: larafoundry.com
laravel #vue #inertia #saas #larafoundry

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.

DEV Community: Dmitry Isaenko

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

Table of Contents

Dual Architecture

Database Schema

Notifications Table

Notification-User Pivot

Model

Multilingual Content

Auto-Translate in Admin Panel

Recipient Segmentation

Filter Implementation

Admin CRUD and Workflow

Routes

Workflow

System Notifications

System Notification Triggers

Delivery and Read Statistics

Visibility Status

Frontend UX

User Notification Panel

Real-Time Unread Count

Bulk Operations

User API Endpoints

Admin Creation Form

Testing

CRUD

Segmentation

Read Tracking

System Notifications

Design Decisions

Why One Table Instead of Two?

Why JSON Translations Instead of a Translations Table?

Why Polling Instead of WebSockets?

Why Auto-Mark-as-Read on Expand?

Why Exclude Admin From Recipients?

What's Next

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

Table of Contents

Company Dashboard

What the Admin Sees

The Query

AdminCompanyResource

Subscription Status Engine

Company Model Access Methods

Blocking System

GetBlockStatusAction

CheckAccessMiddleware

Gates

Subscription Expiry Notifications

Scheduled Command

Frontend Blocked Pages

CompanyBlocked.vue

Inertia Shared Props

Payment Model

CompanyPayment

Events

Admin View

Admin Filtering and Search

AdminCompaniesFilter

Validation

Quick Search

Testing

Subscription Status

Ban Cascade

Payment Events

Expiry Notifications

Admin Filtering

Design Decisions

What's Next

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

Table of Contents

CRUD Architecture

Create

Read (Index)

What the Admin Sees Per User

Update

Delete (Soft)

Ban System

Block Reasons (Config-Driven)