Laravel Query Builder Laravel Package

Product Decisions This Supports

• API Flexibility & Developer Experience:

  • Enable self-service data access for frontend teams by allowing them to dynamically filter, sort, and paginate API responses without backend changes.
  • Reduce API versioning friction by standardizing query parameters (e.g., ?filter[name]=John, ?sort=-created_at) across all endpoints.

• Roadmap Priorities:

  • Build vs. Buy: Avoid reinventing query parsing logic (e.g., manual Request handling for filter[], sort, include) and leverage a battle-tested, MIT-licensed solution.
  • Scalable APIs: Support complex use cases like:
    • Multi-tenancy: Filter by tenant_id via ?filter[tenant_id]=123.
    • Analytics dashboards: Dynamic sorting/filtering of aggregated data (e.g., ?sort=-revenue).
    • GraphQL-like flexibility: Mimic GraphQL’s include behavior for nested relationships (e.g., ?include=posts.comments.author).

• Use Cases:

  • Admin Panels: Let non-technical users build custom reports (e.g., filter orders by status and date_range).
  • Mobile Apps: Optimize payloads with ?fields[users]=id,name,email to reduce bandwidth.
  • Third-Party Integrations: Expose filtered endpoints to partners (e.g., ?filter[active]=true&filter[plan]=pro).

When to Consider This Package

• Adopt if:

  • Your API endpoints require dynamic filtering/sorting (e.g., search, dashboards, admin tools).
  • You use Eloquent models and want to avoid raw SQL or complex Request parsing.
  • Your team prioritizes developer velocity over fine-grained control (e.g., you’re okay with AllowedFilter constraints).
  • You need JSON:API-compliant filtering (e.g., filter[q] for OR/AND groups).

• Look elsewhere if:

  • You need subsecond query performance for large datasets (this package adds minor overhead for parsing/query building).
  • Your queries require custom SQL functions not supported by Eloquent (e.g., FULLTEXT searches).
  • You’re using non-Eloquent data sources (e.g., raw database connections, external APIs).
  • Your API is read-heavy but write-critical (this package is optimized for queries, not mutations).
  • You need GraphQL’s flexibility (consider Laravel GraphQL packages like nuwave/lighthouse instead).

How to Pitch It (Stakeholders)

For Executives:

"This package lets our API endpoints adapt dynamically to user needs—like a self-service data layer. For example, a sales dashboard can filter orders by status=shipped and date_range=2024-01-01..2024-01-31 without backend changes. It’s like giving frontend teams a ‘query builder’ for our data, reducing API versioning and speeding up feature delivery. The MIT license and 4.5K stars mean it’s battle-tested and low-risk."

For Engineers:

*"Spatie’s Query Builder solves the pain of manually parsing filter[], sort, and include params in every API route. Key benefits:

• Consistency: Standardize query params across all endpoints (e.g., ?filter[active]=true).
• Security: Explicitly whitelist allowed filters/sorts/includes to prevent SQL injection.
• Flexibility: Support complex queries like:

  QueryBuilder::for(User::class)
      ->allowedFilters(
          AllowedFilter::partial('name'),
          AllowedFilter::groupOr('q', [
              AllowedFilter::partial('email'),
              AllowedFilter::exact('role', 'admin'),
          ]),
      )
      ->allowedSorts('created_at')
      ->allowedIncludes('posts.comments');
  

• Integration: Works seamlessly with existing Eloquent scopes and Laravel’s query builder.
• Performance: Minimal overhead; optimized for common use cases like pagination and eager loading.

Trade-offs: We cede some control to a third-party package, but the trade-off is worth it for the time saved and reduced bugs in query parsing."*