Add support for boolean filter groups and operators

Author: tobyzerner

CHANGELOG.md

@@ -8,6 +8,25 @@ and this project adheres to
 
 ## [Unreleased]
 
+### ⚠️ Breaking Changes
+
+- `Tobyz\\JsonApiServer\\Laravel\\Filter\\EloquentFilter` renamed to
+  `ColumnFilter`.
+- Remove the `Has` Laravel filter; use `WhereExists` instead.
+- Remove the `WhereDoesntHave` Laravel filter; use the operator support on
+  `WhereHas` instead.
+- Remove `Where::asNumber()`; express numeric comparisons with operators such as
+  `filter[score][gt]=...` or `filter[score][lte]=...`.
+
+### Added
+
+- Add support for boolean filter groups (`filter[and]`, `filter[or]`,
+  `filter[not]`) for resources that implement the `SupportsBooleanFilters`
+  interface
+- Laravel: Add support for boolean filter groups to `EloquentResource`
+- Laravel: Overhaul filter implementations to support operators like `eq`, `ne`,
+  `in`, `lt`, `lte`, `gt`, `gte`, `like`, `notlike`, `null`, and `notnull`
+
 ## [1.0.0-beta.4] - 2025-05-02
 
 ### Added

docs/laravel.md

@@ -166,23 +166,28 @@ BooleanDateTime::make('isDeleted')
 The Laravel integration provides a number of filters for use in your Eloquent
 resources.
 
-### Where
+### Where Filters
 
 ```php
 Where::make('name');
 Where::make('id')->commaSeparated();
 Where::make('isConfirmed')->asBoolean();
-Where::make('score')->asNumeric();
-WhereBelongsTo::make('user');
-Has::make('hasComments');
-WhereHas::make('comments');
-WhereDoesntHave::make('comments');
-WhereNull::make('draft')->property('published_at');
-WhereNotNull::make('published')->property('published_at');
-Scope::make('withTrashed');
+WhereBelongsTo::make('author')->relationship('user');
+WhereExists::make('comments');
+WhereCount::make('commentCount')->relationship('comments');
+WhereHas::make('tags');
+WhereNull::make('draft')->column('published_at');
+WhereNotNull::make('published')->column('published_at');
+Scope::make('withTrashed')->asBoolean();
 Scope::make('trashed')->scope('onlyTrashed');
 ```
 
+### Boolean Filters
+
+`EloquentResource` implements
+`Tobyz\\JsonApiServer\\Resource\\SupportsBooleanFilters`, so you can combine
+filters with `[and]`, `[or]`, and `[not]` groups without extra configuration.
+
 ## Sort Fields
 
 The Laravel integration provides a number of sort fields for use in your

docs/list.md

@@ -218,6 +218,38 @@ GET /posts?filter[name]=Toby
 GET /posts?filter[name][]=Toby&filter[name][]=Franz
 ```
 
+### Boolean Filters
+
+By default it is assumed that each filter applied to the query will be combined
+with a logical `AND`. When a resource implements
+`Tobyz\\JsonApiServer\\Resource\\SupportsBooleanFilters` you can express more
+complex logic with `AND`, `OR`, and `NOT` groups.
+
+Boolean groups are expressed by nesting objects under the `filter` parameter.
+You may use either associative objects or indexed lists of clauses. Each clause
+can be another filter or another boolean group.
+
+```http
+GET /posts
+  ?filter[and][0][status]=published
+  &filter[and][1][or][0][views][gt]=100
+  &filter[and][1][or][1][not][status]=archived
+```
+
+In this request every result must be published, and it must also either have
+more than 100 views or it is not archived.
+
+```http
+GET /posts
+  ?filter[or][0][status]=draft
+  &filter[or][1][status]=published
+  &filter[or][1][not][comments]=0
+```
+
+This request returns drafts, or posts that are published and have comments. The
+second example also shows that in certain cases you can omit `[and]` groups and
+numeric indices; sibling filters at the same level default to `AND` behaviour.
+
 ### Writing Filters
 
 To create your own filter class, extend the `Tobyz\JsonApiServer\Schema\Filter`

src/Filterer.php

@@ -0,0 +1,111 @@
+<?php
+
+namespace Tobyz\JsonApiServer;
+
+use Tobyz\JsonApiServer\Exception\BadRequestException;
+use Tobyz\JsonApiServer\Resource\Collection;
+use Tobyz\JsonApiServer\Resource\Listable;
+use Tobyz\JsonApiServer\Resource\SupportsBooleanFilters;
+
+class Filterer
+{
+    public function __construct(
+        private readonly Collection&Listable $collection,
+        private Context $context,
+    ) {
+        $this->context = $context->withCollection($collection);
+    }
+
+    public function apply($query, array $filters): void
+    {
+        $this->applyGroup($query, $filters, 'and', []);
+    }
+
+    private function applyGroup($query, array $filters, string $boolean, array $path): void
+    {
+        $clauses = [];
+        $availableFilters = $this->resolveAvailableFilters();
+
+        foreach ($filters as $key => $value) {
+            $keyPath = [...$path, $key];
+
+            if (
+                $this->collection instanceof SupportsBooleanFilters &&
+                in_array($key, ['and', 'or', 'not'])
+            ) {
+                if (!is_array($value)) {
+                    throw $this->badRequest(
+                        'Boolean groups must be objects or lists of clauses',
+                        $keyPath,
+                    );
+                }
+
+                $clauses[] = fn($query) => $this->applyGroup($query, $value, $key, $keyPath);
+
+                continue;
+            }
+
+            if (is_int($key)) {
+                if (!is_array($value)) {
+                    throw $this->badRequest(
+                        'Filter clauses must be expressed as objects',
+                        $keyPath,
+                    );
+                }
+
+                $clauses[] = fn($query) => $this->applyGroup($query, $value, 'and', $keyPath);
+
+                continue;
+            }
+
+            if (!($filter = $availableFilters[$key] ?? null)) {
+                throw $this->badRequest("Invalid filter: $key", $keyPath);
+            }
+
+            $clauses[] = fn($query) => $filter->apply($query, $value, $this->context);
+        }
+
+        if (!$clauses) {
+            return;
+        }
+
+        if ($this->collection instanceof SupportsBooleanFilters) {
+            if ($boolean === 'or') {
+                $this->collection->filterOr($query, $clauses);
+
+                return;
+            }
+
+            if ($boolean === 'not') {
+                $this->collection->filterNot($query, $clauses);
+
+                return;
+            }
+        }
+
+        foreach ($clauses as $clause) {
+            $clause($query);
+        }
+    }
+
+    private function resolveAvailableFilters(): array
+    {
+        $filters = [];
+
+        foreach ($this->collection->filters() as $filter) {
+            if ($filter->isVisible($this->context)) {
+                $filters[$filter->name] = $filter;
+            }
+        }
+
+        return $filters;
+    }
+
+    private function badRequest(string $message, array $path): BadRequestException
+    {
+        return (new BadRequestException($message))->setSource([
+            'parameter' =>
+                '[' . implode('][', array_map(fn($segment) => (string) $segment, $path)) . ']',
+        ]);
+    }
+}

src/Laravel/EloquentResource.php

@@ -18,6 +18,7 @@
 use Tobyz\JsonApiServer\Resource\Findable;
 use Tobyz\JsonApiServer\Resource\Listable;
 use Tobyz\JsonApiServer\Resource\Paginatable;
+use Tobyz\JsonApiServer\Resource\SupportsBooleanFilters;
 use Tobyz\JsonApiServer\Resource\Updatable;
 use Tobyz\JsonApiServer\Schema\Field\Attribute;
 use Tobyz\JsonApiServer\Schema\Field\Field;
@@ -32,7 +33,8 @@ abstract class EloquentResource extends AbstractResource implements
     Paginatable,
     Creatable,
     Updatable,
-    Deletable
+    Deletable,
+    SupportsBooleanFilters
 {
     public function resource(object $model, Context $context): ?string
     {
@@ -240,6 +242,34 @@ public function delete(object $model, Context $context): void
         $model->delete();
     }
 
+    public function filterOr(object $query, array $clauses): void
+    {
+        if (!$clauses) {
+            return;
+        }
+
+        $query->where(function ($query) use ($clauses) {
+            foreach ($clauses as $clause) {
+                $query->orWhere(function ($nested) use ($clause) {
+                    $clause($nested);
+                });
+            }
+        });
+    }
+
+    public function filterNot(object $query, array $clauses): void
+    {
+        if (!$clauses) {
+            return;
+        }
+
+        $query->whereNot(function ($nested) use ($clauses) {
+            foreach ($clauses as $clause) {
+                $clause($nested);
+            }
+        });
+    }
+
     /**
      * Get the model property that a field represents.
      */

src/Laravel/Filter/ColumnFilter.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Laravel\Filter;
+
+use Illuminate\Contracts\Database\Query\Expression;
+use Illuminate\Support\Str;
+use Tobyz\JsonApiServer\Schema\Filter;
+
+abstract class ColumnFilter extends Filter
+{
+    protected string|Expression|null $column = null;
+
+    public static function make(string $name): static
+    {
+        return new static($name);
+    }
+
+    public function column(string|Expression|null $column): static
+    {
+        $this->column = $column;
+
+        return $this;
+    }
+
+    protected function getColumn(): string|Expression
+    {
+        return $this->column ?: Str::snake($this->name);
+    }
+}