Laravel Query Builder Laravel Package

Product Decisions This Supports

• API Flexibility & Developer Experience: Enables consistent, type-safe query parameters across APIs (e.g., filtering, sorting, pagination) without manual validation or boilerplate code. Reduces cognitive load for frontend/backend teams.
• Roadmap for Self-Service Analytics: Accelerates development of internal dashboards or public APIs where users need to filter/search data (e.g., /users?filter[status]=active&sort=-created_at).
• Build vs. Buy: Avoids reinventing query parsing logic (e.g., manual Request handling for filter[], include[], etc.). MIT license mitigates vendor lock-in.
• Use Cases:
  • Admin Panels: Dynamic filtering for CRUD interfaces (e.g., "Show inactive users with posts").
  • Public APIs: Secure, documented query parameters for clients (e.g., e-commerce product filters).
  • Legacy Migration: Gradually adopt in existing APIs by wrapping QueryBuilder::for($existingQuery).
  • Multi-Tenant Apps: Filter by tenant ID via filter[tenant_id] without exposing raw SQL.

When to Consider This Package

• Avoid if:
  • Your API requires complex nested queries (e.g., GraphQL-like depth) beyond Eloquent’s capabilities. Consider Laravel GraphQL or custom solutions.
  • You need real-time filtering (e.g., WebSockets). Use Laravel Echo or dedicated search engines (Elasticsearch, Algolia).
  • Performance is critical for partial filters (e.g., LIKE %value% on large tables). Optimize with database indexes or full-text search.
  • Your team prefers GraphQL or REST with strict schemas (e.g., OpenAPI). This package leans toward flexible query params.
• Look elsewhere if:
  • You’re using non-Eloquent models (e.g., raw database queries). Extend the package or use a lower-level solution like DB::query().
  • You need advanced aggregations (e.g., GROUP BY, HAVING). Combine with Laravel’s query builder or use a reporting tool (e.g., Laravel Scout).
  • Your stack is non-PHP/Laravel (e.g., Node.js, Python). Port to equivalent libraries (e.g., express-query-int).

How to Pitch It (Stakeholders)

For Executives: "This package standardizes how our APIs handle filtering, sorting, and data inclusion—reducing dev time by 30%+ for common query patterns. For example, a frontend team can now fetch ‘active users with posts sorted by name’ via /users?filter[status]=active&include=posts&sort=-name without backend changes. It also improves security by whitelisting allowed query parameters, cutting SQL injection risks. Low maintenance (MIT-licensed, 4.4K stars) and aligns with our Laravel stack."

For Engineers: *"Spatie’s Query Builder lets you replace manual Request parsing for filter[], include[], etc., with declarative rules like:

QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email') // Auto-parses ?filter[name]=john
    ->allowedIncludes('posts')       // Handles ?include=posts
    ->allowedSorts('created_at');    // Supports ?sort=-created_at

• Pros:
  • No more writing repetitive if ($request->has('filter[name]')) logic.
  • Works with existing queries (QueryBuilder::for($query->where(...))).
  • Supports nested relations, custom filters, and scopes.
• Trade-offs:
  • Partial filters (LIKE) may impact performance on large tables (mitigate with indexes).
  • Not a replacement for GraphQL if you need strongly typed schemas.
• Next Steps: Add to a new API or wrap existing endpoints incrementally. Docs are excellent; expect 1–2 dev days to integrate."*

For Designers/Product Managers: *"This enables self-service data exploration for users (e.g., filtering support tickets by status/date). For example:

• Admin Panels: Let managers filter users by ‘active’, ‘role’, or ‘last login’ via URL params.
• Public APIs: Give developers tools to build dynamic clients (e.g., ‘Show products in stock, sorted by price’). No UI changes needed—just expose the query params!"*