spatie/laravel-query-builder
60.3
Adequate · 17 November 2026
2.2k
lines of production code
PHP
primary language
5
measurements over time
What this system is
Features
Introduces configurable query-builder settings for API parameter customization
The package now provides a \config/query-builder.php\ file that allows users to customize query string parameter names (include, filter, sort, fields, append), adjust the delimiter for array values, and control whether filter values are split by that delimiter. It also enables configuration of aggregate suffixes (e.g., Count, Exists) for relationship includes, and offers options to disable exceptions for invalid filter, sort, or include queries. Additionally, users can configure how relation names and field names are converted to snake\_case, and specify a strategy for matching relation table names to field parameters.
config · high confidence
Modernized API and aggregate includes
The includes system has been refactored to use a new \IncludeInterface\ and dedicated classes (such as \IncludedRelationship\, \IncludedCount\, \IncludedSum\, \IncludedAvg\, \IncludedMax\, \IncludedMin\, \IncludedExists\, and \IncludedCallback\). This change introduces support for aggregate includes (count, sum, average, max, min, exists) and allows custom callbacks for relationships, providing a more structured and type-safe way to handle included data in queries.
src/Includes · high confidence
New filter types and nested relation support
This release introduces several new filter classes to expand query capabilities: FiltersBelongsTo allows filtering by related model properties, FiltersGroup enables AND/OR conjunctions for multiple filters, and FiltersOperator supports comparison operators (like \<, \>, =). Additionally, the system now supports filtering by nested relation scopes via the new HandlesRelationConstraints concern, allowing queries like 'author.name' to filter on related model attributes. New filters include FiltersCallback for custom logic, FiltersEndsWith and FiltersBeginsWith for pattern matching, and FiltersTrashed for soft-delete handling. The Filter interface has been modernized with generics for better type safety.
src/Filters · high confidence
Behavioural changes
Introduce specific exception classes for query validation errors
The library now provides distinct exception classes for different query validation failures, replacing generic error handling with specific types for invalid fields, filters, sorts, includes, appends, and sort directions. This allows developers to catch and handle specific validation errors (such as \InvalidFieldQuery\ or \InvalidSortQuery\) individually, while each exception now exposes the list of allowed values alongside the invalid input to help users correct their requests immediately.
src/Exceptions · high confidence
Modernized sort API with new interface and callback support
The sorting mechanism has been refactored to use a new \Sort\ interface, replacing the previous implementation. This change introduces a standardized way to handle sorting via the \\_\_invoke\ method, accepting a query builder, sort direction, and property name. A new \SortsCallback\ class allows users to define custom sorting logic using closures, while \SortsField\ provides the default field-based sorting behavior. This update modernizes the API and enables more flexible sorting configurations.
src/Sorts · high confidence
Refactored query building into dedicated concern traits
The query-building logic in the library has been restructured into four distinct traits—AddsFieldsToQuery, AddsIncludesToQuery, FiltersQuery, and SortsQuery—replacing the previous monolithic implementation. This change introduces a more modular approach where field selection, relationship inclusion, filtering, and sorting are handled by separate, focused components. Users will see that allowed fields, includes, filters, and sorts are now processed through these specific traits, which manage their respective validation (e.g., ensuring requested fields or includes exist in the allowed list) and application to the query builder. The refactoring also standardizes how these features are configured, such as allowing string names for allowed sorts/includes/filters which are automatically converted to their respective Allowed\* objects, and introduces configuration options to disable exceptions for invalid queries (e.g., \disable\_invalid\_include\_query\_exception\).
src/Concerns · high confidence
Upgrade to v7 with breaking API changes and modernized requirements
This release upgrades the package to version 7, requiring PHP 8.3+ and Laravel 12 or 13 (dropping support for Laravel 10 and 11). The public API has been modernized: wildcard parameters for \allowedFilters()\, \allowedSorts()\, and \allowedIncludes()\ are removed in favor of explicit lists, and these methods now accept variadic arguments instead of arrays. \SortDirection\ is now a PHP enum, and static delimiter methods have been replaced by a config key and a fluent \delimiter()\ method. Additionally, the \Filter\, \Sort\, and \Include\ interfaces now require explicit \void\ return types on their \\_\_invoke\ methods, and the \allowedFields()\ method no longer needs to be called before \allowedIncludes()\. The changelog has been updated to v7.3.5, and CI configuration has been migrated from Travis CI to GitHub Actions with PHPStan level raised to 6.
(repo-wide) · high confidence
v7: Modernized API and aggregate includes
The library has been upgraded to version 7, introducing a modernized API with strict typing, generics, and a new request handling layer. Users can now use aggregate includes (count, exists, min, max, sum, avg) alongside standard relationship includes, and apply operator-based filters (e.g., \<, \>, =) or filter groups (AND/OR conjunctions). The query builder now supports selecting specific fields for tables, custom delimiters for array values, and nullable filters, while deprecated macros and request data sources have been removed in favor of the new \QueryBuilderRequest\ class.
src · high confidence
Test coverage
Added database factories for test models; Added test helper trait for collection sorting assertions; Added test model for Filter interface; Comprehensive test suite for QueryBuilder features.
Dependencies
Upgrade to Laravel 12/13 and PHP 8.3 with modernized tooling
This package now requires PHP 8.3 and supports Laravel 12 and 13, dropping compatibility with older versions. The development environment has been modernized by switching the test runner from PHPUnit to Pest v4/v5, upgrading static analysis to Larastan v3.3, and updating the testing framework (Testbench) to v10/v11. These changes ensure the package works with the latest Laravel ecosystem while providing improved developer tooling for testing and code quality.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 61.3 → 60.3 (-1.0)
- Rubric changed (rubric-2026.11.2 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 52.2 → 51.7 (-0.5)
- Architecture 98.4 → 85.5 (-12.9)
- Maturity 59.6 → 59.6 (0.0)
- Readiness 89.0 → 89.0 (0.0)
- Security 67.7 → 67.7 (0.0)
Resolved (1)
- Off-boarding risk: anonymized user #1
New (5)
- Circular dependency (src/QueryBuilder.php)
- Edited copies of one member (3 members, 13+ corresponding lines) (src/Concerns/AddsIncludesToQuery.php)
- Edited copies of one member (4 members, 3+ corresponding lines) (src/Includes/IncludedAvg.php)
- Off the main sequence: src/Includes
- Off-boarding risk: anonymized user #1
Changes since last survey
- 4 commits — 4 feature/other, 0 fixes
By area
- (root) — 2 commits
- docs/features — 1 commit
- tests/TestClasses — 1 commit
Notable commits
- change: Keep true and false filter values unless they are ignored themselves (#1076)
- change: Resolve nested scope bindings on the related model (#1075)
- change: Update CHANGELOG
- change: Update CHANGELOG
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
spatie/laravel-query-builder was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 17 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 3070dfc320803281131fc2b0684c195f3ac4dd02 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.85+preprod-eba6548ac50f.