docs(README): update package description and features

alexnogueirasilva · alexnogueirasilva · commit 3ca5c8620b6c · 2025-03-15T14:06:18.000-03:00
diff --git a/README.md b/README.md
@@ -1,26 +1,24 @@
-# Filterable Package for Laravel
+# Filterable Package
 
-**Filterable Package** is a Laravel package designed to simplify filtering Eloquent models in your application. It provides an easy-to-use interface to apply various types of filters to your Eloquent queries, such as exact matches, partial matches (LIKE), date ranges, JSON-based filters, and more, directly from incoming requests. This package is especially useful for building APIs where dynamic filtering is often required.
+A Laravel package for filterable traits and classes. This package provides powerful, dynamic query filtering capabilities directly from incoming requests, especially useful when developing flexible and dynamic APIs.
 
 ## Features
-- **Easy Integration:** Apply the `Filterable` trait to your Eloquent models to start using it.
-- **Multiple Filters:** Supports a variety of filters such as exact matches, LIKE searches, greater than, less than, IN clauses, JSON-based filters, and date ranges.
-- **Custom Filter Mapping:** Easily map request parameters to different column names in the database.
-- **Flexible Sorting:** Allows for dynamic sorting of results based on request parameters.
 
-## Installation
+- **Easy Integration:** Apply the `Filterable` trait to your Eloquent models.
+- **Flexible Filters:** Exact, like, in, between, greater than (gte, gt), less than (lte, lt), JSON, and relationship filters.
+- **Dynamic Sorting:** Customize sorting behavior directly from requests.
+- **Relationship Filters:** Use advanced conditional logic like `whereAny`, `whereAll`, and `whereNone` for relational queries.
+- **JSON Support:** Directly filter JSON columns with dot-notation.
 
-To install the package, use Composer:
+## Installation
 
 ```bash
 composer require devaction-labs/filterable-package
 ```
 
 ## Usage
 
-### Step 1: Apply the `Filterable` Trait to Your Model
-
-Apply the `Filterable` trait to any Eloquent model you want to filter.
+### Step 1: Add the `Filterable` Trait
 
 ```php
 namespace App\Models;
@@ -32,189 +30,117 @@ class Expense extends Model
 {
     use Filterable;
 
-    // Define any custom filter map or allowed sorts if necessary
     protected array $filterMap = [
-        'search' => 'description', // Example: map 'search' request parameter to 'description' column
+        'search' => 'description',
+        'date'   => 'expense_date',
     ];
 
-    protected array $allowedSorts = ['expense_date', 'amount']; // Example: allow sorting by these columns
+    protected array $allowedSorts = ['expense_date', 'amount'];
 }
 ```
 
-### Step 2: Apply Filters in Your Controller
-
-Apply filters in your controller methods using the `filtrable` scope provided by the `Filterable` trait.
+### Step 2: Applying Filters in Controllers
 
 ```php
-namespace App\Http\Controllers\Api\Finance;
+namespace App\Http\Controllers\Api;
 
 use App\Http\Controllers\Controller;
-use App\Http\Resources\ExpenseCollection;
-use App\Models\Expense;
 use DevactionLabs\FilterablePackage\Filter;
+use App\Models\Expense;
 
 class ExpenseController extends Controller
 {
-    public function index(): ExpenseCollection
+    public function index()
     {
         $expenses = Expense::query()
-            ->with(['category', 'period'])
             ->filtrable([
                 Filter::like('description', 'search'),
                 Filter::exact('expense_date', 'date'),
+                Filter::between('expense_date', 'date_range'),
                 Filter::json('attributes', 'user.name', 'LIKE', 'user_name'),
                 Filter::json('attributes', 'user.age', '>', 'user_age'),
-            ])
-            ->customPaginate();
-
-        return new ExpenseCollection($expenses);
+                Filter::relationship('user', 'name')->setValue('John')->with(),
+                Filter::relationship('user', 'name')->whereAny([
+                    ['name', '=', 'John'],
+                    ['email', '=', 'john@example.com'],
+                ])->with(),
+            ->customPaginate(false, ['per_page' => 10, 'sort' => '-created_at']);
+
+        return response()->json($expenses);
     }
 }
 ```
 
 ## Available Filters
 
-### `Filter::exact($attribute, $filterBy = null)`
-- **Description:** Filters records where the column value matches exactly with the provided value.
-- **Example:** `Filter::exact('status', 'status')` filters records where the `status` column matches the value of the `status` parameter in the request.
-
-### `Filter::like($attribute, $filterBy = null)`
-- **Description:** Filters records where the column value is similar to the provided value (uses SQL `LIKE`).
-- **Example:** `Filter::like('name', 'search')` filters records where the `name` column contains the value of the `search` parameter in the request.
-
-### `Filter::in($attribute, $filterBy = null)`
-- **Description:** Filters records where the column value is within a specified list of values.
-- **Example:** `Filter::in('category_id', 'categories')` filters records where the `category_id` column matches any value provided in the `categories` parameter in the request.
-
-### `Filter::gte($attribute, $filterBy = null)`
-- **Description:** Filters records where the column value is greater than or equal to the provided value.
-- **Example:** `Filter::gte('amount', 'min_amount')` filters records where the `amount` column is greater than or equal to the value of the `min_amount` parameter in the request.
-
-### `Filter::lte($attribute, $filterBy = null)`
-- **Description:** Filters records where the column value is less than or equal to the provided value.
-- **Example:** `Filter::lte('amount', 'max_amount')` filters records where the `amount` column is less than or equal to the value of the `max_amount` parameter in the request.
-
-### `Filter::json($attribute, $path, $operator = '=', $filterBy = null)`
-- **Description:** Filters records based on JSON attributes. Allows querying nested JSON data using a dot-notated path.
-- **Parameters:**
-    - `$attribute`: The column that contains the JSON data.
-    - `$path`: The dot-notated path to the JSON attribute (e.g., `'user.name'`).
-    - `$operator`: The comparison operator (e.g., `'='`, `'LIKE'`, `'>'`, etc.).
-    - `$filterBy`: The request parameter name to map to this filter.
-- **Example:**
-    - `Filter::json('attributes', 'user.name', 'LIKE', 'user_name')` filters records where the `user.name` attribute in the `attributes` JSON column matches the `user_name` request parameter using a `LIKE` comparison.
-    - `Filter::json('attributes', 'user.age', '>', 'user_age')` filters records where the `user.age` attribute in the `attributes` JSON column is greater than the `user_age` request parameter.
-### `Filter::between($attribute, $filterBy = null)`
-
-- **Description:** Filters records where the column value is within a specified range (inclusive).
-- **Parameters:**
-    - `$attribute`: The database column to apply the filter on.
-    - `$filterBy`: (Optional) The request parameter name to map to this filter. Defaults to the attribute name.
-- **Example Usage:**
-  - `Filter::between('expense_date', 'date_range')` filters records where the `expense_date` column falls between two values provided in the `date_range` parameter in the request.
-
-**API Request Example:**
-`` Get /api/expenses?filter[date_range]=2023-01-01,2023-12-31
-```
-
-## Custom Filter Mapping
-You can map request parameters to different column names in your database. For example:
+### Direct Filters
+- **Exact Match:** `Filter::exact('status', 'status')`
+- **LIKE Match:** `Filter::like('description', 'search')`
+- **IN Clause:** `Filter::in('category_id', 'categories')`
+- **Greater Than or Equal:** `Filter::gte('amount', 'min_amount')`
+- **Less Than or Equal:** `Filter::lte('amount', 'max_amount')`
+- **Between:** `Filter::between('created_at', 'date_range')`
+
+### JSON Filters
+- **Exact Match:** `Filter::json('data', 'user.name', '=', 'user_name')`
+- **LIKE Match:** `Filter::json('data', 'user.name', 'LIKE', 'user_name')`
+
+### Relationship Filters
+- **Simple Relationship:**
+  ```php
+  Filter::relationship('user', 'name')->setValue('John')->with()
+  ```
+
+- **Conditional Logic (`whereAny`, `whereAll`, `whereNone`):**
+  ```php
+  Filter::relationship('user', 'name')
+      ->whereAny([
+          ['name', '=', 'John'],
+          ['email', '=', 'john@example.com'],
+      ])
+      ->setValue('John')
+      ->with();
+  ```
+
+## Customizing Pagination and Sorting
+
+Use the provided methods to paginate and sort easily:
 
 ```php
-protected array $filterMap = [
-    'search' => 'description',
-    'date' => 'expense_date',
-];
-```
-
-Now, if the request contains `filter[search]=Pizza`, the query will filter the `description` column for the value `Pizza`.
-
-## Benefits and Differentiators
-
-- **Enhanced Code Readability:** Filters are applied in a clean, readable manner without cluttering your controllers or models with complex query logic.
-- **Dynamic Filtering:** Easily handle multiple filters from a single request without manually parsing input.
-- **Reusability:** Filters can be reused across different queries and models, making your code DRY (Don't Repeat Yourself).
-- **Flexible Sorting:** Allows sorting results dynamically based on request parameters, ensuring that your API remains flexible to client needs.
-- **JSON Support:** Easily filter nested JSON attributes, enhancing the flexibility of your queries when dealing with JSON data types.
-
-## Example Usage in API Controller
-
-```php
-      namespace App\Http\Controllers\Api\Finance;
-      
-      use App\Http\Controllers\Controller;
-      use App\Http\Resources\ExpenseCollection;
-      use App\Models\Expense;
-      use DevactionLabs\FilterablePackage\Filter;
-      
-      class ExpenseController extends Controller
-      {
-          public function index(): ExpenseCollection
-          {
-              $expenses = Expense::query()
-                  ->with(['category', 'period'])
-                  ->filtrable([
-                      Filter::like('description', 'search'),
-                      Filter::exact('expense_date', 'date'),
-                      Filter::between('expense_date', 'date_range'),
-                      Filter::json('attributes', 'user.name', 'LIKE', 'user_name'),
-                      Filter::json('attributes', 'user.age', '>', 'user_age'),
-                  ])
-                  ->customPaginate();
-      
-              return new ExpenseCollection($expenses);
-          }
-      }
+$results = Expense::query()
+    ->filtrable([...])
+    ->customPaginate(false, ['per_page' => 10, 'sort' => '-created_at']);
 ```
 
-## Pagination and Sorting
+- `-` (minus) prefix indicates descending sorting (e.g., `-amount`).
 
-### Custom Pagination
-
-Use the `customPaginate` scope to apply pagination with customizable parameters.
+### Defining Default Sorting and Allowed Sorts in Model:
 
 ```php
-$expenses = Expense::query()
-    ->filtrable([...])
-    ->customPaginate(); // Defaults to 15 items per page
-
-// With custom parameters
-$expenses = Expense::query()
-    ->filtrable([...])
-    ->customPaginate(false, ['per_page' => 10, 'sort' => '-amount']);
+protected string $defaultSort = 'amount';
+protected array $allowedSorts = ['amount', 'expense_date'];
 ```
 
-### Allowed Sorts and Default Sort
+## Custom Filter Mapping
 
-Define allowed sorts and a default sort order in your model.
+Easily map request parameters to database columns:
 
 ```php
-protected array $allowedSorts = ['expense_date', 'amount'];
-protected string $defaultSort = 'expense_date';
-
-// In your controller
-$expenses = Expense::query()
-    ->filtrable([...])
-    ->allowedSorts(['expense_date', 'amount'])
-    ->customPaginate();
+protected array $filterMap = [
+    'display_name' => 'name',
+    'date' => 'expense_date',
+];
 ```
 
-## Handling JSON Filters with Different Databases
+Now, using the parameter `filter[display_name]=John` will filter on the `name` column.
 
-The package supports JSON-based filters across different database systems by handling the JSON extraction appropriately.
+## Supported Databases for JSON Filters
+- MySQL
+- PostgreSQL
+- SQLite
 
-### Supported Databases:
-- **MySQL:** Uses the `->>` operator to extract JSON values.
-- **SQLite:** Uses the `json_extract` function.
-- **PostgreSQL:** Uses the `->>` operator to extract JSON values.
-
-Ensure that your database driver is correctly set to utilize the appropriate JSON extraction method.
-
-## Conclusion
-
-The **Filterable Package** simplifies the process of filtering Eloquent models in Laravel. By leveraging the power of this package, you can create highly flexible and dynamic filtering solutions in your application, improving code quality and maintainability. With support for JSON-based filters, you can efficiently query nested JSON attributes, making your APIs more robust and versatile.
+The package automatically detects the database driver from your configuration.
 
 ## License
 
-This package is open-sourced software licensed under the [MIT license](LICENSE).
-```
+This package is open-sourced under the MIT license.
diff --git a/composer.json b/composer.json
@@ -9,7 +9,7 @@
             "email": "alex@devaction.com.br"
         }
     ],
-    "version": "v1.0.19",
+    "version": "v1.0.20",
     "require": {
         "php": "^8.2|^8.3|^8.4",
         "illuminate/cache": "^12.2",
@@ -32,13 +32,6 @@
             "DevactionLabs\\FilterablePackage\\": "src/"
         }
     },
-    "extra": {
-        "laravel": {
-            "providers": [
-                "DevactionLabs\\FilterablePackage\\FilterableServiceProvider"
-            ]
-        }
-    },
     "autoload-dev": {
         "psr-4": {
             "Tests\\": "tests/"
