Merge branch 'develop' of github.com:kettasoft/filterable into develop

Author: Abdalrhman Emad Saad

docs/.vuepress/config.js

@@ -3,118 +3,128 @@ import { defineUserConfig } from "vuepress/cli";
 import { viteBundler } from "@vuepress/bundler-vite";
 
 export default defineUserConfig({
-    lang: "en-US",
+  lang: "en-US",
 
-    title: "Filterable",
-    description: "Kettasoft Filterable - Powerful Eloquent Filtering Package",
+  title: "Filterable",
+  description: "Kettasoft Filterable - Powerful Eloquent Filtering Package",
 
-    plugins: [
-        {
-            name: "@vuepress/plugin-search",
-        },
-    ],
+  plugins: [
+    {
+      name: "@vuepress/plugin-search",
+    },
+  ],
 
-    theme: defaultTheme({
-        repo: "https://github.com/kettasoft/filterable",
-        // logo: "/docs/logo.png",
+  theme: defaultTheme({
+    repo: "https://github.com/kettasoft/filterable",
+    // logo: "/docs/logo.png",
 
-        colorModeSwitch: true,
-        sidebarDepth: 3,
-        logoAlt: null,
-        logo: null,
-        selectLanguageText: "ar",
-        selectLanguageName: "ar",
-        lastUpdated: true,
-        contributors: true,
-        // contributorsText: "dasdasd",
+    colorModeSwitch: true,
+    sidebarDepth: 3,
+    logoAlt: null,
+    logo: null,
+    selectLanguageText: "ar",
+    selectLanguageName: "ar",
+    lastUpdated: true,
+    contributors: true,
+    // contributorsText: "dasdasd",
 
-        navbar: ["/", "/installation"],
-        sidebar: [
-            {
-                text: "Home",
-                link: "/",
-            },
-            {
-                text: "Introduction",
-                link: "/introduction",
-            },
-            {
-                text: "Installation",
-                link: "/installation",
-            },
-            {
-                text: "How It Works",
-                link: "how-it-works",
-            },
-            {
-                text: "Engines",
-                collapsible: true,
-                children: [
-                    {
-                        text: "Invokable",
-                        link: "engines/invokable",
-                    },
-                    {
-                        text: "Tree",
-                        link: "engines/tree",
-                    },
-                    {
-                        text: "Ruleset",
-                        link: "engines/rule-set",
-                    },
-                    {
-                        text: "Expression",
-                        link: "engines/expression",
-                    },
-                ],
-            },
-            {
-                text: "Features",
-                collapsible: true,
-                children: [
-                    {
-                        text: "Header-Driven Filter Mode",
-                        link: "features/header-driven-filter-mode",
-                    },
+    navbar: ["/", "/installation"],
+    sidebar: [
+      {
+        text: "Home",
+        link: "/",
+      },
+      {
+        text: "Introduction",
+        link: "/introduction",
+      },
+      {
+        text: "Installation",
+        link: "/installation",
+      },
+      {
+        text: "How It Works",
+        link: "how-it-works",
+      },
+      {
+        text: "Engines",
+        collapsible: true,
+        children: [
+          {
+            text: "Invokable",
+            link: "engines/invokable",
+          },
+          {
+            text: "Tree",
+            link: "engines/tree",
+          },
+          {
+            text: "Ruleset",
+            link: "engines/rule-set",
+          },
+          {
+            text: "Expression",
+            link: "engines/expression",
+          },
+        ],
+      },
+      {
+        text: "Features",
+        collapsible: true,
+        children: [
+          {
+            text: "Header-Driven Filter Mode",
+            link: "features/header-driven-filter-mode",
+          },
 
-                    {
-                        text: "Auto Register Filterable Macro",
-                        link: "features/auto-register-filterable-macro",
-                    },
-                    {
-                        text: "Conditional Logic",
-                        link: "features/conditional-logic-with-when",
-                    },
-                    {
-                        text: "Filter Aliases",
-                        link: "features/aliasing",
-                    },
-                    {
-                        text: "Through callbacks",
-                        link: "features/through",
-                    },
-                    {
-                        text: "Auto Binding",
-                        link: "features/auto-binding",
-                    },
-                ],
-            },
-            {
-                text: "Authorization",
-                link: "authorization",
-            },
-            {
-                text: "Validation",
-                link: "validation",
-            },
-            {
-                text: "Sanitization",
-                link: "sanitization",
-            },
+          {
+            text: "Auto Register Filterable Macro",
+            link: "features/auto-register-filterable-macro",
+          },
+          {
+            text: "Conditional Logic",
+            link: "features/conditional-logic-with-when",
+          },
+          {
+            text: "Filter Aliases",
+            link: "features/aliasing",
+          },
+          {
+            text: "Through callbacks",
+            link: "features/through",
+          },
+          {
+            text: "Auto Binding",
+            link: "features/auto-binding",
+          },
         ],
-    }),
+      },
+      {
+        text: "Execution",
+        collapsible: true,
+        children: [
+          {
+            text: "Invoker",
+            link: "execution/invoker",
+          },
+        ],
+      },
+      {
+        text: "Authorization",
+        link: "authorization",
+      },
+      {
+        text: "Validation",
+        link: "validation",
+      },
+      {
+        text: "Sanitization",
+        link: "sanitization",
+      },
+    ],
+  }),
 
-    base: "/filterable",
+  base: "/filterable",
 
-    bundler: viteBundler(),
+  bundler: viteBundler(),
 });

docs/execution/invoker.md

@@ -0,0 +1,151 @@
+# Invoker – Fluent Control Over Query Execution
+
+## Overview
+
+The `Invoker` class in the Filterable package is a smart execution wrapper that allows you to control the lifecycle of your query after applying filters. It is returned by the `Filterable::apply()` method and supports actions **before**, **after**, or **on error** during query execution.
+
+---
+
+## Purpose
+
+`Invoker` wraps the underlying query builder and enables:
+
+- Executing callbacks **before** the query runs.
+- Handling results **after** the query runs.
+- Capturing **errors** and providing fallback logic.
+- Dispatching the query as a Laravel job.
+- Fluent chaining with `when` and `unless` conditions.
+
+---
+
+## Usage Example
+
+```php
+$result = Filterable::apply(User::query())
+    ->beforeExecute(function ($builder) {
+      $builder->where('is_active', true);
+    })
+    ->afterExecute(function (Collection $result) {
+        return $result->filter(fn ($user) => $user->isActive());
+    })
+    ->onError(function ($invoker, $exception) {
+        report($exception);
+        return collect(); // fallback
+    })
+    ->get(); // <-- This will trigger the execution
+```
+
+## Public Methods
+
+`Invoker::init(QueryBuilderInterface $builder)`
+
+Create a new Invoker instance manually.
+
+---
+
+### beforeExecute
+
+`->beforeExecute(Closure $callback): static`
+Register a callback to be called before the query is executed.
+
+**Parameters**:
+
+- `Closure $callback`: Receives the internal query builder.
+
+---
+
+### afterExecute
+
+`->afterExecute(Closure $callback): static`
+Register a callback to process or modify the result after execution.
+
+**Parameters**:
+
+- `Closure $callback`: Receives the result returned by the terminal method.
+
+---
+
+### onError
+
+`->onError(Closure $callback): static`
+Register a callback to handle any exceptions that occur during query execution.
+
+**Parameters**:
+`Closure $callback`: Receives the Invoker and the thrown exception.
+
+---
+
+### when
+
+`->when(bool $condition, callable $callback): static`
+Conditionally apply logic to the Invoker chain.
+
+---
+
+### unless
+
+`->unless(bool $condition, callable $callback): static`
+The inverse of when.
+
+---
+
+### asJob
+
+`->asJob(string $jobClass, array $data = [], ?string $queue = null): mixed`
+Dispatch the query execution as a Laravel job.
+
+**Parameters**:
+
+- `string $jobClass`: The name of the job class to dispatch.
+- `array $data`: Optional additional data.
+- `string|null $queue`: Optional queue name.
+
+---
+
+### When Invoker is Skipped
+
+In some advanced use cases, the `Invoker` wrapper will be **skipped**, and the `apply()` method will return the query builder directly.
+
+This happens in two cases:
+
+1. If the target class implements the `ShouldReturnQueryBuilder` interface:
+
+```php
+<?php
+
+namespace App\Http\Filters;
+
+use Kettasoft\Filterable\Filterable;
+use Kettasoft\Filterable\Foundation\Contracts\ShouldReturnQueryBuilder;
+
+class PostFilter extends Filterable implements ShouldReturnQueryBuilder
+{
+//
+}
+```
+
+2. If you explicitly call the `shouldReturnQueryBuilder()` method before calling a terminal method.
+
+```php
+$filter = Filterable::create()
+    ->shouldReturnQueryBuilder()
+    ->apply(Post::query()) // <- Returns Query builder directly
+```
+
+This is useful when you want to bypass Invoker's control layer and interact with the builder as usual.
+
+---
+
+Notes:
+The job class must accept an `invoker` key in its constructor data.
+
+## Summary
+
+`Invoker` is your **last-mile control layer** before the query is executed. It's ideal for:
+
+- Logging
+- Result transformation
+- Fallbacks
+- Background execution
+
+This gives Filterable a clean and powerful **declarative style**.