chore: better Repository docs (#1852)

app/Repositories/Contracts/RepositoryInterface.php

@@ -2,18 +2,31 @@
 
 namespace App\Repositories\Contracts;
 
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Collection;
 
+/** @template T of Model */
 interface RepositoryInterface
 {
+    /** @return T */
     public function getOne($id): Model;
 
+    /** @return T */
+    public function getOneBy(array $params): Model;
+
+    /** @return T|null */
     public function findOne($id): ?Model;
 
-    /** @return Collection<Model> */
+    /** @return T|null */
+    public function findOneBy(array $params): ?Model;
+
+    /** @return Collection<array-key, T> */
     public function getMany(array $ids, bool $preserveOrder = false): Collection;
 
-    /** @return Collection<Model> */
+    /** @return Collection<int, T> */
-    public function getAll(): Collection;
+    public function getAll(): EloquentCollection;
+
+    /** @return T|null */
+    public function findFirstWhere(...$params): ?Model;
 }

app/Repositories/Repository.php

@@ -4,72 +4,78 @@ namespace App\Repositories;
 
 use App\Repositories\Contracts\RepositoryInterface;
 use Illuminate\Contracts\Auth\Guard;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Collection;
 
-/** @template T of Model */
+/**
+ * @template T of Model
+ * @implements RepositoryInterface<T>
+ */
 abstract class Repository implements RepositoryInterface
 {
-    private string $modelClass;
+    /** @var class-string<T> $modelClass */
-    protected Guard $auth;
+    protected string $modelClass;
-    public Model $model;
 
+    protected Guard $auth;
+
+    /** @param class-string<T> $modelClass */
     public function __construct(?string $modelClass = null)
     {
         $this->modelClass = $modelClass ?: self::guessModelClass();
-        $this->model = app($this->modelClass);
 
         // This instantiation may fail during a console command if e.g. APP_KEY is empty,
         // rendering the whole installation failing.
         rescue(fn () => $this->auth = app(Guard::class));
     }
 
+    /** @return class-string<T> */
     private static function guessModelClass(): string
     {
         return preg_replace('/(.+)\\\\Repositories\\\\(.+)Repository$/m', '$1\Models\\\$2', static::class);
     }
 
-    /** @return T */
+    /** @inheritDoc */
     public function getOne($id): Model
     {
-        return $this->model::query()->findOrFail($id);
+        return $this->modelClass::query()->findOrFail($id);
     }
 
-    /** @return T|null */
+    /** @inheritDoc */
-    public function findOneBy(array $params): ?Model
-    {
-        return $this->model::query()->where($params)->first();
-    }
-
-    /** @return T|null */
     public function findOne($id): ?Model
     {
-        return $this->model::query()->find($id);
+        return $this->modelClass::query()->find($id);
     }
 
-    /** @return T */
+    /** @inheritDoc */
     public function getOneBy(array $params): Model
     {
-        return $this->model::query()->where($params)->firstOrFail();
+        return $this->modelClass::query()->where($params)->firstOrFail();
     }
 
-    /** @return array<array-key, T>|Collection<array-key, T> */
+    /** @inheritDoc */
+    public function findOneBy(array $params): ?Model
+    {
+        return $this->modelClass::query()->where($params)->first();
+    }
+
+    /** @inheritDoc */
     public function getMany(array $ids, bool $preserveOrder = false): Collection
     {
-        $models = $this->model::query()->find($ids);
+        $models = $this->modelClass::query()->find($ids);
 
         return $preserveOrder ? $models->orderByArray($ids) : $models;
     }
 
-    /** @return array<array-key, T>|Collection<array-key, T> */
+    /** @inheritDoc */ // @phpcs:ignore
-    public function getAll(): Collection
+    public function getAll(): EloquentCollection
     {
-        return $this->model::all();
+        return $this->modelClass::all();
     }
 
-    /** @return T|null  */
+    /** @inheritDoc */
     public function findFirstWhere(...$params): ?Model
     {
-        return $this->model::query()->firstWhere(...$params);
+        return $this->modelClass::query()->firstWhere(...$params);
     }
 }

app/Repositories/SettingRepository.php

@@ -10,7 +10,7 @@ class SettingRepository extends Repository
     /** @return array<mixed> */
     public function getAllAsKeyValueArray(): array
     {
-        return $this->model->pluck('value', 'key')->toArray();
+        return $this->modelClass::query()->pluck('value', 'key')->toArray();
     }
 
     public function getByKey(string $key): mixed