Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion config/filterable.php
Original file line number Diff line number Diff line change
Expand Up @@ -212,7 +212,7 @@
| Invokable Filter Engine
|--------------------------------------------------------------------------
|
| The Invokable Engine provides a powerful way to dynamically map incomming reuqest parameters to corresponding methods in a filter class.
| The Invokable Engine provides a powerful way to dynamically map incomming request parameters to corresponding methods in a filter class.
|
*/
'invokable' => [
Expand Down
12 changes: 6 additions & 6 deletions docs/engines/invokable.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ sidebarDepth: 2

# Invokable Engine

The **Invokable Engine** provides a powerful way to dynamically map incomming reuqest parameters to corresponding methods in a filter class. This mechanism enables clean, scalable filtering logic and behavior injection without requiring large **switch** or **if-else** blocks.
The **Invokable Engine** provides a powerful way to dynamically map incomming request parameters to corresponding methods in a filter class. This mechanism enables clean, scalable filtering logic and behavior injection without requiring large **switch** or **if-else** blocks.

---

## Purpose

To automatically execute soecific methods in a filter class based on the incomming request keys, Each key in the request is matched with a method of the same name in the filter class and registered in **`$filters`** property, and the method is executed with the provided value.
To automatically execute specific methods in a filter class based on the incomming request keys, Each key in the request is matched with a method of the same name in the filter class and registered in **`$filters`** property, and the method is executed with the provided value.

---

Expand Down Expand Up @@ -96,7 +96,7 @@ You can access not only the raw value but also the parsed operator (e.g. =, like

## Mapping Request Keys

By default, the engine attempts to match the reuqest keys directly to metch names in the filter class. However, for mode flexibility and clarity, you can define a custom map that links request keys to specific method names.
By default, the engine attempts to match the request keys directly to match names in the filter class. However, for mode flexibility and clarity, you can define a custom map that links request keys to specific method names.

This allows you to:

Expand Down Expand Up @@ -182,15 +182,15 @@ This ensures that the filter system remains dynamic and flexible whether or not

- **Convention over configuration:** Method names match request keys.
- **Safe execution:** Only existing methods and registered filter keys in **`$filters`** are called.
- **Flexable extension:** Add or override logic in the filter class easily.
- **Flexible extension:** Add or override logic in the filter class easily.
- **Clean query builder:** Keeps container logic slim and readable.

---

### Lifecycle

1. Controller recevies request.
2. $request->only([...]) extracts relevent filters.
1. Controller receives request.
2. $request->only([...]) extracts relevant filters.
3. Filter class loops over keys.
4. For each key:
- if a method named **`$key`** exists and registered in **`$filters`** property, is is executed with the value.
Expand Down
40 changes: 20 additions & 20 deletions docs/engines/invokable/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,12 +94,12 @@ $posts = Post::filter(PostFilter::class)->paginate();

Every filter method receives a `Payload` instance, giving you full access to the parsed request data:

| Property | Type | Description |
| ----------- | -------- | ---------------------------------------------- |
| `field` | `string` | The column/filter name |
| `operator` | `string` | The parsed operator (e.g., `eq`, `like`, `gt`) |
| `value` | `mixed` | The sanitized filter value |
| `rawValue` | `mixed` | The original raw input before sanitization |
| Property | Type | Description |
| ---------- | -------- | ---------------------------------------------- |
| `field` | `string` | The column/filter name |
| `operator` | `string` | The parsed operator (e.g., `eq`, `like`, `gt`) |
| `value` | `mixed` | The sanitized filter value |
| `rawValue` | `mixed` | The original raw input before sanitization |

```php
protected function price(Payload $payload)
Expand Down Expand Up @@ -155,12 +155,12 @@ The Invokable Engine supports **PHP 8 Attributes** (annotations) on filter metho

Attributes are sorted and executed by **stage**:

| Order | Stage | Purpose | Example Attributes |
| ----- | ------------- | ---------------------------------- | ----------------------------------- |
| 1 | **CONTROL** | Decide whether to run the filter | `#[Authorize]`, `#[SkipIf]` |
| 2 | **TRANSFORM** | Modify the payload value | `#[Trim]`, `#[Sanitize]`, `#[Cast]`, `#[MapValue]`, `#[DefaultValue]`, `#[Explode]` |
| 3 | **VALIDATE** | Assert correctness of the value | `#[Required]`, `#[In]`, `#[Between]`, `#[Regex]` |
| 4 | **BEHAVIOR** | Affect query behavior | `#[Scope]` |
| Order | Stage | Purpose | Example Attributes |
| ----- | ------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
| 1 | **CONTROL** | Decide whether to run the filter | `#[Authorize]`, `#[SkipIf]` |
| 2 | **TRANSFORM** | Modify the payload value | `#[Trim]`, `#[Sanitize]`, `#[Cast]`, `#[MapValue]`, `#[DefaultValue]`, `#[Explode]` |
| 3 | **VALIDATE** | Assert correctness of the value | `#[Required]`, `#[In]`, `#[Between]`, `#[Regex]` |
| 4 | **BEHAVIOR** | Affect query behavior | `#[Scope]` |

### Example with Attributes

Expand Down Expand Up @@ -221,14 +221,14 @@ The default operator can be configured per engine:

## Key Features

| Feature | Description |
| ------------------------------ | -------------------------------------------------------------- |
| **Convention over Configuration** | Method names match request keys automatically |
| **Safe Execution** | Only registered filter keys in `$filters` are processed |
| **Attribute Pipeline** | PHP 8 attributes for validation, transformation, and control |
| **Custom Method Mapping** | `$mentors` property for flexible key-to-method mapping |
| **Rich Payload Object** | Full access to field, operator, value, and raw value |
| **Extensible** | Add or override filter methods easily |
| Feature | Description |
| --------------------------------- | ------------------------------------------------------------ |
| **Convention over Configuration** | Method names match request keys automatically |
| **Safe Execution** | Only registered filter keys in `$filters` are processed |
| **Attribute Pipeline** | PHP 8 attributes for validation, transformation, and control |
| **Custom Method Mapping** | `$mentors` property for Flexible key-to-method mapping |
| **Rich Payload Object** | Full access to field, operator, value, and raw value |
| **Extensible** | Add or override filter methods easily |

---

Expand Down
2 changes: 1 addition & 1 deletion docs/sanitization.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Request Sanitization

Sanitization allows you to clean or transform incomming reuqest data **before** validation or filtering is applied.
Sanitization allows you to clean or transform incomming request data **before** validation or filtering is applied.
This feature ensures your filters always work with clean and normalized data.

## Overview
Expand Down
2 changes: 1 addition & 1 deletion tests/Unit/Filterable/FilterRulesValidationTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
class FilterRulesValidationTest extends TestCase
{
/**
* It validate incomming reuqest before filtering.
* It validate incomming request before filtering.
* @test
*/
public function it_validate_incomming_reuqest_before_filtering()
Expand Down
Loading