Add support for generics

.github/workflows/static-analysis.yml

@@ -0,0 +1,26 @@
+name: Run static analysis
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  types:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.3
+          tools: composer:v2
+          coverage: none
+
+      - name: Install dependencies
+        run: composer update --prefer-stable --prefer-dist --no-interaction --no-progress
+
+      - name: Execute type checking
+        run: vendor/bin/phpstan --configuration="phpstan.types.neon.dist" --no-progress

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
+
+/** @extends \Swis\JsonApi\Client\Repository<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
 

composer.json

@@ -18,6 +18,7 @@
         "guzzlehttp/guzzle": "^7.3",
         "laravel/pint": "^1.5",
         "php-http/mock-client": "^1.2",
+        "phpstan/phpstan": "^2.1",
         "phpunit/phpunit": "^9.5"
     },
     "suggest": {
@@ -36,10 +37,6 @@
     },
     "license": "MIT",
     "authors": [
-        {
-            "name": "Hendrik Nijmeijer",
-            "email": "[email protected]"
-        },
         {
             "name": "Jasper Zonneveld",
             "email": "[email protected]",
@@ -52,9 +49,10 @@
         }
     ],
     "scripts": {
-        "test": "phpunit",
         "check-style": "pint --test",
-        "fix-style": "pint"
+        "check-types": "phpstan --configuration=\"phpstan.types.neon.dist\"",
+        "fix-style": "pint",
+        "test": "phpunit"
     },
     "extra": {
         "branch-alias": {

phpstan.types.neon.dist

@@ -0,0 +1,5 @@
+parameters:
+  level: max
+  paths:
+    - tests\_mocks
+    - types

src/Actions/Create.php

@@ -6,10 +6,13 @@
 
 use Swis\JsonApi\Client\Interfaces\ItemInterface;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 trait Create
 {
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\DocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface<TItem>
      */
     public function create(ItemInterface $item, array $parameters = [], array $headers = [])
     {

src/Actions/FetchMany.php

@@ -4,10 +4,13 @@
 
 namespace Swis\JsonApi\Client\Actions;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 trait FetchMany
 {
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\DocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\CollectionDocumentInterface<TItem>
      */
     public function all(array $parameters = [], array $headers = [])
     {

src/Actions/FetchOne.php

@@ -4,10 +4,13 @@
 
 namespace Swis\JsonApi\Client\Actions;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 trait FetchOne
 {
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\DocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface<TItem>
      */
     public function find(string $id, array $parameters = [], array $headers = [])
     {

src/Actions/Save.php

@@ -6,13 +6,19 @@
 
 use Swis\JsonApi\Client\Interfaces\ItemInterface;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 trait Save
 {
+    /** @use Create<TItem> */
     use Create { create as protected saveNew; }
+
+    /** @use Update<TItem> */
     use Update { update as protected saveExisting; }
 
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\DocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface<TItem>
      */
     public function save(ItemInterface $item, array $parameters = [], array $headers = [])
     {

src/Actions/TakeOne.php

@@ -4,10 +4,13 @@
 
 namespace Swis\JsonApi\Client\Actions;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 trait TakeOne
 {
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\DocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface<TItem>
      */
     public function take(array $parameters = [], array $headers = [])
     {

src/Actions/Update.php

@@ -6,10 +6,13 @@
 
 use Swis\JsonApi\Client\Interfaces\ItemInterface;
 
+/**
+ * @template TItem of \Swis\JsonApi\Client\Interfaces\ItemInterface
+ */
 trait Update
 {
     /**
-     * @return \Swis\JsonApi\Client\Interfaces\DocumentInterface
+     * @return \Swis\JsonApi\Client\Interfaces\ItemDocumentInterface<TItem>
      */
     public function update(ItemInterface $item, array $parameters = [], array $headers = [])
     {

src/Collection.php

@@ -6,6 +6,12 @@
 
 use Swis\JsonApi\Client\Interfaces\DataInterface;
 
+/**
+ * @template TKey of int
+ * @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<int, 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<int, TItem>|null  $data
+     * @return static
+     */
     public function setData(?Collection $data);
 
+    /**
+     * @return \Swis\JsonApi\Client\Collection<int, 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<int, 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);