Generics annotations support (#1298)

* option to use generics syntax, default to yes in laravel 9

* rename `use_generics_syntax` to `use_generics_annotations`

* update readme and changelog

* remove laravel 9 default override

* include key type in generics annotations

* readme rewording

* set `use_generics_annotations` to `true` by default

* update tests to reflect `use_generics_annotations` being set to `true` by default

* default `use_generics_annotations` setting to true when not set in config

Co-authored-by: Markus Podar <markus@fischer.name>

---------

Co-authored-by: Markus Podar <markus@fischer.name>

Author: tanerkay

CHANGELOG.md

@@ -14,6 +14,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 - Add support for custom casts that implement `CastsInboundAttributes` [#1329 / sforward](https://github.com/barryvdh/laravel-ide-helper/pull/1329)
+- Add option `use_generics_annotations` for collection type hints [#1298 / tanerkay](https://github.com/barryvdh/laravel-ide-helper/pull/1298)
 
 2022-03-06, 2.12.3
 ------------------

README.md

@@ -227,6 +227,12 @@ You may use the [`::withCount`](https://laravel.com/docs/master/eloquent-relatio
 
 By default, these attributes are generated in the phpdoc. You can turn them off by setting the config `write_model_relation_count_properties` to `false`.
 
+#### Generics annotations
+
+Laravel 9 introduced generics annotations in DocBlocks for collections. PhpStorm 2022.3 and above support the use of generics annotations within `@property` and `@property-read` declarations in DocBlocks, e.g. `Collection<User>` instead of `Collection|User[]`.
+
+These can be disabled by setting the config `use_generics_annotations` to `false`.
+
 #### Support `@comment` based on DocBlock
 
 In order to better support IDEs, relations and getters/setters can also add a comment to a property like table columns. Therefore a custom docblock `@comment` is used:

config/ide-helper.php

@@ -292,6 +292,17 @@
     */
     'force_fqn' => false,
 
+    /*
+    |--------------------------------------------------------------------------
+    | Use generics syntax
+    |--------------------------------------------------------------------------
+    |
+    | Use generics syntax within DocBlocks,
+    | e.g. `Collection<User>` instead of `Collection|User[]`.
+    |
+    */
+    'use_generics_annotations' => true,
+
     /*
     |--------------------------------------------------------------------------
     | Additional relation types

src/Console/ModelsCommand.php

@@ -713,9 +713,10 @@ public function getPropertiesFromMethods($model)
                                         $model,
                                         $collectionClass
                                     );
+                                    $collectionTypeHint = $this->getCollectionTypeHint($collectionClassNameInModel, $relatedModel);
                                     $this->setProperty(
                                         $method,
-                                        $collectionClassNameInModel . '|' . $relatedModel . '[]',
+                                        $collectionTypeHint,
                                         true,
                                         null,
                                         $comment
@@ -1080,6 +1081,23 @@ protected function getCollectionClass($className)
         return '\\' . get_class($model->newCollection());
     }
 
+    /**
+     * Determine a model classes' collection type hint.
+     *
+     * @param string $collectionClassNameInModel
+     * @param string $relatedModel
+     * @return string
+     */
+    protected function getCollectionTypeHint(string $collectionClassNameInModel, string $relatedModel): string
+    {
+        $useGenericsSyntax = $this->laravel['config']->get('ide-helper.use_generics_annotations', true);
+        if ($useGenericsSyntax) {
+            return $collectionClassNameInModel . '<int, ' . $relatedModel . '>';
+        } else {
+            return $collectionClassNameInModel . '|' . $relatedModel . '[]';
+        }
+    }
+
     /**
      * Returns the available relation types
      */
@@ -1277,8 +1295,9 @@ protected function getCollectionMethods($model)
         if ($collectionClass !== '\\' . \Illuminate\Database\Eloquent\Collection::class) {
             $collectionClassInModel = $this->getClassNameInDestinationFile($model, $collectionClass);
 
-            $this->setMethod('get', $collectionClassInModel . '|static[]', ['$columns = [\'*\']']);
-            $this->setMethod('all', $collectionClassInModel . '|static[]', ['$columns = [\'*\']']);
+            $collectionTypeHint = $this->getCollectionTypeHint($collectionClassInModel, 'static');
+            $this->setMethod('get', $collectionTypeHint, ['$columns = [\'*\']']);
+            $this->setMethod('all', $collectionTypeHint, ['$columns = [\'*\']']);
         }
     }
 

tests/Console/ModelsCommand/Comment/__snapshots__/Test__test__1.php

@@ -21,7 +21,7 @@
  * This is second line, success too.
  * @property-read string $many_format_comment There is format comment, success.
  * @property-read string $not_comment
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationHasMany HasMany relations.
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationHasMany HasMany relations.
  * @property-read int|null $relation_has_many_count
  * @property-read Simple|null $relationHasOne Others relations.
  * @property-read Model|\Eloquent $relationMorphTo MorphTo relations.

tests/Console/ModelsCommand/CustomCollection/__snapshots__/Test__test__1.php

@@ -12,10 +12,10 @@
  * Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\CustomCollection\Models\Simple
  *
  * @property integer $id
- * @property-read SimpleCollection|Simple[] $relationHasMany
+ * @property-read SimpleCollection<int, Simple> $relationHasMany
  * @property-read int|null $relation_has_many_count
- * @method static SimpleCollection|static[] all($columns = ['*'])
- * @method static SimpleCollection|static[] get($columns = ['*'])
+ * @method static SimpleCollection<int, static> all($columns = ['*'])
+ * @method static SimpleCollection<int, static> get($columns = ['*'])
  * @method static \Illuminate\Database\Eloquent\Builder|Simple newModelQuery()
  * @method static \Illuminate\Database\Eloquent\Builder|Simple newQuery()
  * @method static \Illuminate\Database\Eloquent\Builder|Simple query()

tests/Console/ModelsCommand/DynamicRelations/__snapshots__/Test__test__1.php

@@ -12,7 +12,7 @@
 /**
  * Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\DynamicRelations\Models\Dynamic
  *
- * @property-read \Illuminate\Database\Eloquent\Collection|Dynamic[] $regularHasMany
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Dynamic> $regularHasMany
  * @property-read int|null $regular_has_many_count
  * @method static \Illuminate\Database\Eloquent\Builder|Dynamic newModelQuery()
  * @method static \Illuminate\Database\Eloquent\Builder|Dynamic newQuery()

tests/Console/ModelsCommand/GeneratePhpdocWithForcedFqn/__snapshots__/Test__test__1.php

@@ -84,7 +84,7 @@
  * @property string $macaddress_not_nullable
  * @property \Illuminate\Support\Carbon|null $created_at
  * @property \Illuminate\Support\Carbon|null $updated_at
- * @property-read \Illuminate\Database\Eloquent\Collection|\Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\GeneratePhpdocWithForcedFqn\Models\Post[] $posts
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, \Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\GeneratePhpdocWithForcedFqn\Models\Post> $posts
  * @property-read int|null $posts_count
  * @method static \Illuminate\Database\Eloquent\Builder|\Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\GeneratePhpdocWithForcedFqn\Models\Post newModelQuery()
  * @method static \Illuminate\Database\Eloquent\Builder|\Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\GeneratePhpdocWithForcedFqn\Models\Post newQuery()

tests/Console/ModelsCommand/GeneratePhpdocWithFqn/__snapshots__/Test__test__1.php

@@ -90,7 +90,7 @@
  * @property string $macaddress_not_nullable
  * @property Carbon|null $created_at
  * @property Carbon|null $updated_at
- * @property-read Collection|Post[] $posts
+ * @property-read Collection<int, Post> $posts
  * @property-read int|null $posts_count
  * @method static EloquentBuilder|Post newModelQuery()
  * @method static EloquentBuilder|Post newQuery()

tests/Console/ModelsCommand/GenericsSyntaxDisabled/Models/Simple.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\GenericsSyntaxDisabled\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class Simple extends Model
+{
+    // Regular relations
+    public function regularHasMany(): HasMany
+    {
+        return $this->hasMany(Simple::class);
+    }
+
+    public function regularBelongsToMany(): BelongsToMany
+    {
+        return $this->belongsToMany(Simple::class);
+    }
+}