Skip to content

Commit 6b35691

Browse files
author
Coen Zimmerman
committed
Fixed and improved generics in docblocks
1 parent a8a23b3 commit 6b35691

26 files changed

+287
-72
lines changed

src/BaseRepository.php

Lines changed: 28 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -32,27 +32,29 @@
3232
* by other columns, by marking the Criteria that does the ordering with key 'order'.
3333
*
3434
* @template TModel of \Illuminate\Database\Eloquent\Model
35+
*
36+
* @implements BaseRepositoryInterface<TModel>
3537
*/
3638
abstract class BaseRepository implements BaseRepositoryInterface
3739
{
3840
protected ContainerInterface $app;
3941

4042
/**
41-
* @var TModel|Model|EloquentBuilder|BaseBuilder
43+
* @var TModel|EloquentBuilder<TModel>|BaseBuilder
4244
*/
4345
protected Model|EloquentBuilder|BaseBuilder $modelOrQuery;
4446

4547
/**
4648
* Criteria to keep and use for all coming queries
4749
*
48-
* @var Collection<int|string, CriteriaInterface>
50+
* @var Collection<int|string, CriteriaInterface<TModel, Model>>
4951
*/
5052
protected Collection $criteria;
5153

5254
/**
5355
* The Criteria to only apply to the next query
5456
*
55-
* @var Collection<int|string, CriteriaInterface>
57+
* @var Collection<int|string, CriteriaInterface<TModel, Model>>
5658
*/
5759
protected Collection $onceCriteria;
5860

@@ -61,7 +63,7 @@ abstract class BaseRepository implements BaseRepositoryInterface
6163
* So this is a dynamic list that can change during calls of various repository
6264
* methods that alter the active criteria.
6365
*
64-
* @var Collection<int|string, CriteriaInterface>
66+
* @var Collection<int|string, CriteriaInterface<TModel, Model>>
6567
*/
6668
protected Collection $activeCriteria;
6769

@@ -81,8 +83,8 @@ abstract class BaseRepository implements BaseRepositoryInterface
8183

8284

8385
/**
84-
* @param ContainerInterface $container
85-
* @param Collection<int|string, CriteriaInterface> $initialCriteria
86+
* @param ContainerInterface $container
87+
* @param Collection<int|string, CriteriaInterface<TModel, Model>> $initialCriteria
8688
* @throws RepositoryException
8789
*/
8890
public function __construct(ContainerInterface $container, Collection $initialCriteria)
@@ -148,7 +150,7 @@ public function makeModel(bool $storeModel = true): Model
148150
/**
149151
* Give unexecuted (fresh) query wioth the current applied criteria.
150152
*
151-
* @return EloquentBuilder|BaseBuilder
153+
* @return EloquentBuilder<TModel>|BaseBuilder
152154
* @throws RepositoryException
153155
*/
154156
public function query(): EloquentBuilder|BaseBuilder
@@ -299,10 +301,11 @@ public function findAllBy(string $attribute, mixed $value, $columns = ['*']): El
299301
* @param array<string, callable|array<int, string>|mixed> $where
300302
* @param string[] $columns
301303
* @param bool $or
302-
* @return EloquentCollection
304+
* @return EloquentCollection<int, TModel>
303305
*/
304306
public function findWhere(array $where, array $columns = ['*'], bool $or = false): EloquentCollection
305307
{
308+
/** @var EloquentBuilder<TModel> $model */
306309
$model = $this->query();
307310

308311
foreach ($where as $field => $value) {
@@ -386,7 +389,7 @@ public function update(array $data, int|string $id, ?string $attribute = null):
386389
* @param array<string, mixed> $data
387390
* @param int|string $id
388391
* @param string|null $attribute
389-
* @return Model|false
392+
* @return TModel|false
390393
* @throws MassAssignmentException|ModelNotFoundException
391394
*/
392395
public function fill(array $data, int|string $id, ?string $attribute = null): Model|false
@@ -429,7 +432,7 @@ public function allCallback(Closure $callback, array $columns = ['*']): Eloquent
429432

430433
$this->assertValidCustomCallback($result);
431434

432-
/** @var EloquentBuilder|BaseBuilder $result */
435+
/** @var EloquentBuilder<TModel>|BaseBuilder $result */
433436
return $result->get($columns);
434437
}
435438

@@ -447,7 +450,7 @@ public function findCallback(Closure $callback, array $columns = ['*']): ?Model
447450

448451
$this->assertValidCustomCallback($result);
449452

450-
/** @var EloquentBuilder|BaseBuilder $result */
453+
/** @var EloquentBuilder<TModel>|BaseBuilder $result */
451454
return $result->first($columns);
452455
}
453456

@@ -469,7 +472,7 @@ public function findCallback(Closure $callback, array $columns = ['*']): ?Model
469472
* Override with your own defaults (check ExtendedRepository's refreshed,
470473
* named Criteria for examples).
471474
*
472-
* @return Collection<int|string, CriteriaInterface>
475+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
473476
*/
474477
public function defaultCriteria(): Collection
475478
{
@@ -504,7 +507,7 @@ public function ignoreCriteria(bool $ignore = true): void
504507
* Returns a cloned set of all currently set criteria (not including
505508
* those to be applied once).
506509
*
507-
* @return Collection<int|string, CriteriaInterface>
510+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
508511
*/
509512
public function getCriteria(): Collection
510513
{
@@ -514,7 +517,7 @@ public function getCriteria(): Collection
514517
/**
515518
* Returns a cloned set of all currently set once criteria.
516519
*
517-
* @return Collection<int|string, CriteriaInterface>
520+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
518521
*/
519522
public function getOnceCriteria(): Collection
520523
{
@@ -524,7 +527,7 @@ public function getOnceCriteria(): Collection
524527
/**
525528
* Returns a cloned set of all currently set criteria (not including those to be applied once).
526529
*
527-
* @return Collection<int|string, CriteriaInterface>
530+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
528531
*/
529532
public function getAllCriteria(): Collection
530533
{
@@ -575,8 +578,8 @@ public function applyCriteria(): void
575578
* If a criteria already exists for the key, it is overridden.
576579
* Note that this does NOT overrule any onceCriteria, even if set by key!
577580
*
578-
* @param CriteriaInterface $criteria
579-
* @param string|null $key Unique identifier, may be used to remove and overwrite criteria
581+
* @param CriteriaInterface<TModel, Model> $criteria
582+
* @param string|null $key Unique identifier, may be used to remove and overwrite criteria
580583
*/
581584
public function pushCriteria(CriteriaInterface $criteria, ?string $key = null): void
582585
{
@@ -600,8 +603,8 @@ public function removeCriteria(string $key): void
600603
*
601604
* Note that this does NOT work for specific criteria exclusively, it resets to default for ALL Criteria.
602605
*
603-
* @param CriteriaInterface $criteria
604-
* @param string|null $key
606+
* @param CriteriaInterface<TModel, Model> $criteria
607+
* @param string|null $key
605608
* @return $this
606609
*/
607610
public function pushCriteriaOnce(CriteriaInterface $criteria, ?string $key = null): static
@@ -636,15 +639,19 @@ public function removeCriteriaOnce(string $key): static
636639
}
637640

638641
// Override by key with null-value.
639-
$this->onceCriteria->put($key, new NullCriteria());
642+
/** @var NullCriteria<TModel, Model> $nullCriterion */
643+
$nullCriterion = new NullCriteria();
644+
645+
$this->onceCriteria->put($key, $nullCriterion);
646+
640647
return $this;
641648
}
642649

643650

644651
/**
645652
* Returns the criteria that must be applied for the next query.
646653
*
647-
* @return Collection<int|string, CriteriaInterface>
654+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
648655
*/
649656
protected function getCriteriaToApply(): Collection
650657
{

src/Contracts/BaseRepositoryInterface.php

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ public function makeModel(bool $storeModel = true): Model;
3838
/**
3939
* Give unexecuted (fresh) query wioth the current applied criteria.
4040
*
41-
* @return EloquentBuilder|BaseBuilder
41+
* @return EloquentBuilder<TModel>|BaseBuilder
4242
* @throws RepositoryException
4343
*/
4444
public function query(): EloquentBuilder|BaseBuilder;
@@ -124,7 +124,7 @@ public function findAllBy(string $attribute, mixed $value, $columns = ['*']): El
124124
* @param array<string, callable|array<int, string>|mixed> $where
125125
* @param string[] $columns
126126
* @param bool $or
127-
* @return EloquentCollection
127+
* @return EloquentCollection<int, TModel>
128128
*/
129129
public function findWhere(array $where, array $columns = ['*'], bool $or = false): EloquentCollection;
130130

@@ -160,7 +160,7 @@ public function update(array $data, int|string $id, ?string $attribute = null):
160160
* @param array<string, mixed> $data
161161
* @param int|string $id
162162
* @param string|null $attribute
163-
* @return Model|false
163+
* @return TModel|false
164164
* @throws MassAssignmentException|ModelNotFoundException
165165
*/
166166
public function fill(array $data, int|string $id, ?string $attribute = null): Model|false;
@@ -208,7 +208,7 @@ public function findCallback(Closure $callback, array $columns = ['*']): ?Model;
208208
* Override with your own defaults (check ExtendedRepository's refreshed,
209209
* named Criteria for examples).
210210
*
211-
* @return Collection<int|string, CriteriaInterface>
211+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
212212
*/
213213
public function defaultCriteria(): Collection;
214214

@@ -232,22 +232,22 @@ public function ignoreCriteria(bool $ignore = true): void;
232232
* Returns a cloned set of all currently set criteria (not including
233233
* those to be applied once).
234234
*
235-
* @return Collection<int|string, CriteriaInterface>
235+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
236236
*/
237237
public function getCriteria(): Collection;
238238

239239
/**
240240
* Returns a cloned set of all currently set once criteria.
241241
*
242-
* @return Collection<int|string, CriteriaInterface>
242+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
243243
*/
244244
public function getOnceCriteria(): Collection;
245245

246246
/**
247247
* Returns a cloned set of all currently set criteria (not including
248248
* those to be applied once).
249249
*
250-
* @return Collection<int|string, CriteriaInterface>
250+
* @return Collection<int|string, CriteriaInterface<TModel, Model>>
251251
*/
252252
public function getAllCriteria(): Collection;
253253

@@ -267,8 +267,8 @@ public function applyCriteria(): void;
267267
* If a criteria already exists for the key, it is overridden
268268
* Note that this does NOT overrule any onceCriteria, even if set by key!
269269
*
270-
* @param CriteriaInterface $criteria
271-
* @param string|null $key Unique identifier, may be used to remove and overwrite criteria
270+
* @param CriteriaInterface<TModel, Model> $criteria
271+
* @param string|null $key Unique identifier, may be used to remove and overwrite criteria
272272
*/
273273
public function pushCriteria(CriteriaInterface $criteria, ?string $key = null): void;
274274

@@ -283,8 +283,8 @@ public function removeCriteria(string $key): void;
283283
* Note that this does NOT work for specific criteria exclusively, it resets
284284
* to default for ALL Criteria.
285285
*
286-
* @param CriteriaInterface $criteria
287-
* @param string|null $key
286+
* @param CriteriaInterface<TModel, Model> $criteria
287+
* @param string|null $key
288288
* @return $this
289289
*/
290290
public function pushCriteriaOnce(CriteriaInterface $criteria, ?string $key = null): static;

src/Contracts/CriteriaInterface.php

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,17 @@
66
use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
77
use Illuminate\Database\Eloquent\Relations\Relation;
88
use Illuminate\Database\Query\Builder as DatabaseBuilder;
9-
use Watson\Rememberable\Query\Builder as RememberableBuilder;
109

10+
/**
11+
* @template TModel of \Illuminate\Database\Eloquent\Model
12+
* @template TRelated of \Illuminate\Database\Eloquent\Model
13+
*/
1114
interface CriteriaInterface
1215
{
1316
/**
14-
* @param Model|Relation|DatabaseBuilder|EloquentBuilder|RememberableBuilder $model
15-
* @param BaseRepositoryInterface $repository
16-
* @return Model|Relation|DatabaseBuilder|EloquentBuilder|RememberableBuilder
17+
* @param TModel|Relation<TRelated>|DatabaseBuilder|EloquentBuilder<TModel> $model
18+
* @param BaseRepositoryInterface<TModel> $repository
19+
* @return TModel|Relation<TRelated>|DatabaseBuilder|EloquentBuilder<TModel>
1720
*/
1821
public function apply(
1922
Model|Relation|DatabaseBuilder|EloquentBuilder $model,

src/Contracts/FindsModelsByTranslationInterface.php

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@
55
use Illuminate\Database\Eloquent\Collection as EloquentCollection;
66
use Illuminate\Database\Eloquent\Model;
77

8+
/**
9+
* @template TModel of \Illuminate\Database\Eloquent\Model
10+
*/
811
interface FindsModelsByTranslationInterface
912
{
1013
/**
@@ -14,9 +17,14 @@ interface FindsModelsByTranslationInterface
1417
* @param string $value
1518
* @param string|null $locale
1619
* @param bool $exact = or LIKE match
17-
* @return Model|null
20+
* @return TModel|null
1821
*/
19-
public function findByTranslation(string $attribute, string $value, string $locale = null, bool $exact = true): ?Model;
22+
public function findByTranslation(
23+
string $attribute,
24+
string $value,
25+
string $locale = null,
26+
bool $exact = true,
27+
): ?Model;
2028

2129
/**
2230
* Finds models by a given translated property.
@@ -25,7 +33,12 @@ public function findByTranslation(string $attribute, string $value, string $loca
2533
* @param string $value
2634
* @param string|null $locale
2735
* @param bool $exact = or LIKE match
28-
* @return EloquentCollection<int, Model>
36+
* @return EloquentCollection<int, TModel>
2937
*/
30-
public function findAllByTranslation(string $attribute, string $value, string $locale = null, bool $exact = true): EloquentCollection;
38+
public function findAllByTranslation(
39+
string $attribute,
40+
string $value,
41+
string $locale = null,
42+
bool $exact = true,
43+
): EloquentCollection;
3144
}

src/Contracts/HandlesEloquentRelationManipulationInterface.php

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,21 @@
44

55
use Illuminate\Database\Eloquent\Model;
66

7+
/**
8+
* @template TModel of \Illuminate\Database\Eloquent\Model
9+
*/
710
interface HandlesEloquentRelationManipulationInterface
811
{
912
/**
10-
* @param Model $model
13+
* @param TModel $model
1114
* @param string $relation name of the relation (method name)
1215
* @param array<int, int|string> $ids list of id's to connect to
1316
* @param bool $detaching
1417
*/
1518
public function sync(Model $model, string $relation, array $ids, bool $detaching = true): void;
1619

1720
/**
18-
* @param Model $model
21+
* @param TModel $model
1922
* @param string $relation name of the relation (method name)
2023
* @param int|string $id
2124
* @param array<string, mixed> $attributes
@@ -30,24 +33,24 @@ public function attach(
3033
): void;
3134

3235
/**
33-
* @param Model $model
36+
* @param TModel $model
3437
* @param string $relation name of the relation (method name)
3538
* @param array<int, int|string> $ids
3639
* @param bool $touch
3740
*/
3841
public function detach(Model $model, string $relation, array $ids = [], bool $touch = true): void;
3942

4043
/**
41-
* @param Model $model
44+
* @param TModel $model
4245
* @param string $relation name of the relation (method name)
43-
* @param Model|int|string $with
46+
* @param TModel|int|string $with
4447
*/
4548
public function associate(Model $model, string $relation, Model|int|string $with): void;
4649

4750
/**
4851
* Excecutes a dissociate on the model model provided.
4952
*
50-
* @param Model $model
53+
* @param TModel $model
5154
* @param string $relation name of the relation (method name)
5255
*/
5356
public function dissociate(Model $model, string $relation): void;

src/Contracts/HandlesEloquentSavingInterface.php

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,13 @@
88
* The point of this is to provide Eloquent saving through some
99
* intermediate object (i.e. a Repository) to make model manipulation
1010
* easier to test/mock.
11+
*
12+
* @template TModel of \Illuminate\Database\Eloquent\Model
1113
*/
1214
interface HandlesEloquentSavingInterface
1315
{
1416
/**
15-
* @param Model $model
17+
* @param TModel $model
1618
* @param array<string, mixed> $options
1719
* @return bool
1820
*/

0 commit comments

Comments
 (0)