Laravel Query Builder Laravel Package

Product Decisions This Supports

• API Flexibility & Standardization: Enables consistent, declarative query parameters (filtering, sorting, pagination, field selection) across all Eloquent-based APIs, reducing frontend-backend negotiation overhead.
• Build vs. Buy: Avoids reinventing query parsing logic (e.g., manual Request handling for filter[], sort, include). MIT-licensed and battle-tested (4.5K stars) reduces risk.
• Roadmap Priorities:
  • Phase 1: Standardize existing APIs (e.g., /users?filter[name]=John&sort=-created_at).
  • Phase 2: Replace ad-hoc query builders with this package for new endpoints.
  • Phase 3: Extend to GraphQL APIs (via Laravel GraphQL) for unified query patterns.
• Use Cases:
  • Admin Panels: Dynamic filtering (e.g., ?filter[status]=active&filter[created_at][gt]=2023-01-01).
  • Public APIs: Secure, documented query parameters (e.g., ?fields[users]=id,name&include=posts).
  • Legacy Migration: Gradually adopt by wrapping existing queries (e.g., QueryBuilder::for($existingQuery)).

When to Consider This Package

• Adopt When:
  • Your API has >5 endpoints with repetitive query logic (filtering/sorting/pagination).
  • You need consistent query parameters across microservices or monoliths.
  • Your team spends >20% of API dev time on manual query parsing (e.g., parsing filter[] arrays).
  • You require fine-grained security (e.g., restrict sort to only id/created_at).
• Look Elsewhere If:
  • You’re using non-Eloquent data sources (e.g., raw SQL, MongoDB). Alternative: Custom middleware or libraries like spatie/laravel-query-builder’s non-Eloquent extensions.
  • Your queries are extremely complex (e.g., multi-table joins with dynamic conditions). Alternative: Combine with Laravel’s Query Builder or a dedicated ORM like October CMS’s BackendList.
  • You need real-time filtering (e.g., WebSockets). Alternative: Use Laravel Echo + custom logic.
  • Your team prefers GraphQL over REST. Alternative: Integrate with spatie/laravel-query-builder via GraphQL resolvers or use nwidart/laravel-eloquent-filters.

How to Pitch It (Stakeholders)

For Executives:

"This package standardizes how our APIs handle filtering, sorting, and data inclusion—like adding ‘autocomplete’ for query parameters. For example, instead of manually parsing ?name=John&sort=-created_at in every endpoint, we’ll use a single, secure library to handle it. This reduces dev time by ~30% for new APIs, cuts bugs from inconsistent query logic, and makes our public APIs more predictable for partners. It’s like upgrading from hand-written SQL to a modern ORM—just for API queries."

ROI:

• Dev Velocity: 1–2 days to implement vs. weeks of custom code.
• Security: Explicitly whitelist allowed fields/sorts (e.g., block ?sort=password).
• Scalability: Works across all Laravel services; easy to audit/query patterns.

For Engineers:

*"This replaces repetitive Request parsing with a fluent, type-safe API. Key wins:

1. Consistency: All APIs use the same filter[], sort, include syntax (e.g., /users?filter[status]=active&include=posts).
2. Security: Whitelist fields/sorts at the model level (e.g., allowedSorts(['id', 'created_at'])).
3. Flexibility:
   • Chain with existing queries: QueryBuilder::for(User::where('active', true)).
   • Custom logic: Extend with AllowedFilter::custom() or AllowedSort::custom().
4. Documentation: Auto-generates OpenAPI/Swagger specs for query params.
5. Performance: Uses Eloquent’s built-in optimizations (e.g., with() for includes).

Migration Path:

• Start with one high-traffic endpoint (e.g., /products).
• Use QueryBuilder::for($existingQuery) to wrap legacy logic.
• Gradually replace custom Request handlers.

Example Migration:

// Before (manual parsing)
public function index(Request $request) {
    $query = User::query();
    if ($request->has('name')) {
        $query->where('name', 'like', '%'.$request->name.'%');
    }
    return $query->get();
}

// After (standardized)
public function index() {
    return QueryBuilder::for(User::class)
        ->allowedFilters('name') // Only allow `?filter[name]=...`
        ->get();
}
```"

**Dependencies**: Requires Laravel 8+; works with Lumen. No breaking changes in v7.x.