Add support for phpstan generics

Author: Hendrik Nijmeijer

README.md

@@ -477,6 +477,52 @@ N.B. This example uses our [swisnl/php-http-fixture-client](https://github.com/s
 This package allows you to easily mock requests with static fixtures.
 Definitely worth a try!
 
+## Using generics
+
+This package provides support for generic types in repositories and relationships,
+so your IDE can provide type hinting and auto-completion for the items you are working with.
+
+This is achieved by using [generics in PHPDoc annotations](https://phpstan.org/blog/generics-in-php-using-phpdocs).
+
+### Repositories
+
+```php
+
+/** @implements RepositoryInterface<BlogItem> */
+class BlogRepository extends \Swis\JsonApi\Client\Repository {...}
+
+```
+
+Now, when you use the `BlogRepository` class, your IDE understands the correct return types for the `all()`, `find()` and `save()` methods.
+
+### Relationships
+
+You can also use generics in your relationships to specify the type of the related item.
+Just use the `OneRelationInterface` or `ManyRelationInterface` interfaces in your relation method and specify the type of the related item:
+
+```php
+
+/** @return \Swis\JsonApi\Client\Interfaces\OneRelationInterface<AuthorItem> */
+public function author(): OneRelationInterface
+{
+    return $this->hasOne(AuthorItem::class);
+}
+
+```
+
+This way, when accessing the `$blog->author()->getData()`, your IDE will understand that it returns an `AuthorItem` instance.
+
+The same can be achieved for ManyRelations (`HasMany`, `MorphToMany`):
+
+```php
+
+/** @return \Swis\JsonApi\Client\Interfaces\ManyRelationInterface<AuthorItem> */
+public function comments(): ManyRelationInterface
+{
+    return $this->hasMany(CommentItem::class);
+}
+
+```
 
 ## Advanced usage
 

src/Collection.php

@@ -6,6 +6,12 @@
 
 use Swis\JsonApi\Client\Interfaces\DataInterface;
 
+/**
+ * @template TKey of array-key
+ * @template TValue of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ *
+ * @extends \Illuminate\Support\Collection<TKey, TValue>
+ */
 class Collection extends \Illuminate\Support\Collection implements DataInterface
 {
     /**

src/Concerns/HasRelations.php

@@ -26,8 +26,10 @@ trait HasRelations
     /**
      * Create a singular relation to another item.
      *
+     * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
      *
-     * @return \Swis\JsonApi\Client\Relations\HasOneRelation
+     * @param  class-string<TItem>  $itemClass
+     * @return \Swis\JsonApi\Client\Interfaces\OneRelationInterface<TItem>
      */
     public function hasOne(string $itemClass, ?string $name = null): OneRelationInterface
     {
@@ -48,8 +50,10 @@ protected function newHasOne(string $type): OneRelationInterface
     /**
      * Create a plural relation to another item.
      *
+     * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
      *
-     * @return \Swis\JsonApi\Client\Relations\HasManyRelation
+     * @param  class-string<TItem>  $itemClass
+     * @return \Swis\JsonApi\Client\Interfaces\ManyRelationInterface<TItem>
      */
     public function hasMany(string $itemClass, ?string $name = null): ManyRelationInterface
     {

src/Interfaces/CollectionDocumentInterface.php

@@ -4,10 +4,13 @@
 
 namespace Swis\JsonApi\Client\Interfaces;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 interface CollectionDocumentInterface extends DocumentInterface
 {
     /**
-     * @return \Swis\JsonApi\Client\Collection
+     * @return \Swis\JsonApi\Client\Collection<array-key, TItem>
      */
     public function getData();
 }

src/Interfaces/ItemDocumentInterface.php

@@ -4,10 +4,13 @@
 
 namespace Swis\JsonApi\Client\Interfaces;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 interface ItemDocumentInterface extends DocumentInterface
 {
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\ItemInterface
+     * @return TItem
      */
     public function getData();
 }

src/Interfaces/ManyRelationInterface.php

@@ -8,10 +8,20 @@
 use Swis\JsonApi\Client\Links;
 use Swis\JsonApi\Client\Meta;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 interface ManyRelationInterface
 {
+    /**
+     * @param  \Swis\JsonApi\Client\Collection<array-key, TItem>|null  $data
+     * @return static
+     */
     public function setData(?Collection $data);
 
+    /**
+     * @return \Swis\JsonApi\Client\Collection<array-key, TItem>|null
+     */
     public function getData(): ?Collection;
 
     public function hasData(): bool;
@@ -23,6 +33,7 @@ public function getIncluded(): Collection;
     public function hasIncluded(): bool;
 
     /**
+     * @param  \Swis\JsonApi\Client\Collection<array-key, TItem>  $included
      * @return static
      */
     public function associate(Collection $included);

src/Interfaces/OneRelationInterface.php

@@ -7,21 +7,38 @@
 use Swis\JsonApi\Client\Links;
 use Swis\JsonApi\Client\Meta;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 interface OneRelationInterface
 {
+    /**
+     * @param  TItem|null  $data
+     * @return static
+     */
     public function setData(?ItemInterface $data);
 
+    /**
+     * @return TItem|null
+     */
     public function getData(): ?ItemInterface;
 
     public function hasData(): bool;
 
+    /**
+     * @param  TItem|null  $included
+     */
     public function setIncluded(?ItemInterface $included);
 
+    /**
+     * @return TItem|null
+     */
     public function getIncluded(): ?ItemInterface;
 
     public function hasIncluded(): bool;
 
     /**
+     * @param  TItem  $included
      * @return static
      */
     public function associate(ItemInterface $included);
@@ -31,6 +48,9 @@ public function associate(ItemInterface $included);
      */
     public function dissociate();
 
+    /**
+     * @return TItem|null
+     */
     public function getAssociated(): ?ItemInterface;
 
     public function hasAssociated(): bool;

src/Interfaces/RepositoryInterface.php

@@ -4,20 +4,23 @@
 
 namespace Swis\JsonApi\Client\Interfaces;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 interface RepositoryInterface
 {
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\CollectionDocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\CollectionDocumentInterface<TItem>
      */
     public function all();
 
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface<TItem>
      */
     public function find(string $id);
 
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface<TItem>
      */
     public function save(ItemInterface $item);