Feature/Add documentation workflow. (#2)

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,3 +1,23 @@
 # Complex Heart On Laravel
 
-Laravel integration with Complex Heart library.
+[![Test](https://github.com/ComplexHeart/on-laravel/actions/workflows/test.yml/badge.svg)](https://github.com/ComplexHeart/on-laravel/actions/workflows/test.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ComplexHeart_on-laravel&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ComplexHeart_on-laravel)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ComplexHeart_on-laravel&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ComplexHeart_on-laravel)
+
+Laravel integration with Complex Heart SDK.
+
+## Installation
+
+Just install the package from Packagist using composer:
+
+```bash
+composer require complex-heart/on-laravel
+```
+
+## Usage
+
+- [HTTP Request as Criteria Source](https://github.com/ComplexHeart/on-laravel/wiki/HTTP-Request-as-Criteria-Source)
+- [Eloquent Criteria Parser](https://github.com/ComplexHeart/on-laravel/wiki/Eloquent-Criteria-Parser)
+
+
+

sonar-project.properties

@@ -1,4 +1,4 @@
-sonar.projectName=Complex Heart on Laravel
+sonar.projectName=On Laravel
 sonar.projectKey=ComplexHeart_on-laravel
 sonar.organization=complexheart
 sonar.language=php

wiki/Eloquent-Criteria-Parser.md

@@ -0,0 +1,64 @@
+# Eloquent Criteria Parser
+
+Using the Eloquent Criteria Parser is quite simple. Just instantiate the class, next, pass a Criteria instance to
+the `applyCriteria()` method along with a `EloquentQueryBuilder` instance:
+
+```php
+$parser = new BasicCriteriaParser();
+$query = $parser->applyCriteria(User::query(), $criteria);
+```
+
+The returned `EloquentQueryBuilder` has the criteria applied. You just need to call the `get` method to fetch the data
+from the database.
+
+```php
+$users = $query->get();
+```
+
+Alternatively, you can pass an array of strings to map the attributes between the domain and the database.
+
+```php
+$parser = new BasicCriteriaParser([
+    'domain-attribute' => 'database-attribute',
+]);
+```
+
+For example,
+given the following table:
+
+```php
+$this->builder->create('users', function (Blueprint $table) {
+    $table->uuid('id');
+    $table->string('first_name');
+    $table->string('last_name');
+    $table->string('email')->unique();
+    $table->string('bio')->nullable();
+    $table->timestamps();
+});
+```
+
+You may use the following configuration to use `name` and `surname` instead of `first_name` and `last_name`:
+
+```php
+$parser = new BasicCriteriaParser([
+    'name' => 'first_name',
+    'surname' => 'last_name'
+]);
+```
+
+A criteria search will be something like this:
+
+```php
+$criteria = Criteria::default()
+    ->withFilterGroup(FilterGroup::create()
+        ->addFilterEqual('name', 'Vicent'));
+
+$builder = User::query();
+
+$parser = new BasicCriteriaParser();
+$users = $parser
+    ->applyCriteria($builder, $criteria)
+    ->get();
+```
+
+This is useful to expose different attributes from different interfaces as HTTP, or CLI.  

wiki/HTTP-Request-as-Criteria-Source.md

@@ -0,0 +1,79 @@
+# HTTP Request as Criteria source
+
+Let's see a brief example of how to implement a `CriteriaSource` along with **Laravel** HTTP Request.
+
+First, create a [Form Request](https://laravel.com/docs/10.x/validation#creating-form-requests) to implement
+the `CriteriaSource` interface.
+
+```bash
+php artisan make:request SearchUserRequest
+```
+
+Next, implement the interface:
+
+```php
+namespace LaravelMade\Http\Requests;
+
+use ComplexHeart\Domain\Criteria\Contracts\CriteriaSource;
+use Illuminate\Foundation\Http\FormRequest;
+
+class SearchUserRequest extends FormRequest implements CriteriaSource
+{
+    public function filterGroups(): array
+    {
+        // get the filter groups from the request.
+        // you can also return N groups of filters (OR).
+        return [$this->input('filters', [])];
+    }
+
+    public function orderType(): string
+    {
+        return $this->input('order', 'none');
+    }
+
+    public function orderBy(): string
+    {
+        return $this->input('orderBy', '');
+    }
+
+    public function pageLimit(): int
+    {
+        return $this->input('limit', 25);
+    }
+
+    public function pageOffset(): int
+    {
+        return $this->input('offset', 0);
+    }
+
+    public function pageNumber(): int
+    {
+        return $this->input('page', 0);
+    }
+}
+```
+
+Done, now you only need to call the `fromSource` method of the `Criteria` object.
+
+```php
+Route::get('users', function (SearchUserRequest $request): JsonResponse {
+    $criteria = Criteria::fromSource($request);
+
+    // use criteria to fetch the users.
+});
+```
+
+Additionally, you can add rules to the `FormRequest` object to ensure the `Criteria` is properly instantiated. If the
+`Criteria` object cannot be instantiated a `CriteriaError` will be thrown.
+
+```php
+Route::get('users', function (SearchUserRequest $request): JsonResponse {
+    try {
+        $criteria = Criteria::fromSource($request);
+    } catch (CriteriaError $e) {
+        // handle the Criteria error
+    }
+
+    // use criteria to fetch the users.
+});
+```