docs: rewrite documentation with real-world examples

- Rewrite README with quick example and feature summary
- Rewrite usage docs with practical controller examples
- Rewrite strategies docs with complete real-world strategy
- Rewrite clauses docs with clause resolution explanation
- Rewrite transmutes docs with custom transmute ideas
- Rewrite configuration docs with custom parameter names

Author: oniice

README.md

@@ -1,6 +1,6 @@
 # Laravel Query Strategies
 
-A package to help build queries with Eloquent Builder from URL parameters in a request.
+Build safe, flexible API endpoints by turning URL query parameters into Eloquent queries. Define a strategy that controls exactly which filters, sorts, fields, and relationships your API consumers can use.
 
 [![Latest Stable Version](https://poser.pugx.org/myerscode/laravel-query-strategies/v/stable)](https://packagist.org/packages/myerscode/laravel-query-strategies)
 [![Total Downloads](https://poser.pugx.org/myerscode/laravel-query-strategies/downloads)](https://packagist.org/packages/myerscode/laravel-query-strategies)
@@ -14,31 +14,68 @@ A package to help build queries with Eloquent Builder from URL parameters in a r
 - PHP ^8.5
 - Laravel ^13.0
 
-## Why this package is helpful?
+## Quick Example
 
-If you want to apply query clauses to Eloquent Models using parameters passed by the user, then this package will allow you to create strategies that will enable them to be applied automatically.
+Given a `ProductStrategy` that defines which parameters are allowed:
 
-Using query strategies you can define what properties a user can have access to offering a safer way for them interact with your data schemas.
+```php
+class ProductStrategy extends Strategy
+{
+    protected array $canOrderBy = ['name', 'price', 'created_at'];
+    protected array $canWith = ['category', 'reviews'];
+    protected array $allowedFields = ['id', 'name', 'price', 'category_id'];
+    protected array $allowedAppends = ['discount_price'];
 
-Strategies can obfuscate the real column names, add aliases to them and enable/disable the query clauses that can be applied to the model.
+    protected array $config = [
+        'name'     => ['filter' => ContainsClause::class],
+        'price'    => ['column' => 'unit_price'],
+        'category' => ['column' => 'category_id', 'explode' => true],
+    ];
+}
+```
 
-You can work the builder before and after applying a strategy, so it can be easily integrated with existing code and queries.
+Your API consumers can now query like this:
 
-## Installation
+```
+GET /products?name=laptop&price=500&category=1,2,3&order=price&sort=desc&limit=10&with=reviews&fields=id,name,price&append=discount_price
+```
 
-You can install the package via composer:
+And in your controller:
+
+```php
+use function Myerscode\Laravel\QueryStrategies\filter;
+
+public function index()
+{
+    return filter(Product::class)->with(ProductStrategy::class)->apply();
+}
+```
+
+That single line handles filtering, sorting, field selection, eager loading, accessor appending, limiting, and pagination — all controlled by the strategy.
+
+## Why Use This?
+
+- **Safe by default** — only parameters defined in your strategy are applied. Unknown parameters are ignored (or rejected in strict mode).
+- **Column obfuscation** — map public parameter names to real database columns so your schema stays private.
+- **Flexible clauses** — 17 built-in filter clauses (equals, contains, between, greater than, etc.) with operator overrides via URL.
+- **Relationship support** — filter through relationships with dot notation, sort by relationship columns, and control eager loading.
+- **Composable** — chain individual methods (`filter()`, `order()`, `fields()`, etc.) or call `apply()` to run everything at once.
+
+## Installation
 
 ```bash
 composer require myerscode/laravel-query-strategies
 ```
 
+The package auto-discovers its service provider. No manual registration needed.
+
 ## Documentation
 
-- [Usage](docs/usage.md) — Getting started, filter methods, query parameter syntax, and pagination
-- [Configuration](docs/configuration.md) — Publishing and customising the config file
-- [Strategies](docs/strategies.md) — Defining strategies, parameter config options, ordering, limiting, and eager loads
-- [Clauses](docs/clauses.md) — Built-in clauses, aliases, and creating custom clauses
-- [Transmutes](docs/transmutes.md) — Value transformation with built-in and custom transmutes
+- [Usage](docs/usage.md) — Getting started, creating filters, query parameter syntax, and pagination
+- [Strategies](docs/strategies.md) — Defining strategies, parameter options, ordering, limiting, eager loads, and default filters
+- [Clauses](docs/clauses.md) — Built-in clauses, scope and trashed filtering, callbacks, and custom clauses
+- [Transmutes](docs/transmutes.md) — Transforming values before filtering
+- [Configuration](docs/configuration.md) — Customising parameter names and strict mode
 
 ## License
 

docs/clauses.md

@@ -1,6 +1,6 @@
 # Clauses
 
-Clauses define how a filter value is applied to the Eloquent query builder. Each clause maps to a SQL WHERE condition.
+Clauses define how a filter value translates into a SQL condition. When a user sends `?name=John`, the clause determines whether that becomes `WHERE name = 'John'`, `WHERE name LIKE '%John%'`, or something else entirely.
 
 ## Built-in Clauses
 
@@ -20,86 +20,100 @@ Clauses define how a filter value is applied to the Eloquent query builder. Each
 | `IsNotInClause` | `WHERE column NOT IN (...)` | `notIn`, `!in` |
 | `IsNullClause` | `WHERE column IS NULL` | `isNull`, `null` |
 | `IsNotNullClause` | `WHERE column IS NOT NULL` | `isNotNull`, `!null`, `notNull` |
-| `TrashedClause` | Soft delete filtering (`with`, `only`) | — |
 | `OrEqualsClause` | `OR WHERE column = value` | `or`, `\|\|` |
 | `ScopeClause` | Calls a model scope | — |
+| `TrashedClause` | Soft delete filtering | — |
 
-Aliases are used in operator overrides. For example, `?name--contains=John` uses the `ContainsClause`.
+## How Clauses Are Resolved
+
+When a request comes in, the package resolves which clause to use in this order:
+
+1. If the parameter has a `callback` defined, that runs instead of any clause.
+2. If the user specifies an operator override (e.g. `?name--contains=John`), the alias is looked up in the parameter's methods and the strategy's default methods.
+3. If the parameter has a `filter` or `default` clause class set, that's used.
+4. If multiple values are provided, the `multi` clause is used (defaults to `IsInClause`).
+5. Otherwise, the global default `EqualsClause` is used.
+
+## Operator Overrides
+
+API consumers can override the default clause for any parameter by appending `--` and a clause alias:
+
+```
+?name--contains=lap        → WHERE name LIKE '%lap%'
+?price--gte=100            → WHERE price >= 100
+?price--between=10,500     → WHERE price BETWEEN 10 AND 500
+?email--beginsWith=admin   → WHERE email LIKE 'admin%'
+?status--isNull            → WHERE status IS NULL
+```
+
+This gives consumers flexibility without you needing to define separate parameters for each operation.
 
 ## Scope Clause
 
-The `ScopeClause` calls an Eloquent local scope on the model instead of applying a direct WHERE condition. The parameter name is converted to camelCase to match the scope method name.
+The `ScopeClause` calls an Eloquent local scope instead of applying a direct WHERE condition. The parameter name is converted to camelCase to match the scope method.
+
+Say your model has:
 
 ```php
-// Model scope
 public function scopeStartsBefore(Builder $query, string $date): Builder
 {
     return $query->where('starts_at', '<=', $date);
 }
+```
+
+Configure it in your strategy:
 
-// Strategy config
+```php
 protected array $config = [
     'starts_before' => [
-        'default' => ScopeClause::class,
+        'filter' => ScopeClause::class,
     ],
 ];
 ```
 
-Usage: `?starts_before=2024-01-01`
+Then `?starts_before=2024-01-01` calls `scopeStartsBefore($query, '2024-01-01')`.
 
-Multiple parameters can be passed to a scope using comma-separated values:
+Scopes that accept multiple arguments work with comma-separated values:
 
 ```
 ?created_between=2024-01-01,2024-12-31
+→ scopeCreatedBetween($query, '2024-01-01', '2024-12-31')
 ```
 
-This calls `scopeCreatedBetween($query, '2024-01-01', '2024-12-31')`.
-
 Empty values are ignored — the scope won't be called.
 
 ## Trashed Clause
 
-The `TrashedClause` provides built-in soft delete filtering for models using Laravel's `SoftDeletes` trait.
+For models using Laravel's `SoftDeletes` trait, the `TrashedClause` provides built-in soft delete control:
 
 ```php
 protected array $config = [
     'trashed' => [
-        'default' => TrashedClause::class,
+        'filter' => TrashedClause::class,
     ],
 ];
 ```
 
-Accepted values:
-
 | Value | Behaviour |
 |---|---|
-| `with` | Include soft-deleted records in results |
-| `only` | Return only soft-deleted records |
+| `?trashed=with` | Include soft-deleted records alongside active ones |
+| `?trashed=only` | Return only soft-deleted records |
 | Any other value | Default behaviour (exclude soft-deleted) |
 
-Usage:
-
-```
-?trashed=with    → Include trashed records
-?trashed=only    → Only trashed records
-```
-
 ## Callback Filters
 
-For one-off filters that don't warrant a full clause class, use the `callback` config option:
+For one-off filters that don't warrant a full clause class, use a closure:
 
 ```php
 protected array $config = [
-    'has_posts' => [
-        'callback' => static function ($builder, $value, $column): void {
-            $builder->whereHas('posts');
-        },
+    // Simple boolean check
+    'has_reviews' => [
+        'callback' => fn ($builder, $value, $column) => $builder->whereHas('reviews'),
     ],
+
+    // Value-dependent filter
     'min_score' => [
-        'callback' => static function ($builder, $value, $column): void {
-            $val = is_array($value) ? $value[0] : $value;
-            $builder->where('score', '>=', $val);
-        },
+        'callback' => fn ($builder, $value, $column) => $builder->where('score', '>=', is_array($value) ? $value[0] : $value),
     ],
 ];
 ```
@@ -108,13 +122,13 @@ The closure receives `(Builder $builder, mixed $value, string $column)`. When a
 
 ## Creating a Custom Clause
 
-Generate a clause using the artisan command:
+Generate one with artisan:
 
 ```bash
 php artisan make:clause ILikeClause
 ```
 
-This creates a class in `app/Queries/Clause/`. Implement the `filter` method:
+This creates `app/Queries/Clause/ILikeClause.php`. Implement the `filter` method:
 
 ```php
 use Illuminate\Database\Eloquent\Builder;
@@ -141,16 +155,16 @@ class ILikeClause extends AbstractClause
 }
 ```
 
-### Using a Custom Clause
-
-Register it in your strategy's `$config`:
+Use it in your strategy:
 
 ```php
 protected array $config = [
+    // As the default clause for a parameter
     'name' => [
-        'default' => ILikeClause::class,
+        'filter' => ILikeClause::class,
     ],
-    // Or as a named method alias
+
+    // As a named method alias (usable via operator override)
     'email' => [
         'methods' => [
             'ilike' => ILikeClause::class,
@@ -159,11 +173,12 @@ protected array $config = [
 ];
 ```
 
-You can also add it to the strategy's `$defaultMethods` to make it available to all parameters:
+With the methods approach, users can opt in: `?email--ilike=admin`.
+
+You can also register a custom clause globally by overriding `$defaultMethods` in your strategy, making it available to all parameters:
 
 ```php
 protected array $defaultMethods = [
-    // Include parent defaults
     ...parent::$defaultMethods,
     ILikeClause::class => ['ilike', '~'],
 ];

docs/configuration.md

@@ -2,13 +2,11 @@
 
 ## Publishing the Config
 
-Publish the configuration file to customise query parameter names:
-
 ```bash
 php artisan vendor:publish --tag=config --provider="Myerscode\Laravel\QueryStrategies\ServiceProvider"
 ```
 
-This creates `config/query-strategies.php`.
+This creates `config/query-strategies.php`. If you don't publish it, the package uses sensible defaults.
 
 ## Options
 
@@ -27,31 +25,39 @@ return [
 ];
 ```
 
-### Strict Mode
+## Strict Mode
 
-| Key | Default | Description |
-|---|---|---|
-| `strict` | `false` | When `true`, throws `InvalidFilterException` if a query parameter is not a recognised filter, system key, or operator override |
+When `strict` is `true`, any query parameter that isn't a recognised filter, system key, or operator override throws an `InvalidFilterException`. This is useful for APIs where you want to catch typos or prevent consumers from guessing at filter names.
+
+```php
+'strict' => true,
+```
+
+When `strict` is `false` (the default), unknown parameters are silently ignored.
+
+You can also enable strict mode per-request by passing it in the config array:
 
-When strict mode is enabled, any unknown query parameter will throw an exception with a message listing the allowed filters. This is useful for APIs where you want to prevent typos or unauthorised filter attempts from silently being ignored.
+```php
+$filter = new Filter($builder, $strategy, $request->query->all(), ['strict' => true]);
+```
 
-### Parameter Keys
+## Parameter Names
 
-Each key maps an internal concept to the query parameter name your API exposes:
+Each key maps an internal concept to the query parameter name your API exposes. Change these if your API conventions differ from the defaults:
 
-| Key | Default | Description |
+| Key | Default | What it controls |
 |---|---|---|
-| `order` | `order` | Parameter for specifying which column to order results by |
-| `sort` | `sort` | Parameter for specifying sort direction (`asc` or `desc`) |
-| `limit` | `limit` | Parameter for limiting the number of results returned |
-| `page` | `page` | Parameter for pagination page number |
-| `with` | `with` | Parameter for specifying relationships to eager load |
-| `fields` | `fields` | Parameter for selecting specific columns |
-| `append` | `append` | Reserved for future use |
+| `order` | `order` | Column to sort by |
+| `sort` | `sort` | Sort direction (`asc` / `desc`) |
+| `limit` | `limit` | Results per page |
+| `page` | `page` | Page number |
+| `with` | `with` | Relationships to eager load |
+| `fields` | `fields` | Columns to select |
+| `append` | `append` | Model accessors to append |
 
-## Example
+## Example: Custom Parameter Names
 
-If your API uses `sort_by` instead of `order` and `per_page` instead of `limit`:
+If your API uses different conventions:
 
 ```php
 return [
@@ -61,10 +67,16 @@ return [
         'limit'  => 'per_page',
         'page'   => 'page',
         'with'   => 'include',
-        'fields' => 'fields',
+        'fields' => 'select',
         'append' => 'append',
     ],
 ];
 ```
 
-Users would then query with `?sort_by=name&direction=desc&per_page=25&include=owner`.
+Consumers would then query with:
+
+```
+GET /products?sort_by=name&direction=desc&per_page=25&include=category&select=id,name
+```
+
+The strategy and filter logic stays the same — only the URL parameter names change.