Merge pull request #1 from worksome/feature/generics

feat: add generics and fix PHPStan

Author: owenvoke

composer.json

@@ -18,6 +18,7 @@
     "require": {
         "php": "^8.2",
         "illuminate/contracts": "^9.0 || ^10.0",
+        "illuminate/database": "^9.0 || ^10.0",
         "spatie/laravel-package-tools": "^1.14.1",
         "tucker-eric/eloquentfilter": "^3.2"
     },
@@ -62,16 +63,6 @@
             "worksome/coding-style": true
         }
     },
-    "extra": {
-        "laravel": {
-            "providers": [
-                "Worksome\\Filters\\FiltersServiceProvider"
-            ],
-            "aliases": {
-                "Filters": "Worksome\\Filters\\Facades\\Filters"
-            }
-        }
-    },
     "minimum-stability": "dev",
     "prefer-stable": true
 }

phpstan-baseline.neon

@@ -0,0 +1,6 @@
+parameters:
+	ignoreErrors:
+		-
+			message: "#^Call to an undefined method Worksome\\\\Filters\\\\ModelFilter\\:\\:withTrashed\\(\\)\\.$#"
+			count: 1
+			path: src/ModelFilter.php

src/Exceptions/MissingRequiredFilterException.php

@@ -7,7 +7,7 @@
 use Exception;
 
 /**
- * Exception thrown by FWorksome\Filters\FilterQuery when no required FilterClass property is not provided to it
+ * Exception thrown by `Worksome\Filters\FilterQuery` when a required FilterClass property is not provided to it.
  */
 class MissingRequiredFilterException extends Exception
 {

src/Filter.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Worksome\Filters;
 
 use Illuminate\Contracts\Pagination\LengthAwarePaginator;
@@ -8,17 +10,16 @@
 use Illuminate\Support\Facades\Facade;
 
 /**
- * Facade for Worksome\Filters\FilterQuery
- *
- * @method static FilterQuery model(string $modelClass)
- * @method static FilterQuery apply(string $filterClass)
- * @method static FilterQuery input(array $input = [])
- * @method static FilterQuery query(Builder $query)
- * @method static Builder getQuery
- * @method static \Illuminate\Support\Collection|static[] get
- * @method static LengthAwarePaginator paginateFilter($perPage = null, $columns = ['*'], $pageName = 'page', $page =null)
- * @method static Paginator            simplePaginateFilter($perPage = null, $columns = ['*'], $pageName = 'page', $page = null)
+ * @method static FilterQuery                             model(string $modelClass)
+ * @method static FilterQuery                             apply(string $filterClass)
+ * @method static FilterQuery                             input(array $input = [])
+ * @method static FilterQuery                             query(Builder $query)
+ * @method static Builder                                 getQuery()
+ * @method static \Illuminate\Support\Collection|static[] get()
+ * @method static LengthAwarePaginator                    paginateFilter($perPage = null, $columns = ['*'], $pageName = 'page', $page = null)
+ * @method static Paginator                               simplePaginateFilter($perPage = null, $columns = ['*'], $pageName = 'page', $page = null)
  *
+ * @see FilterQuery
  */
 class Filter extends Facade
 {

src/FilterQuery.php

@@ -1,37 +1,53 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Worksome\Filters;
 
 use Illuminate\Contracts\Config\Repository;
 use Illuminate\Contracts\Pagination\LengthAwarePaginator;
 use Illuminate\Contracts\Pagination\Paginator;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Database\Eloquent\Model;
 use Worksome\Filters\Exceptions\MissingRequiredFilterException;
 use Worksome\Filters\Exceptions\MissingRequiredModelOrQueryException;
 
-/** Our own implementation for filtering based on `EloquentFilter\Filterable`, but without the usage of scopes. */
+/**
+ * Our own implementation for filtering based on `EloquentFilter\Filterable`, but without the usage of scopes.
+ *
+ * @template TModel of Model
+ * @template TFilter of ModelFilter
+ */
 class FilterQuery
 {
-    /** @var array<int, string> */
+    /** @var array */
     protected array $filtered = [];
 
-    /** @var array<int, mixed> */
+    /** @var array<int|string, mixed> */
     protected array $input = [];
 
     protected Repository $config;
 
+    /** @var class-string<TModel>|null */
     private string|null $modelClass = null;
 
+    /** @var class-string<TFilter>|null */
     private string|null $filterClass = null;
 
+    /** @var Builder<TModel>|null */
     private Builder|null $query = null;
 
     public function __construct(Repository $config)
     {
         $this->config = $config;
     }
 
+    /**
+     * @param  class-string<TModel>  $modelClass
+     *
+     * @return self<TModel, TFilter>
+     */
     public function model(string $modelClass): self
     {
         $this->modelClass = $modelClass;
@@ -40,29 +56,47 @@ public function model(string $modelClass): self
         return $this;
     }
 
+    /**
+     * @param  class-string<TFilter>  $filterClass
+     *
+     * @return self<TModel, TFilter>
+     */
     public function apply(string $filterClass): self
     {
         if ($this->filterClass && $this->filterClass != $filterClass) {
             $this->resetQuery();
         }
+
         $this->filterClass = $filterClass;
 
         return $this;
     }
 
-    /** @param array<string, mixed> $input */
+    /**
+     * @param  array<string, mixed>  $input
+     *
+     * @return self<TModel, TFilter>
+     */
     public function input(array $input = []): self
     {
         $this->input = $input;
+
         return $this;
     }
 
+    /**
+     * @param  Builder<TModel>  $query
+     *
+     * @return self<TModel, TFilter>
+     */
     public function query(Builder $query): self
     {
         $this->query = $query;
+
         return $this;
     }
 
+    /** @return Builder<TModel> */
     public function getQuery(): Builder
     {
         if (! isset($this->query)) {
@@ -75,35 +109,40 @@ public function getQuery(): Builder
     }
 
     /**
-     * @return Builder[]|Collection
+     * @return Collection<int, TModel>
      *
      * @throws MissingRequiredFilterException|MissingRequiredModelOrQueryException
      */
-    public function get()
+    public function get(): Collection
     {
         return $this->getQuery()->get();
     }
 
     /**
-     * @param array<string> $columns
+     * @param  array<string>  $columns
+     *
+     * @return LengthAwarePaginator<TModel>
      *
      * @throws MissingRequiredFilterException|MissingRequiredModelOrQueryException
      */
     public function paginateFilter(
-        ?int $perPage = null,
+        int|null $perPage = null,
         array $columns = ['*'],
         string $pageName = 'page',
-        ?int $page = null,
+        int|null $page = null,
     ): LengthAwarePaginator {
         $perPage = $perPage ?: $this->config->get('eloquentfilter.paginate_limit');
+        assert($perPage === null || is_int($perPage));
         $paginator = $this->getQuery()->paginate($perPage, $columns, $pageName, $page);
         $paginator->appends($this->filtered);
 
         return $paginator;
     }
 
     /**
-     * @param array<int, string> $columns
+     * @param  array<int, string>  $columns
+     *
+     * @return Paginator<TModel>
      *
      * @throws MissingRequiredFilterException|MissingRequiredModelOrQueryException
      */
@@ -114,49 +153,61 @@ public function simplePaginateFilter(
         int|null $page = null,
     ): Paginator {
         $perPage = $perPage ?: $this->config->get('eloquentfilter.paginate_limit');
+        assert($perPage === null || is_int($perPage));
         $paginator = $this->getQuery()->simplePaginate($perPage, $columns, $pageName, $page);
         $paginator->appends($this->filtered);
 
         return $paginator;
     }
 
+    /** @return self<TModel, TFilter> */
     protected function run(): self
     {
         $filter = $this->provideFilter();
 
         $modelFilter = new $filter($this->query, $this->input);
 
+        // @phpstan-ignore-next-line
         $this->filtered = $modelFilter->input();
 
         $modelFilter->handle();
 
         return $this;
     }
 
+    /** @return class-string<TModel> */
     private function getModelClass(): string
     {
         if (! isset($this->modelClass)) {
             throw new MissingRequiredModelOrQueryException('Filter is missing required eloquent Model class.');
         }
+
         return $this->modelClass;
     }
 
+    /** @return class-string<TFilter>|class-string<ModelFilter> */
     private function provideFilter(): string
     {
         if ($this->filterClass) {
             return $this->filterClass;
         }
 
-        $filter = $this->config->get(
+        $namespace = $this->config->get(
             'eloquentfilter.namespace',
             'App\\ModelFilters\\'
-        ) . class_basename($this) . 'Filter';
+        );
 
-        if (class_exists($filter)) {
-            return $filter;
+        assert(is_string($namespace));
+
+        $filter = sprintf('%s%sFilter', $namespace, class_basename($this));
+
+        if (! class_exists($filter)) {
+            throw new MissingRequiredFilterException();
         }
 
-        throw new MissingRequiredFilterException();
+        assert(is_subclass_of($filter, ModelFilter::class));
+
+        return $filter;
     }
 
     private function resetQuery(): void

src/ModelFilter.php

@@ -1,11 +1,16 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Worksome\Filters;
 
 use EloquentFilter\ModelFilter as BaseModelFilter;
+use Illuminate\Database\Eloquent\SoftDeletes;
 use Illuminate\Support\Str;
 
-/** This class wraps around the `EloquentFilter\ModelFilter` to add sorting functionality and `IncludeTrash` helper. */
+/**
+ * This class wraps around the `EloquentFilter\ModelFilter` to add sorting functionality and `IncludeTrash` helper.
+ */
 class ModelFilter extends BaseModelFilter
 {
     /**
@@ -44,22 +49,26 @@ public function sortBy(array $sorts): void
             // Check if pre-defined orderBy method exists to sort by
             if (method_exists($this, $method = 'sortBy' . Str::studly($column))) {
                 $this->$method($direction);
+
                 continue;
             }
 
             // Otherwise order by the column in a specific direction, default DESC
             if ($this->isSortable($column)) {
                 $this->orderBy($column, $direction);
+
                 continue;
             }
         }
     }
 
-    public function includeTrashed(bool $value): void
+    public function includeTrashed(bool $includeTrashed = true): void
     {
-        if ($value) {
-            $this->withTrashed();
+        if (! $includeTrashed) {
+            return;
         }
+
+        $this->withTrashed();
     }
 
     protected function prefixWithModelTable(string $field): string