Weave Code
Laravel Query Builder Laravel Package
spatie/laravel-query-builder
Build safe, flexible Eloquent queries from incoming API requests. Supports whitelisted filtering (partial/exact/scope/custom), sorting, includes, field selection, pagination, and grouped AND/OR filters—ideal for JSON:API-style endpoints with minimal boilerplate.
Easily build Eloquent queries from API requests
Frequently asked questions about Laravel Query Builder
- How do I allow partial string matching (LIKE) filters in my Laravel API using this package?
- Use the `allowedFilters()` method with the `partial` modifier. For example, `QueryBuilder::for(User::class)->allowedFilters(['name:partial'])->get()` will enable partial matches for the `name` field. Ensure your database has indexes on filtered columns to avoid performance issues with LIKE queries.
- Can I use this package with Laravel 9 or 10? What’s the latest supported version?
- Yes, the package is compatible with Laravel 8+. As of now, version 7 of the package is the latest, and it explicitly supports Laravel 8 through 10. Always check the [GitHub repository](https://github.com/spatie/laravel-query-builder) for updates, as Spatie regularly aligns with newer Laravel releases.
- How do I restrict API clients from sorting by specific columns to prevent performance issues?
- Whitelist only the allowed sort fields using `allowedSorts()`. For example, `QueryBuilder::for(User::class)->allowedSorts(['name', 'created_at'])->get()` restricts sorting to those columns. This prevents accidental or malicious sorting by unindexed or expensive columns.
- Is it possible to combine this package with existing Eloquent queries (e.g., chaining with `where()`)?
- Yes, the package works seamlessly with existing Eloquent queries. Start with your base query and pass it to `QueryBuilder::for()`. For example, `QueryBuilder::for(User::where('active', true))->allowedFilters('name')->get()` will apply filters to the pre-constrained query.
- How do I handle nested relationships in includes (e.g., `users?include=posts.comments`)?
- Use dot notation in `allowedIncludes()` to specify nested relationships. For example, `QueryBuilder::for(User::class)->allowedIncludes(['posts', 'posts.comments'])->get()` will eager-load posts and their comments. Ensure your relationships are properly defined in your Eloquent models.
- What’s the best way to secure my API against SQL injection when using dynamic query parameters?
- The package mitigates SQL injection by validating all filters, sorts, and includes against your whitelists. Always use `allowedFilters()`, `allowedSorts()`, and `allowedIncludes()` to restrict input. Additionally, enable `disable_invalid_filter_query_exception` in config to fail silently on invalid queries, preventing error leaks.
- Can I define custom filters or scopes for complex query logic (e.g., date ranges, status flags)?
- Yes, use the `customFilter()` method to define custom logic. For example, `QueryBuilder::for(User::class)->customFilter('active', fn($query, $value) => $query->where('active', $value))->get()` lets you handle complex conditions. Document these filters clearly for your API consumers.
- How do I test my API endpoints that use this package for query building?
- Test by sending HTTP requests with query parameters (e.g., `?filter[name]=John`) and asserting the results. Use Laravel’s HTTP tests to simulate API calls. For example, `get('/users?filter[name]=John')->assertOk()` ensures the filter works as expected. Mock the QueryBuilder in unit tests if needed.
- What are the performance implications of using partial filters (LIKE) in production?
- Partial filters (LIKE) can be slow without proper indexing. Use `beginsWith` or `endsWith` modifiers for better performance, or add full-text indexes if your database supports it. Monitor query performance with tools like Laravel Debugbar and optimize indexes for frequently filtered columns.
- Are there alternatives to this package for building dynamic Eloquent queries in Laravel?
- Alternatives include `fractal/laravel-api-tools` (for API resources and query building) and `darkaonline/l5-swagger` (for Swagger/OpenAPI integration with query parameters). However, `spatie/laravel-query-builder` is specialized for flexible, secure query building with minimal setup, making it ideal for most Laravel API use cases.
Weaver
How can I help you explore Laravel packages today?