Laravel Global Or Scope Laravel Package

Product Decisions This Supports

• Conditional-visibility ("show if") product rules. The recurring pattern is access that is any of N predicates: owner OR public OR shared-with-team OR flagged-by-admin. Drafts/published/org-visible content, moderated listings, records visible to assignee or watcher. This package makes that rule a single named artifact instead of an orWhere scattered across controllers, exports, and admin screens.
• Multi-tenancy / data-partitioning decisions. Lets you express "rows in my tenant OR rows explicitly shared globally OR rows on a parent account" without committing to a single hard tenant column or a heavyweight tenancy framework.
• Feature-flag and cohort rollouts at the data layer. Scope A = existing cohort, scope B = beta cohort. You flip exposure by changing registered scopes rather than rewriting query code in every consumer.
• Retention and archival policy. "Active rows OR rows this user may see archived" turns a retention decision into one testable scope instead of a per-endpoint convention.
• Roadmap sequencing. Because the rule is composable, adding a third visibility rule later is a scope addition, not a schema migration or a new endpoint. "Who can see what" becomes a policy change you can ship inside a sprint.
• Build vs. buy. The real capability is a trait plus an OrScope wrapper around existing Eloquent Scope classes. The decision is "one more composer dependency" vs. "20–50 lines of internal Eloquent plumbing" — buying wins if you'd otherwise reimplement it in three places; vendoring wins if you need heavier boolean composition.
• Consistency as a product/risk decision. Centralizing the disjunction prevents the "the CSV export forgot the permission filter" class of incident, which is a compliance event rather than a bug ticket.
• Reversibility. MIT, no config, no migrations, no service provider ceremony. Adoption is cheap to trial in one domain and cheap to unwind, which lowers the cost of the decision itself.

When to Consider This Package

Adopt when:

• You already have multiple Scope classes (or closures) and the business rule genuinely is a disjunction, and you want it applied by default to every query on that model.
• Your access model is expected to churn (pricing tiers, sharing, org restructuring), so you want visibility logic to be one named, testable, greppable thing.
• You need per-query and per-request escapes — withoutGlobalOrScope, withoutGlobalOrScopes, clearGlobalOrScopes, removedOrScopes — for admin tooling, reporting, and exports. This is usually the part that forces a rewrite of an in-house hack.
• You're on Laravel 9–12 / PHP 8.1+ and are comfortable treating the dependency as forkable: 5 stars, 0 dependents, single-maintainer agency project. That is the primary risk, and it is largely mitigated by MIT licensing and a very small surface area.
• The OR applies broadly across a model's read paths — not to one or two queries.

Look elsewhere (or build in-house) when:

• You only need AND semantics. Native Laravel global scopes are sufficient; this dependency is pure overhead.
• You need arbitrary nested boolean trees — (A∧B) ∨ (C∧¬D). The package composes OR-of-scopes, and stacking OrScope instances only yields (A∨B) ∧ (C∨D). For real expression trees use a specification/query-object pattern or a dedicated filter library.
• You need multi-tenancy with tenant lifecycle, connection switching, and queue/job context propagation. Use stancl/tenancy or spatie/laravel-multitenancy; a scope helper is not a tenancy strategy.
• Your organization requires vendor SLAs, security-review turnaround, or a support contract. Here it's one maintainer with an email address in the docs.
• "Another transitive dependency" is politically expensive. Read the source once and vendor the trait (MIT permits it, keep attribution) — plan for that as the exit path, not the exception.
• The rule touches only one or two queries. Write where(function ($q) { ... }) and move on.

Adoption gate: 0 dependents means there is no ecosystem signal. Do a source read plus your own integration tests around the exact visibility rules you encode before this sits on a revenue or regulated-data path.

How to Pitch It (Stakeholders)

To executives: A small, free, MIT-licensed library that lets us define "who can see which records" once, in one place, instead of re-implementing it in every screen, export, and API endpoint. That directly shrinks the class of bug that becomes a data-exposure incident. It costs nothing to adopt and nothing to reverse: no schema changes, no vendor contract, no migration, no new infrastructure. The honest risk is that it's a single-maintainer open-source project with negligible adoption; the mitigation is that the code is tiny and permissively licensed, so we can absorb it into our own codebase if it's ever abandoned. Recommendation: low-risk, high-leverage for the specific pattern; adopt narrowly and keep an exit path.

To engineering: One composer require, no config files, no migrations. Add the GlobalOrScope trait, register scopes in booting() (or in boot() before parent::boot() — ordering matters), and the model's queries gain (... OR ...) while ordinary global scopes retain AND semantics. Escape hatches cover the usual friction: withoutGlobalOrScope, withoutGlobalOrScopes, removedOrScopes, clearGlobalOrScopes, plus withGlobalOrScopes for ad-hoc composition without the trait, and raw OrScope for stacking (A∨B)∧(C∨D). It wraps standard Illuminate\...\Scope implementations, so there's no proprietary concept to learn and existing scopes are reusable. Two design caveats: no arbitrary nested boolean trees, and the package covers its own tests, not ours — we should add integration tests around the visibility rules we encode. If we ever outgrow it, the file count is small enough to vendor in an afternoon.