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]
Top comments (2)
Bug 3 is the one I would call out as the real risk, because it fails open. A scope that returns early with no user quietly turns a queued report into a cross-branch leak, and nothing in the job looks wrong while it runs. I would flip the default so that no branch context means no rows, and only an explicit branch passed into the job can open the scope again. That way a missing context fails closed and shows up in testing instead of in a customer's inbox.
Great catch, thank you. You’re right, it fails open, and the worst part is that nothing looks wrong while the job runs. I’m changing the scope so that no branch context returns no rows, and the job will receive the branch explicitly. I’ll also add a test that runs the job without a branch and checks the result is empty. For admin cases, I’ll add a separate explicit method so “see all branches” is always a deliberate choice.