Local and global scopes

01 Name the constraints you reach for

issued() and forTeam() are local. The call site shows the constraint. The scope method is named scopeIssued, and you call it as issued(). Laravel strips the prefix. The Builder argument is the query so far, and a void return adds the where without replacing that query.

class Invoice extends Model
{
    public function scopeIssued(Builder $query): void
    {
        $query->where('status', 'issued');
    }

    public function scopeForTeam(Builder $query, Team $team): void
    {
        $query->whereBelongsTo($team);
    }
}

The controller reads as the question you meant to ask. forTeam() uses whereBelongsTo(), so this scope does not type the column either. A rename of the foreign key stays inside the relationship. paginate() belongs at the call site, not inside the scope. A scope that paginates has decided the page size for every caller, including a command that wanted the whole set.

$invoices = Invoice::query()
    ->forTeam($team)
    ->issued()
    ->latest('issued_on')
    ->paginate(20);

A global scope that always adds team_id is useful only when every query has a current team, including jobs, commands and tests. If a report must cross teams, you will be calling withoutGlobalScope() and hoping you found every call site. Prefer the local scope until the omission has actually shipped a bug. The omission is obvious: the controller that forgot forTeam() returns every tenant, and a test can see that. A global scope hides the same bug inside a process that had no team to begin with.

02 Group an orWhere so it cannot escape the team

forTeam() adds a where. An orWhere() chained after it is a sibling, not a child. The SQL is team_id = ? AND status = issued OR status = paid, and the paid row of another team matches the OR. The scope did its job. The call site undid it. Put the alternative statuses inside a grouped where, either in the controller or in a scope whose only job is that group.

public function scopeIssuedOrPaid(Builder $query): void
{
    $query->where(function (Builder $query): void {
        $query->where('status', 'issued')
            ->orWhere('status', 'paid');
    });
}

Call it after forTeam(). The group is one constraint, so the team still applies to both statuses. An orWhere() written loose, next to forTeam(), is the leak. Inside a scope, Laravel groups the wheres that scope added when one of them is an or, so they cannot escape the conditions already on the query.

orWhereBelongsTo() at the call site is the same trap. A global team scope would have kept team_id on that query: Laravel groups the existing or conditions, then adds the global constraint. That is a real argument for the global scope. It does not retire the first section. A job or a report with no current team still inherits the filter, and the grouped local scope stays the call you can read.

A scope is a poor place to eager load "just in case", and a poor place to order every query. Those choices belong on the page that displays them.