spatie/laravel-query-builder

This is a Laravel package that provides a query builder for constructing API requests with support for filtering, sorting, and including related data. It allows developers to define allowed fields, apply complex filters with operators and groups, sort results, and include relationships or aggregate metrics like counts and sums. The system enforces strict validation through specific exception classes and offers extensive configuration options for parameter names and behavior.

8 changes.

The project underwent a major version 7 release, upgrading to PHP 8.3 and Laravel 12/13 while modernizing the public API with strict typing, generics, and a new request handling layer. This period introduced extensive new features, including configurable query parameters, aggregate includes, and advanced filter types, alongside a comprehensive test suite and specific exception classes for better error handling.

5 changes.

The codebase underwent a comprehensive refactoring to modernize its core APIs, replacing monolithic implementations with modular traits and dedicated interfaces for sorting, filtering, and includes. This work introduced support for aggregate includes and custom callbacks while standardizing query building logic through focused components. The period also included enhancements to the test suite with new model factories and interface implementations to support these structural changes.

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

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

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

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

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

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

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

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

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.

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 watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 71.

• Code Health 98
• Architecture 98
• Maturity 60
• Readiness 89
• Security 68

• 300 commits — 247 feature/other, 53 fixes

• (root) — 79 commits
• (repo) — 58 commits
• .github/workflows — 38 commits
• src/Filters — 26 commits
• docs/features — 21 commits
• src/AllowedFilter.php — 14 commits
• tests/FilterTest.php — 12 commits
• src/Concerns — 10 commits
• config/query-builder.php — 8 commits
• src/QueryBuilder.php — 8 commits
• .github/ISSUE_TEMPLATE — 4 commits
• docs/advanced-usage — 4 commits
• src/Includes — 2 commits
• src/QueryBuilderRequest.php — 2 commits
• tests/TestClasses — 2 commits
• .phpunit.cache/test-results — 1 commit
• database/factories — 1 commit
• docs/_index.md — 1 commit
• docs/installation-setup.md — 1 commit
• docs/introduction.md — 1 commit

• fix: Add phpunit dependency to use fixed version in automated tests
• fix: Bugfix ignore allowed filters (#818)
• fix: CS Fix
• fix: Fix PHPStan errors on main (#1057)
• fix: Fix TypeError when nullable operator filter receives null value (#1048)
• fix: Fix ability to filter models by an array as filter value
• fix: Fix broken LIKE escaping (#898)
• fix: Fix code style badge to point at pint.yml workflow
• fix: Fix having null as the filter query parameter name
• fix: Fix phpstan issue
• fix: Fix selecting fields on belongs to many relations
• fix: Fix styling
• fix: Fix styling
• fix: Fix styling
• fix: Fix styling
• fix: Fix styling
• fix: Fix styling
• fix: Fix styling
• fix: Fix styling
• fix: Fix styling
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

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.