Move docs

CHANGELOG.md

@@ -4,7 +4,8 @@ All notable changes to `laravel-query-builder` will be documented in this file
 
 ## 2.6.0 - 2020-02-10
 
-- add `FilterTrashed` for filtering soft-deleted models
+- add `FiltersTrashed` for filtering soft-deleted models
+- add `FiltersCallback` for filtering using a callback
 
 ## 2.5.1 - 2020-01-22
 

docs/features/filtering.md

@@ -151,6 +151,32 @@ QueryBuilder::for(Booking::class)
 // GET /bookings?filter[trashed]=only will only return soft deleted models
 ```
 
+## Callback filters
+
+If you want to define a tiny custom filter, you can use a callback filter. Using `AllowedFilter::callback(string $name, callable $filter)` you can specify a callable that will executed when the filter is requested. 
+
+The filter callback will receive the following parameters: `Builder $query, mixed $value, string $name`. You can modify the `Builder` object to add your own query constraints.
+
+For example:
+
+```php
+QueryBuilder::for(User::class)
+    ->allowedFilters([
+        AllowedFilter::callback('has_posts', function (Builder $query, $value) {
+            $query->whereHas('posts');
+        }),
+    ]);
+```
+
+Using PHP 7.4 this example becomes a lot shorter:
+
+```php
+QueryBuilder::for(User::class)
+    ->allowedFilters([
+        AllowedFilter::callback('has_posts', fn (Builder $query) => $query->whereHas('posts')),
+    ]);
+```
+
 ## Custom filters
 
 You can specify custom filters using the `AllowedFilter::custom()` method. Custom filters are instances of invokable classes that implement the `\Spatie\QueryBuilder\Filters\Filter` interface. The `__invoke` method will receive the current query builder instance and the filter name/value. This way you can build any query your heart desires.

src/Filters/FiltersCallback.php

@@ -4,36 +4,6 @@
 
 use Illuminate\Database\Eloquent\Builder;
 
-/**
- * FiltersCallback provides filtering based on a PHP callback.
- *
- * Such callback should follow signature of {@see \Spatie\QueryBuilder\Filters\Filter::__invoke()}:
- *
- * ```php
- * function (\Illuminate\Database\Eloquent\Builder $builder, mixed $value, string $property)
- * ```
- *
- * For example:
- *
- * ```php
- * QueryBuilder::for(Item::class)
- *     ->allowedFilters([
- *         AllowedFilter::callback('trashed', function (Builder $query, $value) {
- *             if ($value === 'only') {
- *                 return $query->onlyTrashed();
- *             }
- *
- *             if ($value === 'with') {
- *                 return $query->withTrashed();
- *             }
- *
- *             $query->withoutTrashed();
- *         }),
- *     ]);
- * ```
- *
- * @see \Spatie\QueryBuilder\AllowedFilter::callback()
- */
 class FiltersCallback implements Filter
 {
     /**