diff --git a/CHANGELOG.md b/CHANGELOG.md index d670d08..aa025f3 100644 --- a/CHANGELOG.md +++ b/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 ------------------ diff --git a/README.md b/README.md index 4888900..d2ae4db 100644 --- a/README.md +++ b/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` 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: diff --git a/config/ide-helper.php b/config/ide-helper.php index f9110aa..80afdb2 100644 --- a/config/ide-helper.php +++ b/config/ide-helper.php @@ -292,6 +292,17 @@ return [ */ 'force_fqn' => false, + /* + |-------------------------------------------------------------------------- + | Use generics syntax + |-------------------------------------------------------------------------- + | + | Use generics syntax within DocBlocks, + | e.g. `Collection` instead of `Collection|User[]`. + | + */ + 'use_generics_annotations' => true, + /* |-------------------------------------------------------------------------- | Additional relation types diff --git a/src/Console/ModelsCommand.php b/src/Console/ModelsCommand.php index 6f75bcc..30249d4 100644 --- a/src/Console/ModelsCommand.php +++ b/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 . ''; + } 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 = [\'*\']']); - $this->setMethod('all', $collectionClassInModel . '|static[]', ['$columns = [\'*\']']); + $collectionTypeHint = $this->getCollectionTypeHint($collectionClassInModel, 'static'); + $this->setMethod('get', $collectionTypeHint, ['$columns = [\'*\']']); + $this->setMethod('all', $collectionTypeHint, ['$columns = [\'*\']']); } } diff --git a/tests/Console/ModelsCommand/Comment/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/Comment/__snapshots__/Test__test__1.php index 4f530e2..c3c9686 100644 --- a/tests/Console/ModelsCommand/Comment/__snapshots__/Test__test__1.php +++ b/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 $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. diff --git a/tests/Console/ModelsCommand/CustomCollection/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/CustomCollection/__snapshots__/Test__test__1.php index 10818ac..0b10768 100644 --- a/tests/Console/ModelsCommand/CustomCollection/__snapshots__/Test__test__1.php +++ b/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 $relationHasMany * @property-read int|null $relation_has_many_count - * @method static SimpleCollection|static[] all($columns = ['*']) - * @method static SimpleCollection|static[] get($columns = ['*']) + * @method static SimpleCollection all($columns = ['*']) + * @method static SimpleCollection 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() diff --git a/tests/Console/ModelsCommand/DynamicRelations/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/DynamicRelations/__snapshots__/Test__test__1.php index b92e1cf..07a8447 100644 --- a/tests/Console/ModelsCommand/DynamicRelations/__snapshots__/Test__test__1.php +++ b/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 $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() diff --git a/tests/Console/ModelsCommand/GeneratePhpdocWithForcedFqn/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/GeneratePhpdocWithForcedFqn/__snapshots__/Test__test__1.php index a96e024..20b2628 100644 --- a/tests/Console/ModelsCommand/GeneratePhpdocWithForcedFqn/__snapshots__/Test__test__1.php +++ b/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 $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() diff --git a/tests/Console/ModelsCommand/GeneratePhpdocWithFqn/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/GeneratePhpdocWithFqn/__snapshots__/Test__test__1.php index 6a5ff8a..989fd8a 100644 --- a/tests/Console/ModelsCommand/GeneratePhpdocWithFqn/__snapshots__/Test__test__1.php +++ b/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 $posts * @property-read int|null $posts_count * @method static EloquentBuilder|Post newModelQuery() * @method static EloquentBuilder|Post newQuery() diff --git a/tests/Console/ModelsCommand/GenericsSyntaxDisabled/Models/Simple.php b/tests/Console/ModelsCommand/GenericsSyntaxDisabled/Models/Simple.php new file mode 100644 index 0000000..3394bce --- /dev/null +++ b/tests/Console/ModelsCommand/GenericsSyntaxDisabled/Models/Simple.php @@ -0,0 +1,23 @@ +hasMany(Simple::class); + } + + public function regularBelongsToMany(): BelongsToMany + { + return $this->belongsToMany(Simple::class); + } +} diff --git a/tests/Console/ModelsCommand/GenericsSyntaxDisabled/Test.php b/tests/Console/ModelsCommand/GenericsSyntaxDisabled/Test.php new file mode 100644 index 0000000..dd1b412 --- /dev/null +++ b/tests/Console/ModelsCommand/GenericsSyntaxDisabled/Test.php @@ -0,0 +1,31 @@ +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(); + } +} diff --git a/tests/Console/ModelsCommand/GenericsSyntaxDisabled/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/GenericsSyntaxDisabled/__snapshots__/Test__test__1.php new file mode 100644 index 0000000..99c20c0 --- /dev/null +++ b/tests/Console/ModelsCommand/GenericsSyntaxDisabled/__snapshots__/Test__test__1.php @@ -0,0 +1,37 @@ +hasMany(Simple::class); + } + + public function regularBelongsToMany(): BelongsToMany + { + return $this->belongsToMany(Simple::class); + } +} diff --git a/tests/Console/ModelsCommand/RelationCountProperties/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/RelationCountProperties/__snapshots__/Test__test__1.php index a108282..5e2a131 100644 --- a/tests/Console/ModelsCommand/RelationCountProperties/__snapshots__/Test__test__1.php +++ b/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 $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() diff --git a/tests/Console/ModelsCommand/Relations/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/Relations/__snapshots__/Test__test__1.php index acd6be5..863b180 100644 --- a/tests/Console/ModelsCommand/Relations/__snapshots__/Test__test__1.php +++ b/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 $relationBelongsToMany * @property-read int|null $relation_belongs_to_many_count - * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationBelongsToManyWithSub + * @property-read \Illuminate\Database\Eloquent\Collection $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 $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 $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 $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 $relationMorphedByMany * @property-read int|null $relation_morphed_by_many_count - * @property-read \Illuminate\Database\Eloquent\Collection|Simple[] $relationSampleRelationType + * @property-read \Illuminate\Database\Eloquent\Collection $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 $relationSampleToAnyRelationType * @property-read int|null $relation_sample_to_any_relation_type_count * @property-read Simple $relationSampleToManyRelationType * @method static \Illuminate\Database\Eloquent\Builder|Simple newModelQuery() diff --git a/tests/Console/ModelsCommand/UnionTypes/__snapshots__/Test__test__1.php b/tests/Console/ModelsCommand/UnionTypes/__snapshots__/Test__test__1.php index 8f62164..67f759e 100644 --- a/tests/Console/ModelsCommand/UnionTypes/__snapshots__/Test__test__1.php +++ b/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 $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()