Merge pull request #19 from teamq-ec/add-scribe-docs

Add scribe docs

composer.json

@@ -26,10 +26,12 @@
         "spatie/laravel-query-builder": "^5.2|^6.0"
     },
     "require-dev": {
+        "knuckleswtf/scribe": "^4.37",
         "laravel/pint": "^1.0",
         "orchestra/testbench": "^8.0|^9.0",
         "pestphp/pest": "^2.0",
-        "pestphp/pest-plugin-laravel": "^2.0"
+        "pestphp/pest-plugin-laravel": "^2.0",
+        "spatie/invade": "^2.1"
     },
     "autoload": {
         "psr-4": {

config/datatables.php

@@ -1,5 +1,9 @@
 <?php
 
+use Spatie\QueryBuilder;
+use TeamQ\Datatables;
+use TeamQ\Datatables\Scribe\Strategies\Documentations;
+
 return [
     'parameters' => [
         'per_page' => 'per_page',
@@ -9,4 +13,16 @@
         // Represents the value to be sent by the user, to obtain all records, if using the result method.
         'all' => 'all',
     ],
+
+    'documentation' => [
+        QueryBuilder\Filters\FiltersExact::class => Documentations\Filters\ExactFilter::class,
+        QueryBuilder\Filters\FiltersPartial::class => Documentations\Filters\PartialFilter::class,
+        QueryBuilder\Filters\FiltersBeginsWithStrict::class => Documentations\Filters\BeginsWithStrictFilter::class,
+        QueryBuilder\Filters\FiltersEndsWithStrict::class => Documentations\Filters\EndsWithStrictFilter::class,
+        QueryBuilder\Filters\FiltersTrashed::class => Documentations\Filters\TrashedFilter::class,
+        Datatables\Filters\GlobalFilter::class => Documentations\Filters\GlobalFilter::class,
+        Datatables\Filters\DateFilter::class => Documentations\Filters\DateFilter::class,
+        Datatables\Filters\NumberFilter::class => Documentations\Filters\NumberFilter::class,
+        Datatables\Filters\TextFilter::class => Documentations\Filters\TextFilter::class,
+    ],
 ];

src/Scribe/Strategies/Documentations/Documentation.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations;
+
+use Illuminate\Support\Collection;
+use Knuckles\Scribe\Attributes\QueryParam;
+use ReflectionClass;
+use ReflectionException;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+
+class Documentation
+{
+    /**
+     * Gets the documentation for the query params of the Spatie QueryBuilder package.
+     *
+     *
+     * @return array|string[]
+     *
+     * @throws ReflectionException
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        $reflectionClass = new ReflectionClass($param);
+
+        $documentation = $reflectionClass->getAttributes(QueryParam::class);
+
+        if (! empty($documentation)) {
+            $documentation = $documentation[0]->newInstance();
+
+            return $documentation->toArray();
+        }
+
+        if (method_exists($param, 'docs')) {
+            return $param::docs()->toArray();
+        }
+
+        return [];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/BeginsWithStrictFilter.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class BeginsWithStrictFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => 'Begin Partial Filter. It is evaluated as: The field starts with this value.',
+            // 'example' => str($value)->substr(0, 3) ?: 'https://',
+        ];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/DateFilter.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Enums\Comparators\Number;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class DateFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        $operators = collect(Number::cases())
+            ->map(fn (Number $operator) => "<li>{$operator->value} - {$operator->name}</li>")
+            ->join('');
+
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => "<div>Date Filter. It belongs to a type of advanced filter, it allows filtering according to operators. Can receive different payload:
+                    <ul>
+                        <li><b>{$name}=2023-04-01</b><br>It is evaluated by equals.</li>
+                        <li><b>{$name}[value]=2023-04-01</b><br>It is evaluated by equals.</li>
+                        <li><b>{$name}[value]=2023-04-01&{$name}[operator]=5</b><br>It is evaluated by operator 5 (LessThan).</li>
+                        <li><b>{$name}[value][0]=2023-04-01&{$name}[value][1]=2023-07-30&{$name}[operator]=7</b><br>It is evaluated by operator 7 (Between). This operator will only take the first two 'values' however operators like 'In' will take the entire array of 'values'</li>
+                    </ul>
+                    Valid comparison operators are:
+                    <ul>
+                    $operators
+                    </ul>
+                </div>",
+        ];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/EndsWithStrictFilter.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class EndsWithStrictFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => 'End Partial Filter. It is evaluated as: The field ends with this value.',
+            // 'example' => str($value)->substr(0, 3) ?: '@gmail.com',
+        ];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/ExactFilter.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class ExactFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => 'Exact Filter. It is evaluated as: The field is exactly equal to this value.',
+            // 'example' => $value ?: '[email protected]',
+        ];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/GlobalFilter.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class GlobalFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => 'This will search for the given value among the following fields: <ul>'.array_reduce(invade($param)->fields, static fn ($carry, $value) => $carry."<li>{$value}</li>", '').'</ul>',
+        ];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/NumberFilter.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Enums\Comparators\Number;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class NumberFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        $operators = collect(Number::cases())
+            ->map(fn (Number $operator) => "<li>{$operator->value} - {$operator->name}</li>")
+            ->join('');
+
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => "<div>Number Filter. It belongs to a type of advanced filter, it allows filtering according to operators. Can receive different payload:
+                    <ul>
+                        <li><b>{$name}=20</b><br>It is evaluated by equals.</li>
+                        <li><b>{$name}[value]=20</b><br>It is evaluated by equals.</li>
+                        <li><b>{$name}[value]=20&{$name}[operator]=5</b><br>It is evaluated by operator 5 (LessThan).</li>
+                        <li><b>{$name}[value][0]=20&{$name}[value][1]=20&{$name}[operator]=5</b><br>It is evaluated by operator 7 (Between). This operator will only take the first two 'values' however operators like 'In' will take the entire array of 'values'.</li>
+                    </ul>
+                    Valid comparison operators are:
+                    <ul>
+                    $operators
+                    </ul>
+            </div>",
+        ];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/PartialFilter.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class PartialFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => 'Partial Filter. It is evaluated as: The field contains this value.',
+            // 'example' => str($value)->substr(2, 5) ?: str()->words(2)->lower(),
+        ];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/TextFilter.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Enums\Comparators\Text;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class TextFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        $operators = collect(Text::cases())
+            ->map(fn (Text $operator) => "<li>{$operator->value} - {$operator->name}</li>")
+            ->join('');
+
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => "<div>Text Filter. It belongs to a type of advanced filter, it allows filtering according to operators. Can receive different payload:
+                    <ul>
+                        <li><b>{$name}=Luis</b> It is evaluated by equals.</li>
+                        <li><b>{$name}[value]=Luis</b> It is evaluated by equals.</li>
+                        <li><b>{$name}[value]=Luis&{$name}[operator]=5</b> It is evaluated by operator 5 (EndWith).</li>
+                    </ul>
+                    Valid comparison operators are:
+                    <ul>
+                    $operators
+                    </ul>
+            </div>",
+        ];
+    }
+}

src/Scribe/Strategies/Documentations/Filters/TrashedFilter.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace TeamQ\Datatables\Scribe\Strategies\Documentations\Filters;
+
+use Illuminate\Support\Collection;
+use Spatie\QueryBuilder\Filters\Filter;
+use Spatie\QueryBuilder\Sorts\Sort;
+use TeamQ\Datatables\Scribe\Strategies\Documentations\Documentation;
+
+class TrashedFilter extends Documentation
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(Filter|Sort|Collection|string $param, mixed $value = null, ?string $name = null): array
+    {
+        return [
+            'name' => $name,
+            'type' => 'string',
+            'required' => false,
+            'description' => 'Trashed Filter. For soft deleted records. The accepted values are:
+                    <ul>
+                        <li><b>with:</b> With deleted records.</li>
+                        <li><b>only:</b> Only deleted records.</li>
+                        <li><b>without:</b> Without deleted records.</li>
+                    </ul>',
+            'example' => 'only',
+        ];
+    }
+}