Weave Code
Laravel Global Or Scope Laravel Package
lacodix/laravel-global-or-scope
Add global scopes to Eloquent models combined with OR conditions, so multiple scopes are wrapped in a single or group. Disable some or all or-scopes on the fly with withoutGlobalOrScopes for flexible queries.
A Laravel package to add possibility to use global scopes with an or operation in Eloquent models
Frequently asked questions about Laravel Global Or Scope
- How do I install lacodix/laravel-global-or-scope in a Laravel app?
- Run composer require lacodix/laravel-global-or-scope. There is no publish step, no config file, and no migration, because the package ships a trait you add directly to your Eloquent model. You need PHP 8.1 or newer and Laravel 9 or newer.
- Where should I call addGlobalOrScopes in my model?
- Register the scopes in booting() or otherwise before parent::boot() runs, as shown in the README. Registering late means the model silently returns unfiltered data instead of throwing an error, which is a genuine data-exposure risk if the scope is a tenancy or visibility filter. Putting the call in the model's booting() method is the documented and safest pattern.
- What is the difference between addGlobalOrScopes and Laravel's native addGlobalScope?
- Laravel composes every global scope with AND, so there is no first-class way to express scope A or scope B at the model level. This package registers a single composite OrScope that implements Laravel's own Scope contract and applies the inner scopes inside one grouped orWhere. Use it only when the access rule is genuinely disjunctive; otherwise it adds a dependency with no behavior change.
- Which Laravel and PHP versions are supported?
- The package requires PHP 8.1+ and Laravel 9+. Releases track framework majors, with v1.1.0 targeting Laravel 11 and v1.2.0 targeting Laravel 12. Pin the version and read the release notes before upgrading a Laravel major, since grouping behavior depends on Eloquent internals.
- How do I temporarily disable all or-scopes or just one scope on a query?
- Use withoutGlobalOrScopes() to drop every or-scope for that query, or withoutGlobalOrScope(Scope1::class) to disable a single one. Matching withGlobalOrScope and withGlobalOrScopes methods let you re-enable them on a builder. Because removing a branch can change how the remaining ones are grouped, verify the generated SQL for your query shapes rather than assuming the parentheses survive.
- What SQL does laravel-global-or-scope actually generate?
- It produces a single grouped OR expression such as where user_id = 1000 and ((col1 is null and col2 = 1) or (col3 = 2)). That parenthesization is the entire value proposition of the package. Test it empirically against your real query shapes, including joins, whereHas, soft deletes, and nested scopes, instead of trusting the README example.
- Do the or-scopes apply to update(), delete(), and relationship queries?
- An OR group is strictly broader than an AND chain, so a mass update() or delete() on a builder carrying an or-scope can affect far more rows than a reviewer expects. Treat write paths as a policy decision rather than a code-review detail. Check against your installed version which of update, delete, restore, and relation queries actually receive the scope.
- Is this package safe to use with Laravel Octane, Swoole, or queue workers?
- The API exposes removedOrScopes(), withoutGlobalOrScopes(), and a static clearGlobalOrScopes(), which implies per-query and per-process bookkeeping. Static model state in long-lived workers is a known leakage pattern, so verify whether clearGlobalOrScopes() is request-scoped or process-scoped. Do not run it in Octane or a queue daemon until that behavior is confirmed.
- What is a good use case for global or-scopes in an Eloquent model?
- Reach for it when an access rule is genuinely disjunctive, for example created by me or public or shared with my team. If every scope in the model is conjunctive, stick with native global scopes. Consider wrapping the policy in one named scope class so all call sites depend on your own abstraction instead of the vendor API.
- Should I use this package or write my own OR scope class?
- The equivalent behavior is roughly 50 lines against Laravel's public Scope contract, so building it in-house is realistic. The package saves that time and ships its own tests, but it is a single-maintainer project with few dependents and no downstream canary. A practical rule is to pin it for read-path, non-critical filtering and implement it yourself when the OR group participates in tenancy or authorization.
Weaver
How can I help you explore Laravel packages today?