refactor: add specific interface contexts per engine for better decoupling

- Created dedicated interface contexts for each filter engine defining only the required contract.
- Update each engine to depend on its specific interface context instead of a general Filterable class.
- Implemented these interfaces in Filterable to provide required methods per engine.
- This enhances modularity, clarity, and testability of filter engines

Author: Abdalrhman Emad Saad

src/Contracts/FilterableContext.php

@@ -2,30 +2,11 @@
 
 namespace Kettasoft\Filterable\Contracts;
 
-interface FilterableContext
-{
-  /**
-   * Get current data.
-   * @return array
-   */
-  public function getData(): mixed;
-
-  /**
-   * Fetch all relevant filters from the filter API class.
-   *
-   * @return array
-   */
-  public function getFilterAttributes(): array;
-
-  /**
-   * Get mentors.
-   * @return array
-   */
-  public function getMentors(): array;
-
-  /**
-   * Check if current filterable class has ignored empty values.
-   * @return bool
-   */
-  public function hasIgnoredEmptyValues(): bool;
-}
+use Kettasoft\Filterable\Engines\Contracts\{
+  TreeFilterableContext,
+  RulesetFilterableContect,
+  ExpressionEngineContext,
+  InvokableEngineContext
+};
+
+interface FilterableContext extends TreeFilterableContext, RulesetFilterableContect, ExpressionEngineContext, InvokableEngineContext {}

src/Engines/Contracts/ExpressionEngineContext.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Kettasoft\Filterable\Engines\Contracts;
+
+use Kettasoft\Filterable\Sanitization\Sanitizer;
+
+interface ExpressionEngineContext
+{
+  /**
+   * Get current data.
+   * @return array
+   */
+  public function getData(): mixed;
+
+  /**
+   * Get sanitizer instance.
+   * @return Sanitizer
+   */
+  public function getSanitizerInstance(): Sanitizer;
+
+  /**
+   * Get allowed fields to apply filtering.
+   * @return array
+   */
+  public function getAllowedFields(): array;
+
+  /**
+   * Check if a given relation is allowed for filtering.
+   * @param string $relation
+   * @return bool
+   */
+  public function isRelationAllowed(string $relation, $field): bool;
+
+  /**
+   * Get columns wrapper.
+   * @return array
+   */
+  public function getFieldsMap(): array;
+
+  /**
+   * List of supported SQL operators you want to allow when parsing the expressions.
+   * @return array
+   */
+  public function getAllowedOperators(): array;
+}

src/Engines/Contracts/InvokableEngineContext.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Kettasoft\Filterable\Engines\Contracts;
+
+use Illuminate\Http\Request;
+use Kettasoft\Filterable\Sanitization\Sanitizer;
+
+interface InvokableEngineContext
+{
+  /**
+   * Fetch all relevant filters from the filter API class.
+   *
+   * @return array
+   */
+  public function getFilterAttributes(): array;
+
+  /**
+   * Get the current request instance.
+   * @return Request
+   */
+  public function getRequest(): Request;
+
+  /**
+   * Check if current filterable class has ignored empty values.
+   * @return bool
+   */
+  public function hasIgnoredEmptyValues(): bool;
+
+  /**
+   * Get sanitizer instance.
+   * @return Sanitizer
+   */
+  public function getSanitizerInstance(): Sanitizer;
+
+  /**
+   * Get mentors.
+   * @return array
+   */
+  public function getMentors(): array;
+}

src/Engines/Contracts/RulesetFilterableContect.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Kettasoft\Filterable\Engines\Contracts;
+
+use Kettasoft\Filterable\Sanitization\Sanitizer;
+
+interface RulesetFilterableContect
+{
+  /**
+   * Get current data.
+   * @return array
+   */
+  public function getData(): mixed;
+
+  /**
+   * Check if current filterable class has ignored empty values.
+   * @return bool
+   */
+  public function hasIgnoredEmptyValues(): bool;
+
+  /**
+   * Get columns wrapper.
+   * @return array
+   */
+  public function getFieldsMap(): array;
+
+  /**
+   * Get sanitizer instance.
+   * @return Sanitizer
+   */
+  public function getSanitizerInstance(): Sanitizer;
+
+  /**
+   * Get allowed fields to apply filtering.
+   * @return array
+   */
+  public function getAllowedFields(): array;
+
+  /**
+   * List of supported SQL operators you want to allow when parsing the expressions.
+   * @return array
+   */
+  public function getAllowedOperators(): array;
+
+  /**
+   * Check if filter has strict mode.
+   * @return mixed
+   */
+  public function isStrict();
+}

src/Engines/Contracts/TreeFilterableContext.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Kettasoft\Filterable\Engines\Contracts;
+
+use Kettasoft\Filterable\Sanitization\Sanitizer;
+
+interface TreeFilterableContext
+{
+  /**
+   * Get current data.
+   * @return array
+   */
+  public function getData(): mixed;
+
+  /**
+   * Check if current filterable class has ignored empty values.
+   * @return bool
+   */
+  public function hasIgnoredEmptyValues(): bool;
+
+  /**
+   * Get columns wrapper.
+   * @return array
+   */
+  public function getFieldsMap(): array;
+
+  /**
+   * Get sanitizer instance.
+   * @return Sanitizer
+   */
+  public function getSanitizerInstance(): Sanitizer;
+
+  /**
+   * Get allowed fields to apply filtering.
+   * @return array
+   */
+  public function getAllowedFields(): array;
+
+  /**
+   * List of supported SQL operators you want to allow when parsing the expressions.
+   * @return array
+   */
+  public function getAllowedOperators(): array;
+
+  /**
+   * Check if filter has strict mode.
+   * @return mixed
+   */
+  public function isStrict();
+}

src/Engines/Expression.php

@@ -5,21 +5,21 @@
 use Kettasoft\Filterable\Traits\FieldNormalizer;
 use Kettasoft\Filterable\Engines\Contracts\Engine;
 use Illuminate\Contracts\Database\Eloquent\Builder;
-use Kettasoft\Filterable\Contracts\FilterableContext;
 use Kettasoft\Filterable\Support\ConditionNormalizer;
 use Kettasoft\Filterable\Support\ValidateTableColumns;
 use Kettasoft\Filterable\Exceptions\InvalidOperatorException;
 use Kettasoft\Filterable\Exceptions\NotAllowedFieldException;
+use Kettasoft\Filterable\Engines\Contracts\ExpressionEngineContext;
 
 class Expression implements Engine
 {
   use FieldNormalizer;
 
   /**
    * Create Engine instance.
-   * @param \Kettasoft\Filterable\Contracts\FilterableContext $context
+   * @param \Kettasoft\Filterable\Engines\Contracts\ExpressionEngineContext $context
    */
-  public function __construct(protected FilterableContext $context) {}
+  public function __construct(protected ExpressionEngineContext $context) {}
 
   /**
    * Apply filters to the query.

src/Engines/Invokeable.php

@@ -7,7 +7,7 @@
 use Illuminate\Support\Traits\ForwardsCalls;
 use Kettasoft\Filterable\Engines\Contracts\Engine;
 use Illuminate\Contracts\Database\Eloquent\Builder;
-use Kettasoft\Filterable\Contracts\FilterableContext;
+use Kettasoft\Filterable\Engines\Contracts\InvokableEngineContext;
 use Kettasoft\Filterable\Support\ConditionNormalizer;
 
 class Invokeable implements Engine
@@ -22,9 +22,9 @@ class Invokeable implements Engine
 
   /**
    * Create Engine instance.
-   * @param \Kettasoft\Filterable\Contracts\FilterableContext $context
+   * @param \Kettasoft\Filterable\Engines\Contracts\InvokableEngineContext $context
    */
-  public function __construct(protected FilterableContext $context) {}
+  public function __construct(protected InvokableEngineContext $context) {}
 
   /**
    * Apply filters to the query.

src/Engines/Ruleset.php

@@ -5,19 +5,19 @@
 use Kettasoft\Filterable\Traits\FieldNormalizer;
 use Kettasoft\Filterable\Engines\Contracts\Engine;
 use Illuminate\Contracts\Database\Eloquent\Builder;
-use Kettasoft\Filterable\Contracts\FilterableContext;
 use Kettasoft\Filterable\Exceptions\InvalidOperatorException;
 use Kettasoft\Filterable\Exceptions\NotAllowedFieldException;
+use Kettasoft\Filterable\Engines\Contracts\RulesetFilterableContect;
 
 class Ruleset implements Engine
 {
   use FieldNormalizer;
 
   /**
    * Create Engine instance.
-   * @param \Kettasoft\Filterable\Contracts\FilterableContext $context
+   * @param \Kettasoft\Filterable\Engines\Contracts\RulesetFilterableContect $context
    */
-  public function __construct(protected FilterableContext $context) {}
+  public function __construct(protected RulesetFilterableContect $context) {}
 
   /**
    * Apply filters to the query.

src/Engines/Tree.php

@@ -8,9 +8,9 @@
 use Kettasoft\Filterable\Engines\Contracts\Engine;
 use Illuminate\Contracts\Database\Eloquent\Builder;
 use Kettasoft\Filterable\Support\RelationPathParser;
-use Kettasoft\Filterable\Contracts\FilterableContext;
 use Kettasoft\Filterable\Support\AllowedFieldChecker;
 use Kettasoft\Filterable\Support\TreeBasedRelationsResolver;
+use Kettasoft\Filterable\Engines\Contracts\TreeFilterableContext;
 use Kettasoft\Filterable\Engines\Contracts\HasAllowedFieldChecker;
 use Kettasoft\Filterable\Support\TreeBasedSignelConditionResolver;
 use Kettasoft\Filterable\Engines\Contracts\HasInteractsWithOperators;
@@ -22,9 +22,9 @@ class Tree implements Engine, HasInteractsWithOperators, HasAllowedFieldChecker
   protected operatorMapper $operatorMapper;
   /**
    * Create Engine instance.
-   * @param \Kettasoft\Filterable\Contracts\FilterableContext $context
+   * @param \Kettasoft\Filterable\Engines\Contracts\TreeFilterableContext $context
    */
-  public function __construct(protected FilterableContext $context)
+  public function __construct(protected TreeFilterableContext $context)
   {
     $this->operatorMapper = new OperatorMapper($this);
   }