Merge pull request #108 from HendrikN/feature/generic-types

Add support for generics

Author: JaZo

.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 = [])
     {