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 <[email protected]>

---------

Co-authored-by: Markus Podar <[email protected]>

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 @@ return [
     */
     '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 @@ class ModelsCommand extends Command
                                         $model,
                                         $collectionClass
                                     );
+                                    $collectionTypeHint = $this->getCollectionTypeHint($collectionClassNameInModel, $relatedModel);
                                     $this->setProperty(
                                         $method,
-                                        $collectionClassNameInModel . '|' . $relatedModel . '[]',
+                                        $collectionTypeHint,
                                         true,
                                         null,
                                         $comment
@@ -1080,6 +1081,23 @@ class ModelsCommand extends Command
         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 @@ class ModelsCommand extends Command
         if ($collectionClass !== '\\' . \Illuminate\Database\Eloquent\Collection::class) {
             $collectionClassInModel = $this->getClassNameInDestinationFile($model, $collectionClass);
 
-            $this->setMethod('get', $collectionClassInModel . '|static[]', ['$columns = [\'*\']']);
+            $collectionTypeHint = $this->getCollectionTypeHint($collectionClassInModel, 'static');
-            $this->setMethod('all', $collectionClassInModel . '|static[]', ['$columns = [\'*\']']);
+            $this->setMethod('get', $collectionTypeHint, ['$columns = [\'*\']']);
+            $this->setMethod('all', $collectionTypeHint, ['$columns = [\'*\']']);
         }
     }
 

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

@@ -21,7 +21,7 @@ use Illuminate\Database\Eloquent\Relations\MorphTo;
  * 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 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
  * 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<int, static> all($columns = ['*'])
- * @method static SimpleCollection|static[] get($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 @@ use Illuminate\Database\Eloquent\Relations\HasOne;
 /**
  * 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 @@ use Illuminate\Database\Eloquent\SoftDeletes;
  * @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 @@ use Illuminate\Support\Carbon;
  * @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);
+    }
+}

tests/Console/ModelsCommand/GenericsSyntaxDisabled/Test.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\GenericsSyntaxDisabled;
+
+use Barryvdh\LaravelIdeHelper\Console\ModelsCommand;
+use Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\AbstractModelsCommand;
+
+class Test extends AbstractModelsCommand
+{
+    protected function getEnvironmentSetUp($app)
+    {
+        parent::getEnvironmentSetUp($app);
+
+        $app['config']->set('ide-helper.use_generics_annotations', false);
+    }
+
+    public function test(): void
+    {
+        $command = $this->app->make(ModelsCommand::class);
+
+        $tester = $this->runCommand($command, [
+            '--write' => true,
+        ]);
+
+        $this->assertSame(0, $tester->getStatusCode());
+        $this->assertStringContainsString('Written new phpDocBlock to', $tester->getDisplay());
+        $this->assertMatchesMockedSnapshot();
+    }
+}

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

@@ -0,0 +1,37 @@
+<?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;
+
+/**
+ * Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\GenericsSyntaxDisabled\Models\Simple
+ *
+ * @property integer $id
+ * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $regularBelongsToMany
+ * @property-read int|null $regular_belongs_to_many_count
+ * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $regularHasMany
+ * @property-read int|null $regular_has_many_count
+ * @method static \Illuminate\Database\Eloquent\Builder|Simple newModelQuery()
+ * @method static \Illuminate\Database\Eloquent\Builder|Simple newQuery()
+ * @method static \Illuminate\Database\Eloquent\Builder|Simple query()
+ * @method static \Illuminate\Database\Eloquent\Builder|Simple whereId($value)
+ * @mixin \Eloquent
+ */
+class Simple extends Model
+{
+    // Regular relations
+    public function regularHasMany(): HasMany
+    {
+        return $this->hasMany(Simple::class);
+    }
+
+    public function regularBelongsToMany(): BelongsToMany
+    {
+        return $this->belongsToMany(Simple::class);
+    }
+}

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

@@ -83,7 +83,7 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
  * @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|Post[] $relationHasMany
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Post> $relationHasMany
  * @method static \Illuminate\Database\Eloquent\Builder|Post newModelQuery()
  * @method static \Illuminate\Database\Eloquent\Builder|Post newQuery()
  * @method static \Illuminate\Database\Eloquent\Builder|Post query()

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

@@ -75,27 +75,27 @@ use Illuminate\Database\Eloquent\Relations\MorphToMany;
  * @property integer $id
  * @property-read Simple|null $relationBelongsTo
  * @property-read AnotherModel|null $relationBelongsToInAnotherNamespace
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationBelongsToMany
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationBelongsToMany
  * @property-read int|null $relation_belongs_to_many_count
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationBelongsToManyWithSub
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationBelongsToManyWithSub
  * @property-read int|null $relation_belongs_to_many_with_sub_count
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationBelongsToManyWithSubAnother
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationBelongsToManyWithSubAnother
  * @property-read int|null $relation_belongs_to_many_with_sub_another_count
  * @property-read AnotherModel|null $relationBelongsToSameNameAsColumn
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationHasMany
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationHasMany
  * @property-read int|null $relation_has_many_count
  * @property-read Simple|null $relationHasOne
  * @property-read Simple $relationHasOneWithDefault
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationMorphMany
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationMorphMany
  * @property-read int|null $relation_morph_many_count
  * @property-read Simple|null $relationMorphOne
  * @property-read Model|\Eloquent $relationMorphTo
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationMorphedByMany
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationMorphedByMany
  * @property-read int|null $relation_morphed_by_many_count
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationSampleRelationType
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationSampleRelationType
  * @property-read int|null $relation_sample_relation_type_count
  * @property-read Model|\Eloquent $relationSampleToAnyMorphedRelationType
- * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationSampleToAnyRelationType
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, Simple> $relationSampleToAnyRelationType
  * @property-read int|null $relation_sample_to_any_relation_type_count
  * @property-read Simple $relationSampleToManyRelationType
  * @method static \Illuminate\Database\Eloquent\Builder|Simple newModelQuery()

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

@@ -12,7 +12,7 @@ use Illuminate\Database\Query\Builder;
  * Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\UnionTypes\Models\UnionTypeModel
  *
  * @property-read string|int|null $foo
- * @property-read \Illuminate\Database\Eloquent\Collection|UnionTypeModel[] $withUnionTypeReturn
+ * @property-read \Illuminate\Database\Eloquent\Collection<int, UnionTypeModel> $withUnionTypeReturn
  * @property-read int|null $with_union_type_return_count
  * @method static \Illuminate\Database\Eloquent\Builder|UnionTypeModel newModelQuery()
  * @method static \Illuminate\Database\Eloquent\Builder|UnionTypeModel newQuery()