Branch-Level Data Isolation in Laravel with Global Scopes (and 4 Bugs I Hit)

I built a multi-branch business system in Laravel. Each branch must only see its own invoices, clients, and payments. A global scope solved that in a few lines. Then the bugs started.

Here is the setup, and the four problems I had to fix.

The trait

trait BelongsToBranch
{
    protected static function bootBelongsToBranch(): void
    {
        static::addGlobalScope('branch', function (Builder $query) {
            $user = auth()->user();

            if (! $user || $user->isAdmin()) {
                return;
            }

            $query->where(
                $query->getModel()->getTable() . '.branch_id',
                $user->branch_id
            );
        });

        static::creating(function ($model) {
            if (auth()->check() && empty($model->branch_id)) {
                $model->branch_id = auth()->user()->branch_id;
            }
        });
    }
}

Add use BelongsToBranch; to any model, and every query is filtered automatically.

Bug 1: "Column 'branch_id' is ambiguous"

My first version used where('branch_id', ...). It broke as soon as a query joined two tables that both had branch_id.

Fix: always qualify the column with the table name, as in the trait above.

Bug 2: Shared records disappear inside relations

Some clients are shared across branches. When a branch user opened an invoice, $invoice->client returned null, because the scope also ran on the related query.

Fix: remove the scope on that specific relation:

public function client()
{
    return $this->belongsTo(Client::class)
        ->withoutGlobalScope('branch');
}

The hard part is consistency. If you remove it in one place but not in an eager load or a whereHas, the same record shows on one page and vanishes on another.

Bug 3: Queued jobs see everything

Jobs and commands run without a logged-in user. My scope returned early when there was no user, so a queued report job read data from all branches.

Fix: never rely on auth() inside jobs. Pass the branch explicitly:

Invoice::withoutGlobalScope('branch')
    ->where('branch_id', $this->branchId)
    ->get();

Bug 4: Unique validation ignores the scope

Rule::unique('invoices', 'number') queries the table directly. Global scopes don't apply, so invoice number INV-001 in branch A blocked INV-001 in branch B.

Fix: add the branch condition yourself:

Rule::unique('invoices', 'number')
    ->where('branch_id', auth()->user()->branch_id)

The same applies to raw DB::table() queries. Global scopes only work through Eloquent.

Takeaway

Global scopes are a clean way to isolate data, but they work silently. Test three cases every time: a branch user, an admin, and a queued job.

I build multi-branch and SaaS systems in Laravel. If you need one, you can find me here: [YOUR ADMIN PANEL / SAAS GIG LINK]