Refactor/Interface improvement. (#21)

Author: othercodes

.github/workflows/documentation.yml

@@ -0,0 +1,48 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ 'main' ]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        php-version: [ '8.2' ]
+
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v2
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: mbstring
+          coverage: xdebug
+          tools: composer:v2
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ~/.composer/cache
+          key: php-${{ matrix.php-version }}-composer-${{ hashFiles('**/composer.json') }}
+          restore-keys: php-${{ matrix.php-version }}-composer-
+
+      - name: Validate composer.json and composer.lock
+        run: composer validate
+
+      - name: Install Dependencies
+        run: composer install --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+
+      - name: Copy Files
+        run: cp README.md wiki/Home.md
+
+      - name: Publish documentation to Wiki
+        uses: SwiftDocOrg/github-wiki-publish-action@v1
+        with:
+          path: "wiki/"
+        env:
+          GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

README.md

@@ -1,10 +1,10 @@
-# Criteria (a.k.a Filter)
+# Criteria
 
 [![Test](https://github.com/ComplexHeart/php-criteria/actions/workflows/test.yml/badge.svg)](https://github.com/ComplexHeart/php-criteria/actions/workflows/test.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ComplexHeart_php-criteria&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ComplexHeart_php-criteria)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ComplexHeart_php-criteria&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ComplexHeart_php-criteria)
 
-Small implementation of a filter criteria pattern in PHP for Complex Heart SDK. Compose several filters using fluent
+Small implementation of a criteria pattern in PHP for Complex Heart SDK. Compose several filters using fluent
 interface.
 
 ## Installation
@@ -58,7 +58,6 @@ A `FilterGroup` is a set of filters or conditions that must match all together (
 (`OR`), just add more `FilterGroup`.
 
 ```php
-
 // Match articles with given term in title, or in tagline, or in content.
 $criteria = Criteria::default()
     ->withFilterGroup(FilterGroup::create()->addFilterContains('title', $term))
@@ -68,3 +67,5 @@ $criteria = Criteria::default()
     ->withOrderType(Order::TYPE_ASC)
     ->withPageNumber(3);
 ```
+
+

src/Contracts/CriteriaSource.php

@@ -50,9 +50,16 @@ public function orderBy(): string;
     public function pageLimit(): int;
 
     /**
-     * Provides the offset, by default should be 0.
+     * Provides the offset, by default should be 0. This value will be discarded
+     * if page number returns a value > 0.
      *
      * @return int
      */
     public function pageOffset(): int;
+
+    /**
+     * Provides the page number. If value > 0, will be used to compute the offset.
+     * @return int
+     */
+    public function pageNumber(): int;
 }

src/Criteria.php

@@ -68,6 +68,15 @@ public static function create(array $groups, Order $order, Page $page): self
         return new self(groups: $groups, order: $order, page: $page);
     }
 
+    public static function default(): self
+    {
+        return self::create(
+            groups: [],
+            order: Order::none(),
+            page: Page::default()
+        );
+    }
+
     /**
      * Creates a new instance of Criteria from the given data source.
      *
@@ -76,21 +85,18 @@ public static function create(array $groups, Order $order, Page $page): self
      */
     public static function fromSource(CriteriaSource $source): self
     {
-        return Criteria::create(
+        return self::create(
             groups: map(
-                fn(array $g): FilterGroup => FilterGroup::createFromArray($g),
+                fn(array $g): FilterGroup => FilterGroup::fromArray($g),
                 $source->filterGroups()
             ),
             order: Order::create($source->orderBy(), OrderType::make($source->orderType())),
-            page: Page::create($source->pageLimit(), $source->pageOffset())
+            page: $source->pageNumber() > 0
+                ? Page::number($source->pageNumber(), $source->pageLimit())
+                : Page::create($source->pageLimit(), $source->pageOffset())
         );
     }
 
-    public static function default(): self
-    {
-        return self::create(groups: [], order: Order::none(), page: Page::create());
-    }
-
     /**
      * Returns a new instance of the criteria with the given FilterGroups.
      *
@@ -114,9 +120,7 @@ public function withFilterGroups(array $groups): self
      */
     public function withFilterGroup(FilterGroup|Closure $group): self
     {
-        if (is_callable($group)) {
-            $group = $group(new FilterGroup());
-        }
+        $group = $group instanceof FilterGroup ? $group : $group(FilterGroup::create());
 
         // push single FilterGroup into an array.
         $group = is_array($group) ? $group : [$group];
@@ -157,21 +161,21 @@ public function withPage(Page $page): self
         return self::create(groups: $this->groups, order: $this->order, page: $page);
     }
 
-    public function withPageOffset(int $offset): self
+    public function withPageLimit(int $limit): self
     {
         return self::create(
             groups: $this->groups,
             order: $this->order,
-            page: Page::create($this->pageLimit(), $offset)
+            page: Page::create($limit, $this->pageOffset())
         );
     }
 
-    public function withPageLimit(int $limit): self
+    public function withPageOffset(int $offset): self
     {
         return self::create(
             groups: $this->groups,
             order: $this->order,
-            page: Page::create($limit, $this->pageOffset())
+            page: Page::create($this->pageLimit(), $offset)
         );
     }
 
@@ -180,7 +184,7 @@ public function withPageNumber(int $number, int $size = null): self
         return self::create(
             groups: $this->groups,
             order: $this->order,
-            page: Page::number($number, is_null($size) ? $this->page->limit() : $size)
+            page: Page::number($number, is_null($size) ? $this->pageLimit() : $size)
         );
     }
 
@@ -214,14 +218,14 @@ public function page(): Page
         return $this->page;
     }
 
-    public function pageOffset(): int
+    public function pageLimit(): int
     {
-        return $this->page->offset();
+        return $this->page->limit();
     }
 
-    public function pageLimit(): int
+    public function pageOffset(): int
     {
-        return $this->page->limit();
+        return $this->page->offset();
     }
 
     public function __toString(): string

src/Filter.php

@@ -38,7 +38,6 @@ public function __construct(
      * @param  string  $field
      * @param  Operator  $operator
      * @param  mixed  $value
-     *
      * @return Filter
      */
     public static function create(string $field, Operator $operator, mixed $value): self
@@ -48,82 +47,82 @@ public static function create(string $field, Operator $operator, mixed $value):
 
     /**
      * @param  array<string, scalar>|array<string>  $filter
-     * @return self
+     * @return Filter
      */
-    public static function createFromArray(array $filter): self
+    public static function fromArray(array $filter): self
     {
         // check if the array is indexed or associative.
         $isIndexed = fn($source): bool => ([] !== $source) && array_keys($source) === range(0, count($source) - 1);
 
         return ($isIndexed($filter))
             ? self::create(
                 "$filter[0]",
-                Operator::make("$filter[1]"),
+                Operator::create("$filter[1]"),
                 $filter[2]
             )
             : self::create(
                 "{$filter['field']}",
-                Operator::make("{$filter['operator']}"),
+                Operator::create("{$filter['operator']}"),
                 "{$filter['value']}"
             );
     }
 
-    public static function createEqual(string $field, mixed $value): self
+    public static function equal(string $field, mixed $value): self
     {
         return self::create($field, Operator::EQUAL, $value);
     }
 
-    public static function createNotEqual(string $field, mixed $value): self
+    public static function notEqual(string $field, mixed $value): self
     {
         return self::create($field, Operator::NOT_LIKE, $value);
     }
 
-    public static function createGreaterThan(string $field, mixed $value): self
+    public static function greaterThan(string $field, mixed $value): self
     {
         return self::create($field, Operator::GT, $value);
     }
 
-    public static function createGreaterOrEqualThan(string $field, mixed $value): self
+    public static function greaterOrEqualThan(string $field, mixed $value): self
     {
         return self::create($field, Operator::GTE, $value);
     }
 
-    public static function createLessThan(string $field, mixed $value): self
+    public static function lessThan(string $field, mixed $value): self
     {
         return self::create($field, Operator::LT, $value);
     }
 
-    public static function createLessOrEqualThan(string $field, mixed $value): self
+    public static function lessOrEqualThan(string $field, mixed $value): self
     {
         return self::create($field, Operator::LTE, $value);
     }
 
-    public static function createIn(string $field, mixed $value): self
+    public static function in(string $field, mixed $value): self
     {
         return self::create($field, Operator::IN, $value);
     }
 
-    public static function createNotIn(string $field, mixed $value): self
+    public static function notIn(string $field, mixed $value): self
     {
         return self::create($field, Operator::NOT_IN, $value);
     }
 
-    public static function createLike(string $field, mixed $value): self
+    public static function like(string $field, mixed $value): self
     {
         return self::create($field, Operator::LIKE, $value);
     }
 
-    public static function createNotLike(string $field, mixed $value): self
+    public static function notLike(string $field, mixed $value): self
     {
         return self::create($field, Operator::NOT_LIKE, $value);
     }
 
-    public static function createContains(string $field, mixed $value): self
+    public static function contains(string $field, mixed $value): self
     {
         return self::create($field, Operator::CONTAINS, $value);
     }
 
-    public static function createNotContains(string $field, mixed $value): self
+    public static function notContains(string $field, mixed $value): self
     {
         return self::create($field, Operator::NOT_CONTAINS, $value);
     }
@@ -165,7 +164,7 @@ public function __toString(): string
             $this->field(),
             $this->operator()->value,
             is_array($this->value())
-                ? implode('|', $this->value())
+                ? implode(',', $this->value())
                 : $this->value()
         );
     }