Add option to generate larastan-friendly doc blocks for models

Soyhuce · Jul 16, 2020 · bb1f243 · bb1f243
1 parent 7f28242
commit bb1f243
Show file tree

Hide file tree

Showing 9 changed files with 225 additions and 8 deletions.
diff --git a/assets/config.php b/assets/config.php
@@ -34,6 +34,11 @@
          * - Soyhuce\NextIdeHelper\Domain\Models\Extensions\VirtualAttributeResolver
          */
         'extensions' => [],
+
+        /**
+         * Use Larastan friendly docblock when possible
+         */
+        'larastan_friendly' => false,
     ],
 
     /**

diff --git a/src/Domain/Models/Output/ModelDocBlock.php b/src/Domain/Models/Output/ModelDocBlock.php
@@ -101,7 +101,13 @@ private function queryMixin(): ?string
             return null;
         }
 
-        return " * @mixin {$this->model->queryBuilder->fqcn}";
+        $mixin = " * @mixin {$this->model->queryBuilder->fqcn}";
+
+        if (config('next-ide-helper.models.larastan_friendly', false)) {
+            $mixin .= "<{$this->model->fqcn}>";
+        }
+
+        return $mixin;
     }
 
     private function factory(): ?string

diff --git a/src/Domain/Models/Output/QueryBuilderDocBlock.php b/src/Domain/Models/Output/QueryBuilderDocBlock.php
@@ -38,7 +38,10 @@ public function docTags(): Collection
             ->merge($this->attributeScopes())
             ->merge($this->scopeMethods())
             ->merge($this->resultMethods())
-            ->merge($this->templateBlock());
+            ->when(
+                $this->larastanFriendly(),
+                fn (Collection $collection) => $collection->merge($this->templateBlock())
+            );
     }
 
     private function docblock(): string
@@ -122,8 +125,13 @@ private function resultMethods(): Collection
     private function templateBlock(): Collection
     {
         return Collection::make([
-            ' * @template TModelClass',
-            " * @extends \\Illuminate\\Database\\Eloquent\\Builder<{$this->model->fqcn}>",
+            " * @template TModelClass of {$this->model->fqcn}",
+            ' * @extends \Illuminate\Database\Eloquent\Builder<TModelClass>',
         ]);
     }
+
+    private function larastanFriendly(): bool
+    {
+        return config('next-ide-helper.models.larastan_friendly', false);
+    }
 }
diff --git a/tests/Feature/ModelsCommandTest.php b/tests/Feature/ModelsCommandTest.php
@@ -58,6 +58,43 @@ public function theCommandIsSuccessful()
         );
     }
 
+    /**
+     * @test
+     */
+    public function theCommandIsSuccessfulWithLarastanFriendlyComments()
+    {
+        config([
+            'next-ide-helper.models' => [
+                'directories' => [$this->fixturePath()],
+                'file_name' => $this->fixturePath() . '/_ide_models.php',
+                'larastan_friendly' => true,
+            ],
+        ]);
+
+        $this->artisan('next-ide-helper:models')
+            ->assertExitCode(0);
+
+        $this->assertFileEquals(
+            $this->expectedPath('PostLarastan.stub'),
+            $this->fixturePath('Blog/Post.php')
+        );
+
+        $this->assertFileEquals(
+            $this->expectedPath('User.stub'),
+            $this->fixturePath('User.php')
+        );
+
+        $this->assertFileEquals(
+            $this->expectedPath('PostQueryLarastan.stub'),
+            $this->fixturePath('Blog/PostQuery.php')
+        );
+
+        $this->assertFileEquals(
+            $this->expectedPath('_ide_modelsLarastan.stub'),
+            $this->fixturePath('_ide_models.php')
+        );
+    }
+
     protected function tearDown(): void
     {
         File::delete($this->fixturePath('_ide_models.php'));

diff --git a/tests/expected/PostLarastan.stub b/tests/expected/PostLarastan.stub
@@ -0,0 +1,45 @@
+<?php
+
+namespace Soyhuce\NextIdeHelper\Tests\Fixtures\Blog;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Support\Str;
+use Soyhuce\NextIdeHelper\Tests\Fixtures\User;
+
+/**
+ * @property int $id
+ * @property string $title
+ * @property string|null $subtitle
+ * @property string $content
+ * @property int $user_id
+ * @property \Illuminate\Support\Carbon $created_at
+ * @property \Illuminate\Support\Carbon $updated_at
+ * @property-read string $slug
+ * @property-read \Soyhuce\NextIdeHelper\Tests\Fixtures\User $user
+ * @method static \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostCollection all(array|mixed $columns = ['*'])
+ * @method static \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery query()
+ * @mixin \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery<\Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post>
+ */
+class Post extends Model
+{
+    public function newEloquentBuilder($query)
+    {
+        return new PostQuery($query);
+    }
+
+    public function newCollection(array $models = [])
+    {
+        return new PostCollection($models);
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function getSlugAttribute(): string
+    {
+        return Str::slug($this->title);
+    }
+}
diff --git a/tests/expected/PostQuery.stub b/tests/expected/PostQuery.stub
@@ -27,8 +27,6 @@ use Illuminate\Database\Eloquent\Builder;
  * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostCollection getModels(array|string $columns = ['*'])
  * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post newModelInstance(array $attributes = [])
  * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post updateOrCreate(array $attributes, array $values = [])
- * @template TModelClass
- * @extends \Illuminate\Database\Eloquent\Builder<\Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post>
  */
 class PostQuery extends Builder
 {

diff --git a/tests/expected/PostQueryLarastan.stub b/tests/expected/PostQueryLarastan.stub
@@ -0,0 +1,35 @@
+<?php
+
+namespace Soyhuce\NextIdeHelper\Tests\Fixtures\Blog;
+
+use Illuminate\Database\Eloquent\Builder;
+
+/**
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery whereId(int|string $value)
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery whereTitle(string $value)
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery whereSubtitle(string|null $value)
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery whereContent(string $value)
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery whereUserId(int|string $value)
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery whereCreatedAt(\Illuminate\Support\Carbon|string $value)
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery whereUpdatedAt(\Illuminate\Support\Carbon|string $value)
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post create(array $attributes = [])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostCollection|\Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post|null find($id, array $columns = ['*'])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostCollection findMany($id, array $columns = ['*'])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostCollection|\Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post findOrFail($id, array $columns = ['*'])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post findOrNew($id, array $columns = ['*'])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post|null first(array|string $columns = ['*'])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post firstOrCreate(array $attributes, array $values = [])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post firstOrFail(array $columns = ['*'])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post firstOrNew(array $attributes = [], array $values = [])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post forceCreate(array $attributes = [])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostCollection get(array|string $columns = ['*'])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post getModel()
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostCollection getModels(array|string $columns = ['*'])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post newModelInstance(array $attributes = [])
+ * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post updateOrCreate(array $attributes, array $values = [])
+ * @template TModelClass of \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post
+ * @extends \Illuminate\Database\Eloquent\Builder<TModelClass>
+ */
+class PostQuery extends Builder
+{
+}
diff --git a/tests/expected/_ide_models.stub b/tests/expected/_ide_models.stub
@@ -26,8 +26,6 @@ namespace IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures
      * @method \Illuminate\Database\Eloquent\Collection getModels(array|string $columns = ['*'])
      * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User newModelInstance(array $attributes = [])
      * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User updateOrCreate(array $attributes, array $values = [])
-     * @template TModelClass
-     * @extends \Illuminate\Database\Eloquent\Builder<\Soyhuce\NextIdeHelper\Tests\Fixtures\User>
      */
     class UserQuery extends \Illuminate\Database\Eloquent\Builder
     {

diff --git a/tests/expected/_ide_modelsLarastan.stub b/tests/expected/_ide_modelsLarastan.stub
@@ -0,0 +1,85 @@
+<?php
+
+namespace IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures
+{
+    /**
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery whereId(int|string $value)
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery whereEmail(string $value)
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery wherePassword(string $value)
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery whereAddress(\Soyhuce\NextIdeHelper\Tests\Fixtures\Address|string $value)
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery whereRememberToken(string|null $value)
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery whereCreatedAt(\Illuminate\Support\Carbon|string $value)
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery whereUpdatedAt(\Illuminate\Support\Carbon|string $value)
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery whereEmailDomain(string $domain, ?string $area = null)
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User create(array $attributes = [])
+     * @method \Illuminate\Database\Eloquent\Collection|\Soyhuce\NextIdeHelper\Tests\Fixtures\User|null find($id, array $columns = ['*'])
+     * @method \Illuminate\Database\Eloquent\Collection findMany($id, array $columns = ['*'])
+     * @method \Illuminate\Database\Eloquent\Collection|\Soyhuce\NextIdeHelper\Tests\Fixtures\User findOrFail($id, array $columns = ['*'])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User findOrNew($id, array $columns = ['*'])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User|null first(array|string $columns = ['*'])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User firstOrCreate(array $attributes, array $values = [])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User firstOrFail(array $columns = ['*'])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User firstOrNew(array $attributes = [], array $values = [])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User forceCreate(array $attributes = [])
+     * @method \Illuminate\Database\Eloquent\Collection get(array|string $columns = ['*'])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User getModel()
+     * @method \Illuminate\Database\Eloquent\Collection getModels(array|string $columns = ['*'])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User newModelInstance(array $attributes = [])
+     * @method \Soyhuce\NextIdeHelper\Tests\Fixtures\User updateOrCreate(array $attributes, array $values = [])
+     * @template TModelClass of \Soyhuce\NextIdeHelper\Tests\Fixtures\User
+     * @extends \Illuminate\Database\Eloquent\Builder<TModelClass>
+     */
+    class UserQuery extends \Illuminate\Database\Eloquent\Builder
+    {
+    }
+}
+
+namespace IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post
+{
+    /**
+     * @mixin \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery
+     */
+    class User extends \Illuminate\Database\Eloquent\Relations\BelongsTo
+    {
+    }
+}
+
+namespace IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\User
+{
+    /**
+     * @mixin \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery
+     */
+    class LaravelPosts extends \Illuminate\Database\Eloquent\Relations\HasMany
+    {
+    }
+
+    /**
+     * @mixin \Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\PostQuery
+     */
+    class Posts extends \Illuminate\Database\Eloquent\Relations\HasMany
+    {
+    }
+}
+
+namespace Soyhuce\NextIdeHelper\Tests\Fixtures
+{
+    /**
+     * @method static \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery query()
+     * @mixin \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\UserQuery
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\User\Posts posts()
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\User\LaravelPosts laravelPosts()
+     */
+    class User
+    {
+    }
+}
+
+namespace Soyhuce\NextIdeHelper\Tests\Fixtures\Blog
+{
+    /**
+     * @method \IdeHelper\Soyhuce\NextIdeHelper\Tests\Fixtures\Blog\Post\User user()
+     */
+    class Post
+    {
+    }
+}