Laravel Global Or Scope Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package excels at addressing a common but unsupported Laravel/Eloquent limitation—applying global scopes with OR logic (native Laravel only supports AND via withGlobalScope). This is a high-value gap for complex query filtering (e.g., "active OR archived" records).
• Design Pattern Compatibility: Leverages Laravel’s existing Scope interface and Builder pattern, ensuring minimal architectural disruption. The GlobalOrScope trait integrates seamlessly with Eloquent’s lifecycle (booting()/boot()).
• Flexibility: Supports dynamic scope toggling (per-query or request-wide), mixed scope types (classes, closures, instances), and nested OR conditions (via OrScope). This aligns with modular query design needs.

Integration Feasibility

• Low Friction: Zero config files or migrations required—just composer install + trait usage. Ideal for incremental adoption (e.g., piloting on a single model).
• Backward Compatibility: Works alongside existing global scopes (AND logic) without conflicts. Example:

  static::addGlobalScope(SoftDeletes::class); // AND
  static::addGlobalOrScopes([ActiveScope::class, ArchivedScope::class]); // OR
  

• Query Builder Integration: Methods like withoutGlobalOrScopes() and withGlobalOrScopes() mirror Laravel’s conventions, reducing learning curves.

Technical Risk

• Performance Impact:
  • OR conditions can increase query complexity (e.g., WHERE (A OR B) AND C), potentially degrading index usage or requiring higher explain analysis.
  • Mitigation: Profile with DB::enableQueryLog() and optimize scopes to use indexed columns.
• Edge Cases:
  • Scope Ordering: OR scopes are grouped as a single parenthesized clause, but their internal order may affect readability (e.g., Scope1 OR Scope2 vs. Scope2 OR Scope1).
  • Nested Scopes: Advanced use cases (e.g., (Scope1 OR Scope2) AND (Scope3 OR Scope4)) require explicit OrScope instantiation, which could obscure intent.
  • Mitigation: Document scope grouping strategies in team guidelines.
• Laravel Version Lock:
  • PHP 8.1+ / Laravel 9+ requirement may block legacy projects. However, the package supports Laravel 11/12, covering most modern stacks.

Key Questions

1. Query Complexity:
   • How will OR scopes interact with existing complex queries (e.g., joins, subqueries)?
   • Action: Test with real-world query patterns before full adoption.
2. Testing Strategy:
   • How will we verify scope logic in CI? The package includes tests, but model-specific scopes need coverage.
   • Action: Template a scope test suite for critical models.
3. Monitoring:
   • Will OR scopes degrade performance in production? Plan for query logging and index reviews.
4. Team Adoption:
   • How will developers document scope intent? OR logic can be less intuitive than AND.
   • Action: Enforce scope naming conventions (e.g., ActiveOrArchivedScope).

Integration Approach

Stack Fit

• Laravel Ecosystem: Perfect fit for Eloquent-based applications with complex filtering needs (e.g., SaaS platforms, CMS, or data-heavy apps).
• PHP Version: Requires PHP 8.1+, which aligns with Laravel 9+ (including LTS versions like 10.x/11.x).
• Alternatives Considered:
  • Manual OR queries: Less maintainable (scattered orWhere calls).
  • Query Scopes: Requires manual OR grouping (e.g., scopeActiveOrArchived()).
  • Database Views: Overkill for dynamic filtering.
  • Verdict: This package offers the best balance of maintainability and flexibility.

Migration Path

1. Pilot Phase:
   • Select 1–2 models with clear OR filtering needs (e.g., Post with published_at OR draft_at).
   • Implement GlobalOrScope trait and test query behavior (SQL output, performance).
2. Incremental Rollout:
   • Replace manual OR logic in queries with addGlobalOrScopes().
   • Update existing scopes to support OR conditions (e.g., refactor ActiveScope to work with OR).
3. Deprecation Plan:
   • Phase out legacy orWhere chains in favor of global OR scopes.
   • Document scope interactions (e.g., "Use withoutGlobalOrScopes() for admin queries").

Compatibility

• Existing Global Scopes: No conflicts—AND scopes (e.g., SoftDeletes) remain unchanged.
• Third-Party Packages: Should work unless they override Eloquent’s boot() or Builder methods.
• Testing Tools: Compatible with Pest/Laravel Tests (scopes are applied during query execution).

Sequencing

1. Pre-requisites:
   • Upgrade to Laravel 9+ if needed.
   • Ensure PHP 8.1+ (use rector for upgrades if necessary).
2. Core Integration:
   • Install package: composer require lacodix/laravel-global-or-scope.
   • Add trait to pilot models and register OR scopes.
3. Validation:
   • Verify SQL output matches expectations (use DB::enableQueryLog()).
   • Test edge cases (empty scopes, disabled scopes, nested OR).
4. Scaling:
   • Expand to additional models based on pilot feedback.
   • Monitor query performance (e.g., with Laravel Debugbar).

Operational Impact

Maintenance

• Package Updates:
  • Low effort: MIT license + active maintenance (last release: 2026-06-09).
  • Upgrade path: Composer will handle version bumps; test for breaking changes (e.g., Laravel 12 support in v1.2.0).
• Scope Management:
  • Centralized: Scopes are defined in model classes, reducing scattered logic.
  • Dynamic: Scopes can be toggled per-query (e.g., admin panels disable OR filters).
• Documentation:
  • Existing: Comprehensive docs cover usage, disabling, and advanced cases.
  • Action: Add team-specific examples (e.g., "How we use OR scopes for user visibility").

Support

• Troubleshooting:
  • Common Issues:
    • "Scopes not applying": Check booting() registration order.
    • "Performance issues": Review SQL with explain and optimize scopes.
  • Debugging Tools:
    • removedOrScopes() to inspect disabled scopes.
    • Query logging for SQL inspection.
• Community:
  • GitHub Issues: Active maintainer (Lacodix) responds to bugs/feature requests.
  • MIT License: Allows forks if needed.

Scaling

• Performance:
  • OR Scopes: May increase query complexity (e.g., WHERE (A OR B) AND C). Mitigate with:
    • Indexing: Ensure OR conditions use indexed columns.
    • Selective Disabling: Use withoutGlobalOrScopes() for high-traffic endpoints.
  • Benchmark: Compare with/without OR scopes using DB::connection()->getPdo()->query("EXPLAIN ...").
• Concurrency:
  • Thread-safe: Scopes are applied per-query; no shared state.
  • Caching: If using Eloquent caching, ensure scopes are reapplied (they’re query-time, not model-time).
• Database Load:
  • Monitor: Track query duration with Laravel Telescope or New Relic.
  • Optimize: Replace complex OR scopes with database views or application logic if needed.

Failure Modes

Ramp-Up

• Onboarding:
  • Workshop: 1-hour session on scope registration, query debugging, and