Laravel Purity

https://github.com/abbasudo/laravel-purity
Admin
Laravel Purity is a PHP package for Laravel that adds filtering and sorting to Eloquent queries from...
Tokens:45,326
Snippets:370
Trust Score:9.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Usage Example - Direct Instantiation

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filter.md

Shows how to instantiate a filter strategy directly and apply it to a query.

```APIDOC
## Usage Example - Direct Instantiation

### Description
Demonstrates creating a filter strategy instance and applying it to an Eloquent query.

### Code

```php
use Abbasudo\Purity\Filters\Strategies\EqualFilter;

$query = Post::query();
$strategy = new EqualFilter($query, 'title', ['Purity']);
$closure  = $strategy->apply();
$closure($query);             // applies where('title', 'Purity')

EqualFilter::operator();      // '$eq'
```
```

--------------------------------

### Install Laravel Purity via Composer and publish config

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/index.md

Install the package with Composer and publish its configuration. The service provider is auto-discovered, and configuration is published to configs/purity.php.

```sh
composer require abbasudo/laravel-purity
php artisan vendor:publish --tag=purity
```

--------------------------------

### Basic example of using Resolver

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-resolve.md

Shows how to instantiate the resolver and apply a simple filter. The comment shows the resulting query.

```php
use Abbasudo\Purity\Filters\FilterList;
use Abbasudo\Purity\Filters\Resolve;

$app()->singleton(FilterList::class, fn () => (new FilterList())->only(config('purity.filters')));
$resolver = new Resolve(app(FilterList::class), new Post());

$query = Post::query();
$resolver->apply($query, 'title', ['$contains' => 'Purity']);
// $query now has: where title like '%Purity%'
```

--------------------------------

### Install Laravel Purity via Composer

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/guide/installation.md

Run this command to require the abbasudo/laravel-purity package using Composer.

```sh
composer require abbasudo/laravel-purity 

```

--------------------------------

### Class Abbasudo\Purity\Filters\FilterList

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filterlist.md

Documentation for the FilterList class, including its constructor and methods only(), keys(), and get().

```APIDOC
## Class `Abbasudo\Purity\Filters\FilterList`

### Description
Registry mapping operator strings (e.g. `$eq`) to filter strategy classes. Instances are normally created by `Filterable::bootFilter()` as an application-container singleton: `app()->singleton(FilterList::class, fn () => (new FilterList())->only($this->getFilters()))`.

### Constructor

```php
public function __construct()
```

- **Returns:** a `FilterList` pre-populated with every built-in operator from `config('purity.filters')` plus all custom filter classes found in the `config('purity.custom_filters_location')` directory (`glob("$directory/*.php")`, each file `require_once`-loaded, class name derived from namespace + basename).

### Method: `only()`

```php
public function only(array $filters): FilterList
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `$filters` | `array` | yes | — | Allow-list whose entries are either operator strings or filter strategy classes |

- **Return:** `$this` (the registry filtered to the given operators).
- Class entries are reflected (`ReflectionClass`); classes that are subclasses of `Abbasudo\Purity\Filters\Filter` are converted to their operator string via `$filter::operator()`. Non-filter classes are skipped (`catch ReflectionException`). The internal `$this->filters` map is then reduced with `collect(...)->only($filters)->all()`.

```php
$list = (new FilterList())->only(['$eq', '$in']);
$list->keys(); // ['$eq', '$in']

// strategy classes are normalized to operator strings
$list = (new FilterList())->only([EqualFilter::class, InFilter::class]);
```

### Method: `keys()`

```php
public function keys(): array
```

- **Return:** the operator strings currently registered (`array_keys($this->filters)`).
- Used by `Resolve::validate()` to build the `NoOperatorMatch` message.

```php
$operators = app(FilterList::class)->keys();
```

### Method: `get()`

```php
public function get(string $operator)
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `$operator` | `string` | yes | — | Operator string with leading `$`, e.g. `'$eq'` |

- **Return:** the strategy class registered for `$operator`, or `null` if not registered (`return $this->filters[$operator] ?? null;`). The return type is not declared in source.

```php
$class = app(FilterList::class)->get('$eq'); // Abbasudo\Purity\Filters\Strategies\EqualFilter
if ($class !== null) {
    $strategy = new $class($query, 'title', ['Purity']);
    $closure  = $strategy->apply();
}
```

### Load order

1. `loadDefault()` — `config('purity.filters')` (see [`../configuration.md`](../configuration.md)).
2. `loadCustom()` — every PHP class in `config('purity.custom_filters_location')` (defaults to `app_path('Filters')`).

`extract(array $classes)` maps each class to `$class::operator()` → class.

### Example: registering a custom filter

```php
// app/Filters/MyFilter.php (generated by `php artisan make:filter MyFilter`)
namespace App\Filters;

use Abbasudo\Purity\Filters\Filter;
use Closure;
use Illuminate\Database\Eloquent\Builder;

class MyFilter extends Filter
{
    protected static string $operator = '$myop';

    public function apply(): Closure
    {
        return function (Builder $query) {
            foreach ($this->values as $value) {
                $query->where($this->column, $value);
            }
        };
    }
}

// anywhere: the class was auto-loaded by FilterList::loadCustom()
app(FilterList::class)->get('$myop'); // App\Filters\MyFilter
```

### Reference

Source: `src/Filters/FilterList.php` — class at line 9; `__construct` line 13, `only` line 62, `keys` line 79, `get` line 84.
```

--------------------------------

### Error-handling example

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-resolve.md

Shows how to catch exceptions thrown by the resolver when silent mode is disabled. Includes NoOperatorMatch, FieldNotSupported, and OperatorNotSupported exceptions.

```php
config()->set('purity.silent', false); // surface exceptions

try {
    $resolver->apply($query, 'title', 'not-an-array'); // empty/string payload
} catch (Abbasudo\Purity\Exceptions\NoOperatorMatch $e) {
    // "No operator matches your request. Supported operators : $eq, $in, ..."
}

try {
    $resolver->apply($query, 'unknown_column', ['$eq' => 1]);
} catch (Abbasudo\Purity\Exceptions\FieldNotSupported $e) {
    // "The field 'unknown_column' is not supported for model Post. Supported fields : ..."
}

try {
    // 'title' restricted to ['$eq'] via restrictedFilters
    $resolver->apply($query, 'title', ['$contains' => 'x']);
} catch (Abbasudo\Purity\Exceptions\OperatorNotSupported $e) {
    // "The operator $contains is not supported for the field title supported operators : $eq"
}
```

--------------------------------

### availableFields() usage example

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-filterable.md

Shows a model with $filterFields set and how to introspect accepted fields at runtime using availableFields().

```php
// model
protected $filterFields = ['email', 'mobile', 'posts'];

// introspect accepted fields at runtime
$post = new Post();
$fields = $post->availableFields(); // ['email', 'mobile', 'posts']
```

--------------------------------

### Subclass apply() Implementation

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filter.md

Example implementation of the apply method within a filter subclass.

```php
public function apply(): Closure
{
    return function (Builder $query) {
        // use $this->column (+ optionally $this->query) and $this->values
        $query->where($this->column, $value);
    };
}
```

--------------------------------

### Example output of getTableColumns() for posts table

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-getcolumns.md

Shows the produced list for a model with table 'posts' and columns 'id, title'.

```php
['id', 'title', 'posts.id', 'posts.title']
```

--------------------------------

### Warning: Invalid Restricted Filter Example

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/advanced/filter/restrict.md

Shows an example that won't work because the restricted filter '$eqc' is not allowed in the $filters array. All field-restricted operations must be within the allowed filters.

```php
$filters = ['$eq'];
$restrictedFilters = ['title' => ['$eqc']] // This won't work
```

--------------------------------

### Example: registering a custom filter

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filterlist.md

Shows how to define a custom filter class and then retrieve it from the FilterList singleton. The class is auto-loaded by FilterList::loadCustom().

```php
// app/Filters/MyFilter.php (generated by `php artisan make:filter MyFilter`)
namespace App\Filters;

use Abbasudo\Purity\Filters\Filter;
use Closure;
use Illuminate\Database\Eloquent\Builder;

class MyFilter extends Filter
{
    protected static string $operator = '$myop';

    public function apply(): Closure
    {
        return function (Builder $query) {
            foreach ($this->values as $value) {
                $query->where($this->column, $value);
            }
        };
    }
}

// anywhere: the class was auto-loaded by FilterList::loadCustom()
app(FilterList::class)->get('$myop'); // App\Filters\MyFilter
```

--------------------------------

### Example custom sort subclass

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/sorts-sortabstract.md

Shows how to extend SortAbstract and implement apply() to return a sorted builder using orderByRaw.

```php
use Abbasudo\Purity\Sorts\SortAbstract;

class MySort extends SortAbstract
{
    public function apply(): Builder
    {
        return $this->query->orderByRaw("my_order({$this->column}) {$this->direction}");
    }
}
```

--------------------------------

### getRestrictedFilters() usage example

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-filterable.md

Shows how to set $filterFields and call getRestrictedFilters() to get the sanitized map.

```php
$post->filterFields = ['title:$eq', 'name'];
$restricted = $post->getRestrictedFilters();
// ['title' => ['$eq']]
```

--------------------------------

### realName() usage examples

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-getcolumns.md

Demonstrates realName() with a rename map and plain list. When a client name matches a pair value, it resolves to the key; otherwise input is returned unchanged.

```php
$fields = ['name', 'mobile' => 'phone'];
realName($fields, 'phone'); // 'mobile'
realName($fields, 'name');  // 'name'
realName($fields, 'other'); // 'other'
```

--------------------------------

### getSortField usage example

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-sortable.md

Example of getSortField resolving a client-sent field to the real column name using rename pairs.

```php
// $sortFields = ['name', 'mobile' => 'phone']
$post->getSortField('phone'); // 'mobile'
$post->getSortField('name');  // 'name'
```

--------------------------------

### Usage Example - Custom Strategy with Error Propagation

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filter.md

Shows how to create a custom filter strategy by extending the abstract Filter class.

```APIDOC
## Usage Example - Custom Strategy with Error Propagation

### Description
Demonstrates creating a custom filter strategy that throws an exception when values are missing.

### Code

```php
use Abbasudo\Purity\Filters\Filter;
use Closure;
use Illuminate\Database\Eloquent\Builder;
use RuntimeException;

class MyFilter extends Filter
{
    protected static string $operator = '$mine';

    public function apply(): Closure
    {
        return function (Builder $query) {
            if (empty($this->values)) {
                throw new RuntimeException('my filter needs values');
            }

            foreach ($this->values as $value) {
                $query->whereRaw("myfunc({$this->column}) = ?", [$value]);
            }
        };
    }
}

try {
    (new MyFilter(Post::query(), 'title', []))->apply()(Post::query());
} catch (RuntimeException $e) {
    // "my filter needs values"
}
```
```

--------------------------------

### Basic sort usage

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/sorts-sort.md

Example of sorting posts by title ascending and id descending using the Sortable trait.

```php
use Abbasudo\Purity\Traits\Sortable;

class Post extends Model { use Sortable; }

$posts = Post::sort(['title', 'id:desc'])->get();
// orderBy('title', 'asc'), orderBy('id', 'desc')
```

--------------------------------

### Using Post::sort() with various parameters

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-sortable.md

Examples of using the sort scope: basic sorting with default ascending direction, query-string driven sorting, relationship sorting with dot notation, and error handling when silent mode is off.

```php
// basic — direction defaults to 'asc'
$posts = Post::sort(['title', 'id:desc'])->sort()->get();

// query-string driven: GET /api/posts?sort[0]=title&sort[1]=id:desc
Post::sort()->get();

// relationship sort: GET /api/posts?sort=tags.name:desc
Post::sort(['tags.name:desc'])->get();

// error handling — silent mode off surfaces invalid fields
config()->set('purity.silent', false);
try {
    Post::sort(['does_not_exist:asc'])->get();
} catch (Abbasudo\Purity\Exceptions\FieldNotSupported $e) {
    // "The field 'does_not_exist' is not supported for model Post. Supported fields : ..."
}
```

--------------------------------

### HTTP request and Eloquent query flow

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/index.md

Shows the sequence from a GET request with filters and sort parameters through the Eloquent scopes and resolver to the final query execution. The package adds no HTTP routes or environment variables; it only augments Eloquent builders.

```http
GET /api/posts?filters[title][$contains]=Purity&sort=id:desc
        │
        ▼
Post::filter()          // scopeFilter: request()->query('filters', [])
Post::sort()            // scopeSort:    request()->query('sort', [])
        ▼
Resolve::apply → validates field + operator → strategy closure → $query->whereRaw(...)
          Sort   → dispatches to DefaultSort / NullSort / relation sort
        ▼
Post::filter()->sort()->get()
```

--------------------------------

### Relation sort and error handling

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/sorts-sort.md

Example of sorting by a relation, including error handling for unsupported relation types and invalid fields.

```php
// relation methods MUST declare a supported return type:
// public function tags(): BelongsToMany { return $this->belongsToMany(Tag::class); }

Post::sort(['tags.name:desc'])->get();
// joins pivot + related tables, groupBy parent, orderByRaw('max(tags.name) desc' | 'min(tags.name) desc')

// unsupported relation type — morphTo(), morphMany(), etc.
try {
    Post::sort(['postable.name:asc'])->get();
} catch (Abbasudo\Purity\Exceptions\RelationshipNotSupport $e) {
    // "Relationship not support, supported relationships hasOne, belongsTo, hasMany, belongsToMany"
}

// invalid related column
try {
    Post::sort(['tags.not_a_column:asc'])->get();
} catch (Abbasudo\Purity\Exceptions\FieldNotSupported $e) {
    // "The field 'not_a_column' is not supported for model Post. Supported fields : ..."
}
```

--------------------------------

### Using Post::sortFields()

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-sortable.md

Examples of using sortFields to override allowed sort fields for the current chain, including rename pairs.

```php
Post::sortFields('created_at', 'updated_at')->sort()->get();

Post::sortFields(['created_at' => 'published_date', 'updated_at'])->sort()->get();
```

--------------------------------

### scopeFilterFields() usage example

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-filterable.md

Example from tests: restricts filtering to the given fields for the current query chain.

```php
Book::filterFields(['book_title', 'description'])->filter()->get();
```

--------------------------------

### Nested / complex example

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-resolve.md

Shows applying nested OR filters and a relation filter with operator restriction. The comment shows the resulting whereHas query.

```php
// ?filters[$or][0][date][$eq]=2020-01-01&filters[$or][1][date][$eq]=2020-01-02
$resolver->apply($query, '$or', [
    ['date' => ['$eq' => '2020-01-01']],
    ['date' => ['$eq' => '2020-01-02']],
]);

// relation + operator restriction
$resolver->apply($query, 'author', ['name' => ['$eq' => 'John Doe']]);
// -> whereHas('author', where name = 'John Doe')
```

--------------------------------

### Basic column sorting with sort()

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/sorts-sortabstract.md

Sorts posts by a column with optional direction. The first example sorts by created_at descending. The second sorts by published_at ascending with null values placed last when the 'null_last' config is true; on pgsql this uses 'nulls last', on other databases it orders by the null flag first.

```php
// default column sort
Post::sort(['created_at:desc'])->get();

// null values last (config: 'null_last' => true)
Post::sort(['published_at:asc'])->get();
// pgsql: order by published_at asc nulls last
// other: order by published_at is null, published_at asc
```

--------------------------------

### Custom Strategy with Error Propagation

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filter.md

Example of a custom filter strategy that validates input values and throws a RuntimeException if requirements are not met.

```php
use Abbasudo\Purity\Filters\Filter;
use Closure;
use Illuminate\Database\Eloquent\Builder;
use RuntimeException;

class MyFilter extends Filter
{
    protected static string $operator = '$mine';

    public function apply(): Closure
    {
        return function (Builder $query) {
            if (empty($this->values)) {
                throw new RuntimeException('my filter needs values');
            }

            foreach ($this->values as $value) {
                $query->whereRaw("myfunc({$this->column}) = ?", [$value]);
            }
        };
    }
}

try {
    (new MyFilter(Post::query(), 'title', []))->apply()(Post::query());
} catch (RuntimeException $e) {
    // "my filter needs values"
}
```

--------------------------------

### URL query string for filtering posts

Source: https://github.com/abbasudo/laravel-purity/blob/master/README.md

Example URL query string that filters posts by title containing 'Purity'.

```http
GET /api/posts?filters[title][$contains]=Purity
```

--------------------------------

### Get table columns: Helpers::getColumns('posts')

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/helpers.md

Returns the column names of the given database table using `Schema::getColumnListing($table)`. The result includes all columns such as `'id'`, `'title'`, `'created_at'`, etc.

```php
$columns = Helpers::getColumns('posts'); // ['id', 'title', 'created_at', ...]
```

--------------------------------

### scopeFilter() usage and error handling

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-filterable.md

Examples of using Post::filter() with query string params, explicit params, and error handling when the value is not an array. Throws NoOperatorMatch unless silent mode is enabled.

```php
// basic — params come from ?filters[...]=... query string
$posts = Post::filter()->get();

// explicit params (overrides the query string source)
$posts = Post::filter(['title' => ['$eq' => 'good post']])->get();

// error handling — values is not an array at the top level
try {
    Post::filter(['title' => 'plain-string-not-array'])->get();
} catch (Abbasudo\Purity\Exceptions\NoOperatorMatch $e) {
    // "No operator matches your request. Supported operators : $eq, $in, ..."
}

```

--------------------------------

### Catching OperatorNotSupported with restricted filters

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/errors.md

Example of catching OperatorNotSupported when using a restricted operator on a field. Requires setting 'purity.silent' to false and having a model with $restrictedFilters defined.

```php
// model: $restrictedFilters = ['title' => ['$eq']];
config()->set('purity.silent', false);
try {
    Post::filter(['title' => ['$contains' => 'x']])->get();
} catch (Abbasudo\Purity\Exceptions\OperatorNotSupported $e) {
    // "The operator $contains is not supported for the field title supported operators : $eq"
}
```

--------------------------------

### Override configuration in published config file

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/configuration.md

Example of overriding the published configuration. Restricts filters to only EqualFilter and InFilter, sets 'silent' to false to surface exceptions, and sets 'null_last' to true to put NULL values last in every sort.

```php
// override in your published config
// configs/purity.php
return [
    'filters' => [EqualFilter::class, InFilter::class], // only $eq and $in are available
    'silent'  => false,    // surface exceptions
    'null_last' => true,   // NULL values last in every sort
];
```

--------------------------------

### Basic filter usage with Filterable trait

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-comparison.md

Demonstrates the basic usage of the filter pipeline. The Filterable trait enables the filter() method on a model. The first example shows filtering via query parameters, and the second shows an explicit payload form with operators like $gte, $lte, $in, and $null.

```php
use Abbasudo\Purity\Traits\Filterable;

class Post extends Model { use Filterable; }

// GET /api/posts?filters[title][$eq]=Purity&filters[id][$in][0]=1&filters[id][$in][1]=2
$posts = Post::filter()->get();

// explicit payload form
Post::filter([
    'age'  => ['$gte' => 18, '$lte' => 65],
    'id'   => ['$in' => [3, 6, 8]],
    'deleted_at' => ['$null' => null],
])->get();
```

--------------------------------

### scopeFilterBy() usage with operator strings and strategy classes

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-filterable.md

Examples of using Post::filterBy() with operator strings like '$eq' and strategy classes like EqualFilter::class. Both then use filter() to apply filters.

```php
Post::filterBy('$eq', '$in')->filter()->get();
Post::filterBy(EqualFilter::class, InFilter::class)->filter()->get();

```

--------------------------------

### FilterList::only() usage with operator strings and strategy classes

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filterlist.md

Creates a FilterList instance and filters it to only the given operators. Strategy classes are normalized to their operator strings. The example shows the resulting keys.

```php
$list = (new FilterList())->only(['$eq', '$in']);
$list->keys(); // ['$eq', '$in']

// strategy classes are normalized to operator strings
$list = (new FilterList())->only([EqualFilter::class, InFilter::class]);
```

--------------------------------

### Catching RelationshipNotSupport exception

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/errors.md

Shows how to catch the RelationshipNotSupport exception when sorting by an unsupported relation. The example sets 'purity.silent' to false, attempts to sort by 'postable.name:asc' (where postable() is a morphTo relation), and catches the exception to handle the error.

```php
config()->set('purity.silent', false);
try {
    Post::sort(['postable.name:asc'])->get(); // postable(): morphTo
} catch (Abbasudo\Purity\Exceptions\RelationshipNotSupport $e) {
    // "Relationship not support, supported relationships hasOne, belongsTo, hasMany, belongsToMany"
}
```

--------------------------------

### EqualFilter strategy class example

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-comparison.md

Shows the common structure of a filter strategy class in Laravel Purity. Each strategy extends Abbasudo\Purity\Filters\Filter, declares a static $operator, and implements apply() returning a closure that modifies the query. Instances are constructed as new $filter($query, $column, $values) and the closure is invoked with the Eloquent Builder.

```php
namespace Abbasudo\Purity\Filters\Strategies;

use Abbasudo\Purity\Filters\Filter;
use Closure;

class EqualFilter extends Filter
{
    protected static string $operator = '$eq';

    public function apply(): Closure
    {
        return function ($query) {
            foreach ($this->values as $value) {
                $query->where($this->column, $value);
            }
        };
    }
}
```

--------------------------------

### Catching FieldNotSupported exception with silent mode disabled

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/errors.md

Shows how to disable silent mode and catch the FieldNotSupported exception when filtering with an unsupported field. The example sets 'purity.silent' to false, then attempts to filter posts by 'unknown_column', catching the exception and printing its message.

```php
config()->set('purity.silent', false);
try {
    Post::filter(['unknown_column' => ['$eq' => 1]])->get();
} catch (Abbasudo\Purity\Exceptions\FieldNotSupported $e) {
    // "The field 'unknown_column' is not supported for model Post. Supported fields : id, title, ..."
}
```

--------------------------------

### Filter with direct params array

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/advanced/param.md

Passes an array of filter parameters directly to the filter function. The first example uses a variable $params, the second uses an inline array with a simple equality condition, and the third uses an $or group with nested conditions.

```php
Post::filter($params)->get();
```

```php
Post::filter([
            'title' => ['$eq' => 'good post']
        ])->get();
```

```php
Post::filter([
            '$or' => [
                'title' => [
                    '$eq' => 'good post'
                ],
                'author' => [
                    'name' => [ '$eq' => 'John Doe' ],
                    'age' => [ '$gt' => 20 ],
                ],
            ],
        ])->get();
```

--------------------------------

### Filter with custom query parameter source

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/advanced/param.md

Passes the 'find' query parameter directly to the filter function, overriding the default 'filters' source. The example shows a GET request to /api/users?find[name][$eq]=John.

```php
// this will get filters from find query params
// `GET /api/users?find[name][$eq]=John`
Post::filter(request()->query('find'))->get();
```

--------------------------------

### Instantiating a Strategy Directly

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filter.md

Demonstrates how to manually instantiate and apply a filter strategy.

```php
use Abbasudo\Purity\Filters\Strategies\EqualFilter;

$query = Post::query();
$strategy = new EqualFilter($query, 'title', ['Purity']);
$closure  = $strategy->apply();
$closure($query);             // applies where('title', 'Purity')

EqualFilter::operator();      // '$eq'
```

--------------------------------

### Get available sort columns: Helpers::getAvailableSortColumns(new User())

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/helpers.md

Returns the model's `$sortFields` array if declared, via reflection (reading even protected property). Otherwise falls back to all table columns via `getColumns()`. Used by `Sort::setField()` to validate columns in relation sorts. The example shows a model declaring `$sortFields` with an alias mapping.

```php
class User extends Model
{
    protected $sortFields = ['name', 'mobile' => 'phone'];
}

Helpers::getAvailableSortColumns(new User()); // ['name', 'mobile' => 'phone']
```

--------------------------------

### Import class: use Abbasudo\Purity\Helpers;

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/helpers.md

Imports the `Helpers` class so its static methods can be called without the full namespace. Required before using any of the documented methods.

```php
use Abbasudo\Purity\Helpers;
```

--------------------------------

### SQL patterns for $startsWithc strategy per driver

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-string.md

SQL patterns for the $startsWithc strategy across mariadb/mysql, sqlite, pgsql, and sqlsrv drivers. mariadb/mysql uses BINARY, sqlite uses COLLATE BINARY, pgsql uses LIKE, and sqlsrv uses COLLATE Latin1_General_BIN.

```php
whereRaw("BINARY `c` like ?", [v.'%'])
```

```php
whereRaw("`c` COLLATE BINARY like ?", [v.'%'])
```

```php
where(c, 'LIKE', v.'%')
```

```php
whereRaw("`c` COLLATE Latin1_General_BIN LIKE ?", [v.'%'])
```

--------------------------------

### scopeRenamedFilterFields() usage example

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-filterable.md

Renames the 'created_at' field to 'published_date' for filtering in the current query chain.

```php
Post::renamedFilterFields(['created_at' => 'published_date'])->filter()->get();
```

--------------------------------

### Add filter() to Eloquent query

Source: https://github.com/abbasudo/laravel-purity/blob/master/README.md

Add filter() to your Eloquent query to enable filtering. This is the basic usage example.

```php
$posts = Post::filter()->get();
```

--------------------------------

### PurityServiceProvider class implementation

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/service-provider.md

The service provider class. Registers config merging and, in console, publishes config and registers the make:filter command.

```php
namespace Abbasudo\Purity;

use Abbasudo\Purity\Console\FilterMakeCommand;
use Illuminate\Support\ServiceProvider;

class PurityServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->mergeConfigFrom(__DIR__.'/../config/purity.php', 'purity');
    }

    public function boot()
    {
        if ($this->app->runningInConsole()) {
            $this->publishes([
                __DIR__.'/../config/purity.php' => config_path('purity.php'),
            ], 'purity');

            $this->commands([
                FilterMakeCommand::class,
            ]);
        }
    }
}
```

--------------------------------

### Publish Laravel Purity configuration file

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/guide/installation.md

Run this artisan command to publish the configuration file (configs/purity.php) for customizing the package's behavior.

```sh
php artisan vendor:publish --tag=purity 

```

--------------------------------

### Import FilterList class

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filterlist.md

Use this import to reference the FilterList class in your PHP code.

```php
use Abbasudo\Purity\Filters\FilterList;
```

--------------------------------

### Constructor signature

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-resolve.md

Shows the constructor signature for Resolve, which takes a FilterList and a Model.

```php
public function __construct(FilterList $filterList, Model $model)
```

--------------------------------

### Combined $or/$and usage and error handling with silent mode

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-string.md

Demonstrates combining $or and $and conditions in a single filter call, using case-sensitive $containsc, and shows how to disable silent mode to surface unsupported-driver exceptions.

```php
// Find books with two possible dates and a specific author
Post::filter([
    '$or' => [
        ['date' => ['$eq' => '2020-01-01']],
        ['date' => ['$eq' => '2020-01-02']],
    ],
    'author' => ['name' => ['$eq' => 'Kai doe']],
])->get();

// case-sensitive contains
Post::filter(['title' => ['$containsc' => 'Purity']])->get();

// silent mode off → unsupported-driver failures surface
config()->set('purity.silent', false);
try {
    Post::filter(['title' => ['$containsc' => 'x']])->get();
} catch (RuntimeException $e) {
    // "Unsupported database driver: {connection}" (only on non-listed drivers)
}
```

--------------------------------

### Generate a custom filter class with artisan

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/advanced/filter/custom.md

Run this command to create a new filter class. The generated class will be placed in the `Filters` directory, which is scanned by default.

```sh
php artisan make:filter EqualFilter
```

--------------------------------

### Import Resolve class

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-resolve.md

Import the Resolve class for use in your PHP code.

```php
use Abbasudo\Purity\Filters\Resolve;
```

--------------------------------

### Restrict by Field: $restrictedFilters Property

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/advanced/filter/restrict.md

Defines restricted filters per field using the $restrictedFilters property. Note the example includes a duplicate '$eq' in the array.

```php
$restrictedFields = [
  'title' => ['$eq', '$eq'],  // title will be limited to the eq operator
  'title:$eq,$in'             // same as above
  'title'                     // this won't be restricted to any operator
];
```

--------------------------------

### Direct strategy instantiation with InFilter

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-comparison.md

Shows direct instantiation of a filter strategy. The InFilter is constructed with the query, column, and values, then apply() returns a closure that is invoked with the query. The static operator() method returns the operator string.

```php
use Abbasudo\Purity\Filters\Strategies\InFilter;

$query = Post::query();
$strategy = new InFilter($query, 'id', [3, 6, 8]);
$strategy->apply()($query);   // whereIn('id', [3, 6, 8])

InFilter::operator();         // '$in'
```

--------------------------------

### Catching NoOperatorMatch with silent mode disabled

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/errors.md

Example of catching NoOperatorMatch when filtering with a raw string value. Requires setting 'purity.silent' to false to enable exception throwing.

```php
config()->set('purity.silent', false);
try {
    Post::filter(['title' => 'raw-string'])->get(); // $values is a string
} catch (Abbasudo\Purity\Exceptions\NoOperatorMatch $e) {
    // "No operator matches your request. Supported operators : $eq, $in, $between, ..."
}
```

--------------------------------

### apply method signature

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-resolve.md

Shows the apply method signature that mutates the query builder.

```php
public function apply(Builder $query, string $field, array|string $values): void
```

--------------------------------

### BelongsToSort apply method

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/sorts-sortabstract.md

Sorts parent query by a correlated sub-query on the related table. Keys from relation: getQualifiedForeignKeyName() and getQualifiedOwnerKeyName(). Example: Post::sort(['user.name:asc']).

```php
return $this->query->orderBy(
    $relatedModel::query()
    ->select("{$relatedTable}.{$this->column}")
    ->whereColumn($localKey, $foreignKeyKey)
    ->orderByRaw("{$relatedTable}.{$this->column} {$this->direction}")
    ->limit(1),
    $this->direction
);
```

--------------------------------

### Composer auto-registration for PurityServiceProvider

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/service-provider.md

JSON configuration in composer.json that auto-registers the service provider. Required for the package to load.

```json
"extra": { "laravel": { "providers": ["Abbasudo\\Purity\\PurityServiceProvider"] } }
```

--------------------------------

### Laravel Example: Complex Relation Filter

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/js-examples/filter.md

Implement the same complex relation filter manually in Laravel by passing an array of filters to the filter() method. The Restaurant model must have the filter scope defined.

```php
$params = [
    'filters' => [
        'chef' => [
            'restaurants' => [
                'stars' => [
                    '$eq' => 5,
                ],
                'cuisine' => [
                    '$eq' => 'Italian',
                ],
            ],
        ],
    ],
];

$restaurants = Restaurant::filter($params)->get();
```

--------------------------------

### SQL patterns for $endsWithc strategy per driver

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-string.md

SQL patterns for the $endsWithc strategy across mariadb/mysql, sqlite, pgsql, and sqlsrv drivers. mariadb/mysql uses BINARY, sqlite uses COLLATE BINARY, pgsql uses LIKE, and sqlsrv uses COLLATE Latin1_General_BIN.

```php
whereRaw("BINARY `c` like ?", '%'.v)
```

```php
whereRaw("`c` COLLATE BINARY like ?", '%'.v)
```

```php
where(c, 'LIKE', '%'.v)
```

```php
whereRaw("`c` COLLATE Latin1_General_BIN LIKE ?", '%'.v)
```

--------------------------------

### Use getColumns trait (already pulled in by Filterable / Sortable)

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-getcolumns.md

Shows how to use the getColumns trait, though it is already included by Filterable and Sortable.

```php
use getColumns; // already pulled in by Filterable / Sortable
```

--------------------------------

### SQL patterns for $notContainsc strategy per driver

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-string.md

SQL patterns for the $notContainsc strategy across mariadb/mysql, sqlite, pgsql, and sqlsrv drivers. mariadb/mysql uses BINARY, sqlite uses COLLATE BINARY, pgsql uses whereNot with LIKE, and sqlsrv uses COLLATE Latin1_General_BIN.

```php
whereRaw("BINARY `c` not like ?", ["%v%"])
```

```php
whereRaw("`c` COLLATE BINARY not like ?", ["%v%"])
```

```php
whereNot(c, 'LIKE', "%v%")
```

```php
whereRaw("`c` COLLATE Latin1_General_BIN not LIKE ?", ["%v%"])
```

--------------------------------

### Import Sort class

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/sorts-sort.md

Imports the Sort class for use in PHP code.

```php
use Abbasudo\Purity\Sorts\Sort;
```

--------------------------------

### Rename Sort Fields in Model

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/advanced/rename.md

Define renamed sort fields in the model using the $sortFields property. Maps client-side field names to actual database column names for sorting. Example URL: ?sort=phone.

```php
// App\Models\User

// Example URL: ?sort=phone

// The $sortFields property is used to map the client-side field names to the actual database column names for sorting.
protected $sortFields = [
  'name',
  'mobile' => 'phone', // The actual database column is 'mobile', but the client should use 'phone' for sorting.
];
```

--------------------------------

### FilterMakeCommand class implementation

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/service-provider.md

Console generator command that scaffolds a new filter class. Uses the make:filter signature and supports a --force option.

```php
namespace Abbasudo\Purity\Console;

use Illuminate\Console\GeneratorCommand;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Input\InputOption;

#[AsCommand(name: 'make:filter')]
class FilterMakeCommand extends GeneratorCommand
{
    protected $name = 'make:filter';
    protected $description = 'Create a new filter class';
    protected $type = 'Filter';

    protected function getStub(): string
    {
        return $this->resolveStubPath('/stubs/filter.stub');
    }

    protected function resolveStubPath($stub): string
    {
        return file_exists($customPath = $this->laravel->basePath(trim($stub, '/')))
            ? $customPath
            : __DIR__.$stub;
    }

    protected function getDefaultNamespace($rootNamespace): string
    {
        return $rootNamespace.'\Filters';
    }

    protected function getOptions(): array
    {
        return [
            ['force', 'f', InputOption::VALUE_NONE, 'Create the class even if the filter already exists'],
        ];
    }
}
```

--------------------------------

### CustomFilterResolver extends Resolve and overrides apply()

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-resolve.md

Use this snippet to create a custom resolver that intercepts the '$pure' value and delegates to parent::apply() with a modified field. The model selects this resolver by overriding getFilterResolver(). The example is referenced in tests/App/Filters/CustomFilterResolver.php.

```php
class CustomFilterResolver extends Resolve
{
    public function apply(Builder $query, string $field, array|string $values): void
    {
        if (isset($values['$pure']) && $values['$pure'] === 'true') {
            parent::apply($query, $field, ['$startsWith' => 'pure_']);
            return;
        }

        parent::apply($query, $field, $values);
    }
}
```

--------------------------------

### Sort using 2 fields and set the order

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/js-examples/sort.md

Sorts articles by title ascending and slug descending. Uses qs.stringify with encodeValuesOnly to prettify the URL.

```javascript
const qs = require('qs');
const query = qs.stringify({
  sort: ['title:asc', 'slug:desc'],
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);
```

--------------------------------

### php artisan make:filter

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/service-provider.md

Console command to scaffold a new filter strategy class. Supports an optional --force flag to recreate an existing filter.

```APIDOC
## Command: php artisan make:filter {name}

### Description
Creates a new filter class in the app/Filters directory (or custom location). The generated class extends Abbasudo\Purity\Filters\Filter and implements an apply method.

### Usage
`php artisan make:filter EqualFilter`

### Options
- **--force** (`-f`) - Optional - Create the class even if the filter already exists.

### Generated File
Creates a PHP file with the class name in the `app/Filters` namespace (configurable via `custom_filters_location`). The class extends `Filter` and uses `$eq` operator.

### Response
No response body; exit code 0 on success. If the file exists and --force not used, it will ask for confirmation.
```

--------------------------------

### Rename Filter Fields in Model

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/advanced/rename.md

Define renamed filter fields in the model using the $renamedFilterFields property. Maps client-side field names to actual database column names. Example URL: ?filter[phone][$eq]=0000000000.

```php
// App\Models\User

// Example URL: ?filter[phone][$eq]=0000000000

// The $renamedFilterFields property is used to map the client-side field names to the actual database column names.
protected $renamedFilterFields = [
  'mobile' => 'phone', // The actual database column is 'mobile', but the client should use 'phone'.
  'posts'  => 'writing', // The actual relation is 'posts', but the client should use 'writing'.
];
```

--------------------------------

### Direct applySort call

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-sortable.md

Direct call to applySort with a column, raw sort token, and builder.

```php
// called internally by scopeSort, but callable directly
$builder = $post->applySort('title', 'title:desc', Post::query());
```

--------------------------------

### AndFilter::apply() and OrFilter::apply() implementations

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-string.md

Condensed source for AndFilter and OrFilter. AndFilter groups each filter map into an AND-where closure; OrFilter wraps each in an orWhere branch. Both re-enter Resolve::apply() for nested conditions.

```php
// AndFilter::apply() — condensed from source
return function ($query) {
    foreach ($this->values as $value) {
        $query->where(function ($query) use ($value) {
            foreach ($value as $key => $item) {
                app(Resolve::class)->apply($query, $key, $item);
            }
        });
    }
};

// OrFilter::apply() — condensed from source
return function ($query) {
    $query->where(function ($query) {
        foreach ($this->values as $value) {
            $query->orWhere(function ($query) use ($value) {
                foreach ($value as $key => $item) {
                    app(Resolve::class)->apply($query, $key, $item);
                }
            });
        }
    });
};
```

--------------------------------

### Sort using 2 fields

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/js-examples/sort.md

Sorts articles by title and slug in ascending order (default). Uses qs.stringify with encodeValuesOnly to prettify the URL.

```javascript
const qs = require('qs');
const query = qs.stringify({
  sort: ['title', 'slug'],
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);
```

--------------------------------

### Eq Filter with qs

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/js-examples/filter.md

Use qs to build a query string for the $eq filter. The encodeValuesOnly option prettifies the URL. The resulting query is appended to the /api/users endpoint.

```javascript
const qs = require('qs');
const query = qs.stringify({
  filters: {
    username: {
      $eq: 'John',
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/users?${query}`);
```

--------------------------------

### Get model relations: Helpers::getRelations(Post::class)

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/helpers.md

Returns an array of relation method names for the given model. Uses reflection to keep only methods whose declared return type contains `Illuminate\Database\Eloquent\Relations`. Methods without a return type are ignored. May throw `ReflectionException` if the class cannot be resolved.

```php
$relations = Helpers::getRelations(Post::class);
// e.g. ['comments', 'user', 'tags', 'postable']
```

--------------------------------

### DefaultSort apply method

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/sorts-sortabstract.md

Plain orderBy(column, direction). Used when purity.null_last is falsy.

```php
public function apply(): Builder
{
    return $this->query->orderBy($this->column, $this->direction);
}
```

--------------------------------

### Global Filters: Config File (configs/purity.php)

Source: https://github.com/abbasudo/laravel-purity/blob/master/docs/advanced/filter/restrict.md

Defines allowed filters globally in the config file. These are the lowest priority and are overwritten by model $filters and filterBy().

```php
// configs/purity.php
'filters' => [
  EqualFilter::class,
  InFilter::class,
],
```

--------------------------------

### Constructor Signature

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-filter.md

The constructor signature for the abstract Filter class.

```php
public function __construct(Builder $query, string $column, array $values)
```

--------------------------------

### Import and use Sortable trait

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/traits-sortable.md

Import the Sortable trait and apply it to an Eloquent model to enable sorting scopes.

```php
use Abbasudo\Purity\Traits\Sortable;

class Post extends Model
{
    use Sortable;
}
```

--------------------------------

### SQL patterns for $containsc strategy per driver

Source: https://github.com/abbasudo/laravel-purity/blob/master/_autodocs/api-reference/filters-strategies-string.md

SQL patterns for the $containsc strategy across mariadb/mysql, sqlite, pgsql, and sqlsrv drivers. mariadb/mysql uses BINARY, sqlite uses COLLATE BINARY, pgsql uses ILIKE, and sqlsrv uses COLLATE Latin1_General_BIN.

```php
whereRaw("BINARY `c` like ?", ["%v%"])
```

```php
whereRaw("`c` COLLATE BINARY like ?", ["%v%"])
```

```php
where(c, 'ILIKE', "%v%")
```

```php
whereRaw("`c` COLLATE Latin1_General_BIN LIKE ?", ["%v%"])
```
Tokens:
Raw