Prepare v7 with modernized API and new features

Drop Laravel 10/11, require Laravel 12+, Pest 4, PHPUnit 12.
Convert SortDirection to PHP enum, use variadic parameters across all
allowed* methods, extract HandlesRelationConstraints trait, move delimiter
config from global static state to config file, add aggregate includes
(withMin/Max/Sum/Avg), add wildcard allow-all support with environment
guard, rename filter classes, remove ordering constraint for allowedFields,
raise PHPStan to level 6, and update all docs and tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: freekmurze

.github/workflows/run-tests.yml

@@ -13,20 +13,14 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         php: [8.5, 8.4, 8.3, 8.2]
-        laravel: ['10.*', '11.*', '12.*', '13.*']
+        laravel: ['12.*', '13.*']
         stability: [prefer-stable]
         include:
-          - laravel: 11.*
-            testbench: 9.*
-          - laravel: 10.*
-            testbench: 8.*
           - laravel: 12.*
             testbench: 10.*
           - laravel: 13.*
             testbench: 11.*
         exclude:
-          - laravel: 10.*
-            php: 8.5
           - laravel: 13.*
             php: 8.2
 

README.md

@@ -70,7 +70,7 @@ $userQuery = QueryBuilder::for($query) // start from an existing Builder instanc
 
 ```php
 $users = QueryBuilder::for(User::class)
-    ->allowedFields(['id', 'email'])
+    ->allowedFields('id', 'email')
     ->get();
 
 // the fetched `User`s will only have their id & email set

UPGRADING.md

@@ -1,5 +1,125 @@
 # Upgrading
 
+## From v6 to v7
+
+### Requirements
+
+- PHP 8.2+
+- Laravel 12 or 13
+
+Support for Laravel 10 and 11 has been dropped.
+
+### Variadic parameters
+
+The `allowedFilters()`, `allowedSorts()`, `allowedIncludes()`, `allowedFields()`, `defaultSort()`, and `defaultSorts()` methods now accept variadic arguments instead of arrays.
+
+```php
+// Before
+QueryBuilder::for(User::class)
+    ->allowedFilters(['name', 'email'])
+    ->allowedSorts(['name'])
+    ->allowedIncludes(['posts'])
+    ->allowedFields(['id', 'name']);
+
+// After
+QueryBuilder::for(User::class)
+    ->allowedFilters('name', 'email')
+    ->allowedSorts('name')
+    ->allowedIncludes('posts')
+    ->allowedFields('id', 'name');
+```
+
+If you have dynamic arrays, use the spread operator:
+
+```php
+$filters = ['name', 'email'];
+QueryBuilder::for(User::class)->allowedFilters(...$filters);
+```
+
+### `SortDirection` is now an enum
+
+The `SortDirection` class with string constants has been replaced with a proper PHP enum.
+
+```php
+// Before
+use Spatie\QueryBuilder\Enums\SortDirection;
+
+AllowedSort::field('name')->defaultDirection(SortDirection::DESCENDING);
+
+// After
+use Spatie\QueryBuilder\Enums\SortDirection;
+
+AllowedSort::field('name')->defaultDirection(SortDirection::Descending);
+```
+
+The `AllowedSort::defaultDirection()` method now requires a `SortDirection` enum value instead of a string.
+
+### Filter renames
+
+`AllowedFilter::beginsWithStrict()` has been renamed to `AllowedFilter::beginsWith()`.
+`AllowedFilter::endsWithStrict()` has been renamed to `AllowedFilter::endsWith()`.
+
+```php
+// Before
+AllowedFilter::beginsWithStrict('name');
+AllowedFilter::endsWithStrict('name');
+
+// After
+AllowedFilter::beginsWith('name');
+AllowedFilter::endsWith('name');
+```
+
+### `AllowedInclude` factory methods now return `self` instead of `Collection`
+
+`AllowedInclude::relationship()`, `AllowedInclude::count()`, `AllowedInclude::exists()`, `AllowedInclude::callback()`, and `AllowedInclude::custom()` now return a single `AllowedInclude` instance instead of a `Collection`. This should not affect most usage since you typically pass them to `allowedIncludes()`.
+
+### Static delimiter methods removed
+
+The static delimiter methods on `QueryBuilderRequest` have been removed (`setArrayValueDelimiter`, `setFilterArrayValueDelimiter`, `setSortsArrayValueDelimiter`, `setIncludesArrayValueDelimiter`, `setFieldsArrayValueDelimiter`, `setAppendsArrayValueDelimiter`, `resetDelimiters`).
+
+Delimiters are now configured via the `delimiter` key in the config file:
+
+```php
+// config/query-builder.php
+'delimiter' => ',',
+```
+
+The `$arrayValueDelimiter` parameter has also been removed from all `AllowedFilter` factory methods.
+
+### `allowedFields()` no longer needs to be called before `allowedIncludes()`
+
+The `AllowedFieldsMustBeCalledBeforeAllowedIncludes` exception has been removed. You can now call `allowedFields()` and `allowedIncludes()` in any order.
+
+### Config changes
+
+The `disable_invalid_includes_query_exception` config key has been renamed to `disable_invalid_include_query_exception` (singular "include").
+
+The `convert_relation_table_name_strategy` config now uses `null` instead of `false` as its default/disabled value.
+
+A new `delimiter` config key has been added (default: `','`).
+
+### Filter interface return type
+
+The `Filter` interface's `__invoke` method now has an explicit `void` return type. If you have custom filter classes, update them:
+
+```php
+// Before
+public function __invoke(Builder $query, $value, string $property)
+
+// After
+public function __invoke(Builder $query, mixed $value, string $property): void
+```
+
+The same applies to the `Sort` interface and `IncludeInterface`.
+
+### Filter class hierarchy refactored
+
+`FiltersPartial` no longer extends `FiltersExact`, and `FiltersOperator` no longer extends `FiltersExact`. If you were extending these classes and relying on the inheritance chain, note that relation constraint handling is now provided via the `HandlesRelationConstraints` trait in `Spatie\QueryBuilder\Filters\Concerns`.
+
+### PHPStan level raised to 6
+
+The PHPStan analysis level has been bumped from 5 to 6.
+
 ## From v5 to v6
 
 A lot of the query builder classes now have typed properties and method parameters. If you have any custom sorts, includes, or filters, you will need to specify the property and parameter types used.

composer.json

@@ -21,18 +21,18 @@
     ],
     "require": {
         "php": "^8.2",
-        "illuminate/database": "^10.0|^11.0|^12.0|^13.0",
-        "illuminate/http": "^10.0|^11.0|^12.0|^13.0",
-        "illuminate/support": "^10.0|^11.0|^12.0|^13.0",
+        "illuminate/database": "^12.0|^13.0",
+        "illuminate/http": "^12.0|^13.0",
+        "illuminate/support": "^12.0|^13.0",
         "spatie/laravel-package-tools": "^1.11"
     },
     "require-dev": {
         "ext-json": "*",
-        "larastan/larastan": "^2.7 || ^3.3",
+        "larastan/larastan": "^3.3",
         "mockery/mockery": "^1.4",
-        "orchestra/testbench": "^7.0|^8.0|^10.0|^11.0",
-        "pestphp/pest": "^2.0|^3.7|^4.0",
-        "phpunit/phpunit": "^10.0|^11.5.3|^12.0",
+        "orchestra/testbench": "^10.0|^11.0",
+        "pestphp/pest": "^4.0",
+        "phpunit/phpunit": "^12.0",
         "spatie/invade": "^2.0"
     },
     "autoload": {

config/query-builder.php

@@ -10,16 +10,18 @@
      */
     'parameters' => [
         'include' => 'include',
-
         'filter' => 'filter',
-
         'sort' => 'sort',
-
         'fields' => 'fields',
-
         'append' => 'append',
     ],
 
+    /*
+     * The delimiter used to split array values in query parameters.
+     * For example: ?filter[name]=John,Jane uses ',' as delimiter.
+     */
+    'delimiter' => ',',
+
     /*
      * Related model counts are included using the relationship name suffixed with this string.
      * For example: GET /users?include=postsCount
@@ -32,6 +34,30 @@
      */
     'exists_suffix' => 'Exists',
 
+    /*
+     * Related model min aggregate is included using the relationship name suffixed with this string.
+     * For example: GET /users?include=postsViewsMin
+     */
+    'min_suffix' => 'Min',
+
+    /*
+     * Related model max aggregate is included using the relationship name suffixed with this string.
+     * For example: GET /users?include=postsViewsMax
+     */
+    'max_suffix' => 'Max',
+
+    /*
+     * Related model sum aggregate is included using the relationship name suffixed with this string.
+     * For example: GET /users?include=postsViewsSum
+     */
+    'sum_suffix' => 'Sum',
+
+    /*
+     * Related model avg aggregate is included using the relationship name suffixed with this string.
+     * For example: GET /users?include=postsViewsAvg
+     */
+    'avg_suffix' => 'Avg',
+
     /*
      * By default the package will throw an `InvalidFilterQuery` exception when a filter in the
      * URL is not allowed in the `allowedFilters()` method.
@@ -48,7 +74,7 @@
      * By default the package will throw an `InvalidIncludeQuery` exception when an include in the
      * URL is not allowed in the `allowedIncludes()` method.
      */
-    'disable_invalid_includes_query_exception' => false,
+    'disable_invalid_include_query_exception' => false,
 
     /*
      * By default, the package expects relationship names to be snake case plural when using fields[relationship].
@@ -71,7 +97,7 @@
      * `camelCase` => Matches table names like 'top_orders' to 'fields[topOrders]'
      * `none` => Uses the exact table name
      */
-    'convert_relation_table_name_strategy' => false,
+    'convert_relation_table_name_strategy' => null,
 
     /*
      * By default, the package expects the field names to match the database names

docs/advanced-usage/extending-query-builder.md

@@ -7,7 +7,7 @@ As the `QueryBuilder` extends Laravel's default Eloquent query builder you can u
 
 ```php
 QueryBuilder::for(User::where('id', 42)) // base query instead of model
-    ->allowedIncludes(['posts'])
+    ->allowedIncludes('posts')
     ->where('activated', true) // chain on any of Laravel's query methods
     ->first(); // we only need one specific user
 ```

docs/advanced-usage/multi-value-delimiter.md

@@ -3,51 +3,20 @@ title: Multi value delimiter
 weight: 4
 ---
 
-Sometimes values to filter for could include commas. This is why you can specify the delimiter symbol using the `QueryBuilderRequest` to overwrite the default behaviour.
+Sometimes values to filter for could include commas. You can change the delimiter used to split array values by setting the `delimiter` key in the `query-builder` config file.
 
 ```php
-// GET /api/endpoint?filter=12,4V|4,7V|2,1V
+// config/query-builder.php
 
-QueryBuilderRequest::setArrayValueDelimiter('|');
-
-QueryBuilder::for(Model::class)
-    ->allowedFilters(AllowedFilter::exact('voltage'))
-    ->get();
-
-// filters: [ 'voltage' => [ '12,4V', '4,7V', '2,1V' ]]
+return [
+    'delimiter' => '|',
+];
 ```
 
-__Note that this applies to ALL values for filters, includes and sorts__
-
-## Usage 
-
-There are multiple opportunities where the delimiter can be set.
-
-You can define it in a `ServiceProvider` to apply it globally, or define a middleware that can be applied only on certain `Controllers`.
-```php
-// YourServiceProvider.php
-public function boot() {
-    QueryBuilderRequest::setArrayValueDelimiter(';');
-}
-
-// ApplySemicolonDelimiterMiddleware.php
-public function handle($request, $next) {
-    QueryBuilderRequest::setArrayValueDelimiter(';');
-    return $next($request);
-}
-```
+With this configuration, a request like `GET /api/endpoint?filter[voltage]=12,4V|4,7V|2,1V` would be parsed as:
 
-You can also set the delimiter for each feature individually:
 ```php
-QueryBuilderRequest::setIncludesArrayValueDelimiter(';'); // Includes
-QueryBuilderRequest::setAppendsArrayValueDelimiter(';');  // Appends
-QueryBuilderRequest::setFieldsArrayValueDelimiter(';');   // Fields
-QueryBuilderRequest::setSortsArrayValueDelimiter(';');    // Sorts
-QueryBuilderRequest::setFilterArrayValueDelimiter(';');   // Filter
+// filters: [ 'voltage' => [ '12,4V', '4,7V', '2,1V' ]]
 ```
 
-You can override the default delimiter for single filters:
-```php
-// GET /api/endpoint?filter[id]=h4S4MG3(+>azv4z/I<o>,>XZII/Q1On
-AllowedFilter::exact('id', 'ref_id', true, ';');
-```
+__Note that this applies to ALL values for filters, includes and sorts.__

docs/advanced-usage/pagination.md

@@ -13,7 +13,7 @@ By default the query parameters wont be added to the pagination json. You can ap
 
 ```php
 $users = QueryBuilder::for(User::class)
-    ->allowedFilters(['name', 'email'])
+    ->allowedFilters('name', 'email')
     ->paginate()
     ->appends(request()->query());
 ```