Merge pull request #37 from kettasoft/feat/exception-handling

Improved exception handling engine with new configuration options

Author: kettasoft

config/filterable.php

@@ -861,4 +861,44 @@
             'log_channel' => env('FILTERABLE_CACHE_LOG_CHANNEL', 'daily'),
         ],
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Exception Handling
+    |--------------------------------------------------------------------------
+    |
+    | Define how Filterable handles exceptions thrown during filtering.
+    | You can choose from built-in handlers or implement your own.
+    |
+    | Supported options:
+    | - handler: The class responsible for handling exceptions.
+    | - strict: When true, exceptions will always be thrown instead of skipped.
+    | - log_exceptions: Whether to log unhandled or skipped exceptions.
+    | - report: A closure or class name to customize how exceptions are reported.
+    |
+    */
+    'exceptions' => [
+        /*
+        |--------------------------------------------------------------------------
+        | Exception Handler
+        |--------------------------------------------------------------------------
+        |
+        | The class responsible for handling exceptions during filtering.
+        | You can implement your own handler by adhering to the
+        | Filterable\Contracts\ExceptionHandler interface.
+        |
+        */
+        'handler' => Kettasoft\Filterable\Exceptions\Handlers\DefaultHandler::class,
+
+        /*
+        |--------------------------------------------------------------------------
+        | Strict Mode
+        |--------------------------------------------------------------------------
+        |
+        | When enabled, exceptions will always be thrown instead of skipped.
+        | This overrides per-engine strict settings.
+        |
+        */
+        'strict' => env('FILTERABLE_EXCEPTION_STRICT', false),
+    ]
 ];

docs/.vuepress/config.js

@@ -233,6 +233,10 @@ export default defineUserConfig({
                     },
                 ],
             },
+            {
+                text: "Exceptions",
+                link: "exceptions",
+            },
             {
                 text: "Event System",
                 link: "events",

docs/exceptions.md

@@ -0,0 +1,277 @@
+---
+title: Exception Handling
+sidebarDepth: 2
+---
+
+# Exception Handling
+
+Filterable provides a structured and predictable exception-handling system that
+allows engines to decide whether filtering should stop, skip the current filter,
+or continue normally.  
+This mechanism was redesigned to offer clearer behavior, improved safety, and
+better extensibility.
+
+The system is built around three main components:
+
+-   **Exception types** (how engines signal different situations)
+-   **Handlers** (how exceptions are processed)
+-   **Configuration** (how strict or lenient the system should behave)
+
+---
+
+## Exception Flow Overview
+
+During filtering, an engine may encounter invalid, empty, or malformed input.
+Instead of halting the entire process, the engine throws a specific exception
+to indicate what happened.
+
+The handler then decides—based on the exception type and strict configuration—
+whether the exception should be:
+
+-   **thrown** (stop filtering),
+-   **or skipped** (ignore this filter and continue with the next one).
+
+If a handler returns `false`, the current filter is skipped.
+
+---
+
+## Exception Types
+
+Filterable defines two fundamental exception categories.  
+Each one represents a different kind of failure and implies different behavior.
+
+### **SkipExecution**
+
+`SkipExecution` is used when the engine cannot apply the filter, but the situation
+is not considered critical.
+
+Typical scenarios include:
+
+-   empty values when the engine does not accept empty input,
+-   unsupported operators,
+-   incomplete data structures.
+
+**Behavior:**
+
+-   If strict mode is enabled → **the exception is thrown**
+-   If strict mode is disabled → **the filter is skipped**
+
+This allows engines to ignore irrelevant or incomplete input without failing the
+whole filtering pipeline.
+
+---
+
+### **StrictnessException**
+
+`StrictnessException` represents invalid or unsafe input.  
+This type signals that the engine cannot proceed safely with the given data.
+
+Examples include:
+
+-   corrupted or malformed values,
+-   invalid structure or types,
+-   contradictory or logically impossible conditions.
+
+**Behavior:**
+
+-   strict mode enabled → **always thrown**
+-   strict mode disabled → handler may return `false` to skip, but the exception
+    indicates a more serious issue
+
+This class of exceptions enforces higher input correctness.
+
+---
+
+## Exception Handlers
+
+Handlers determine what happens when an exception is thrown.  
+They receive both the exception and the engine instance.
+
+Returning `false` means:  
+**"Skip this filter and continue."**
+
+Throwing the exception stops filtering immediately.
+
+### **ExceptionHandlerInterface**
+
+Every handler must implement:
+
+```php
+interface ExceptionHandlerInterface
+{
+    public function handle(\Throwable $exception, Engine $engine): bool;
+}
+```
+
+This gives full control to define how exceptions are processed.
+
+---
+
+## Helper Base Class: FilterableExceptionHandler
+
+`FilterableExceptionHandler` provides shared logic that custom handlers
+can use to simplify implementation.
+
+Key helper methods:
+
+-   `isStrictThrowing()`
+    Checks whether global strict mode is enabled via config.
+
+-   `hasSkipping($exception)`
+    Detects `SkipExecution`.
+
+-   `isStrictness($exception)`
+    Detects strictness-related exceptions.
+
+Custom handlers may extend this abstract class to avoid duplicating logic.
+
+```php
+abstract class FilterableExceptionHandler implements ExceptionHandlerInterface
+{
+    abstract public function handle(\Throwable $exception, Engine $engine): bool;
+
+    protected function isStrictThrowing(): bool
+    {
+        return config('filterable.exception.strict', false);
+    }
+
+    protected function hasSkipping($exception): bool
+    {
+        return $exception instanceof SkipExecution;
+    }
+
+    protected function isStrictness($exception): bool
+    {
+        return $exception instanceof StrictnessException;
+    }
+}
+```
+
+---
+
+## DefaultHandler Behavior
+
+The default handler implements the standard strategy for both exception types:
+
+```php
+class DefaultHandler extends FilterableExceptionHandler
+{
+    public function handle(\Throwable|SkipExecution $exception, Engine $engine): bool
+    {
+        // SkipExecution: skip if not strict
+        if ($this->hasSkipping($exception)) {
+            if ($engine->isStrict() || $this->isStrictThrowing()) {
+                throw $exception;
+            }
+            return false; // skip current filter
+        }
+
+        // StrictnessException: throw when strict
+        if ($this->isStrictness($exception) || $this->isStrictThrowing()) {
+            throw $exception;
+        }
+
+        return false; // default: skip non-critical cases
+    }
+}
+```
+
+### Summary of Behavior
+
+| Exception Type      | Strict Mode | Behavior        |
+| ------------------- | ----------- | --------------- |
+| SkipExecution       | Enabled     | Throw exception |
+| SkipExecution       | Disabled    | Skip filter     |
+| StrictnessException | Enabled     | Throw exception |
+| StrictnessException | Disabled    | Skip filter     |
+
+---
+
+## Configuration
+
+Exception handling is defined in the `filterable.exceptions` config section:
+
+```php
+'exceptions' => [
+
+    'handler' => Kettasoft\Filterable\Exceptions\Handlers\DefaultHandler::class,
+
+    'strict' => env('FILTERABLE_EXCEPTION_STRICT', false),
+]
+```
+
+### `handler`
+
+Defines the class responsible for handling exceptions.
+
+Must implement:
+`ExceptionHandlerInterface`.
+
+### `strict`
+
+When enabled:
+
+-   exceptions are always thrown,
+-   skipping behavior is disabled,
+-   engine-level strict settings are overridden.
+
+---
+
+## How Filter Skipping Works
+
+If the handler returns `false`, the current filter is skipped and the next filter
+is processed.
+
+Example:
+
+Filters: **status**, **name**, **is_active**
+Suppose:
+
+-   `status` receives empty data,
+-   engine does not accept empty values → throws `SkipExecution`.
+
+If strict mode is disabled:
+
+-   `status` is skipped,
+-   filtering continues with `name` then `is_active`.
+
+This allows the filtering pipeline to continue gracefully without failing
+because of optional or incomplete input.
+
+---
+
+## Creating Custom Handlers
+
+To implement your own rules:
+
+```php
+class MyCustomHandler extends FilterableExceptionHandler
+{
+    public function handle(\Throwable $exception, Engine $engine): bool
+    {
+        // custom logic
+    }
+}
+```
+
+Register it in the config:
+
+```php
+'exceptions' => [
+    'handler' => App\Filters\Handlers\MyCustomHandler::class,
+]
+```
+
+---
+
+## Conclusion
+
+This unified exception-handling pipeline provides:
+
+-   clear distinction between skip-level and failure-level issues,
+-   configurable strictness,
+-   customizable handlers,
+-   consistent engine behavior,
+-   predictable filter skipping.
+
+It enables robust and flexible filtering without breaking existing APIs.

phpunit.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.3/phpunit.xsd" colors="true">
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.3/phpunit.xsd" colors="true" stopOnFailure="true">
   <testsuites>
     <testsuite name="Unit">
       <directory suffix="Test.php">./tests</directory>

src/Engines/Contracts/Skippable.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Kettasoft\Filterable\Engines\Contracts;
+
+use Kettasoft\Filterable\Engines\Exceptions\SkipExecution;
+
+interface Skippable
+{
+    /**
+     * Skip the current execution with a message and optional clause.
+     * @param string $message
+     * @param mixed $clause
+     * @throws SkipExecution
+     * @return never
+     */
+    public function skip(string $message, mixed $clause = null): never;
+}

src/Engines/Exceptions/InvalidDataFormatException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Kettasoft\Filterable\Engines\Exceptions;
+
+use Kettasoft\Filterable\Exceptions\StrictnessException;
+
+class InvalidDataFormatException extends StrictnessException
+{
+  public function __construct()
+  {
+    parent::__construct("The provided data is either incommpatible or incorrectly formatted.");
+  }
+}

…/Exceptions/InvalidOperatorException.php …/Exceptions/InvalidOperatorException.phpsrc/Exceptions/InvalidOperatorException.php renamed to src/Engines/Exceptions/InvalidOperatorException.php src/Exceptions/InvalidOperatorException.php renamed to src/Engines/Exceptions/InvalidOperatorException.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Kettasoft\Filterable\Exceptions;
+namespace Kettasoft\Filterable\Engines\Exceptions;
 
-class InvalidOperatorException extends \InvalidArgumentException
+class InvalidOperatorException extends SkipExecution
 {
   /**
    * InvalidOperatorException constructor.

src/Engines/Exceptions/NotAllowedEmptyValueException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Kettasoft\Filterable\Engines\Exceptions;
+
+class NotAllowedEmptyValueException extends SkipExecution
+{
+    /**
+     * NotAllowedEmptyValueException constructor.
+     * @param mixed $message
+     */
+    public function __construct($message = "")
+    {
+        parent::__construct($message);
+    }
+}