feat: add separation of tags into groups

CHANGELOG.md

@@ -14,6 +14,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 - Add support for `immutable_date:*` and `immutable_datetime:*` casts. [#1380 / thekonz](https://github.com/barryvdh/laravel-ide-helper/pull/1380)
+- Added separation of phpdoc tags into groups [#1377 / Kerigard](https://github.com/barryvdh/laravel-ide-helper/pull/1377)
 
 2023-02-04, 2.13.0
 ------------------

README.md

@@ -263,6 +263,33 @@ add support for creating a new dedicated class instead of using local scopes in
 
 If for some reason it's undesired to have them generated (one for each column), you can disable this via config `write_model_external_builder_methods` and setting it to `false`.
 
+#### Separating docblock tags into groups
+
+By default, all docblock tags are written sequentially on each line. Problems can arise when using Laravel Pint or other linters because they use different formatting.
+
+Change the `phpdoc_separate_tags` setting in the config to `true` to fix this behavior.
+
+```php
+// => before
+
+/**
+ * @property integer $id
+ * @property-write mixed $first_name Set the user's first name.
+ * @method static \Illuminate\Database\Eloquent\Builder|Post newQuery()
+ * @method static \Illuminate\Database\Eloquent\Builder|Post query()
+ */
+
+// => after
+
+/**
+ * @property integer $id
+ * @property-write mixed $first_name Set the user's first name.
+ *
+ * @method static \Illuminate\Database\Eloquent\Builder|Post newQuery()
+ * @method static \Illuminate\Database\Eloquent\Builder|Post query()
+ */
+```
+
 #### Unsupported or custom database types
 
 Common column types (e.g. varchar, integer) are correctly mapped to PHP types (`string`, `int`).

composer.json

@@ -22,7 +22,7 @@
  "require": {
  "php": "^7.3 || ^8.0",
  "ext-json": "*",
- "barryvdh/reflection-docblock": "^2.0.6",
+ "barryvdh/reflection-docblock": "^2.1.0",
  "composer/class-map-generator": "^1.0",
  "doctrine/dbal": "^2.6 || ^3",
  "illuminate/console": "^8 || ^9 || ^10",

config/ide-helper.php

@@ -109,6 +109,17 @@
 
  'write_eloquent_model_mixins' => false,
 
+ /*
+ |--------------------------------------------------------------------------
+ | PHPDOC: Separate Tag Groups
+ |--------------------------------------------------------------------------
+ |
+ | Set to true to separate tags into groups with an empty string.
+ |
+ */
+
+ 'phpdoc_separate_tags' => false,
+
  /*
  |--------------------------------------------------------------------------
  | Helper files to include

src/Alias.php

@@ -421,7 +421,8 @@ protected function getMacroFunction($macro_func)
  */
  public function getDocComment($prefix = "\t\t")
  {
- $serializer = new DocBlockSerializer(1, $prefix);
+ $separateTags = $this->config->get('ide-helper.phpdoc_separate_tags', false);
+ $serializer = new DocBlockSerializer(1, $prefix, true, null, $separateTags);
 
  if (!$this->phpdoc) {
  return '';

src/Console/ModelsCommand.php

@@ -106,6 +106,8 @@ class ModelsCommand extends Command
  protected $keep_text;
  protected $phpstorm_noinspections;
  protected $write_model_external_builder_methods;
+ protected $phpdoc_separate_tags = false;
+
  /**
  * @var bool[string]
  */
@@ -158,6 +160,7 @@ public function handle()
  $this->write_model_external_builder_methods = $this->laravel['config']->get('ide-helper.write_model_external_builder_methods', true);
  $this->write_model_relation_count_properties =
  $this->laravel['config']->get('ide-helper.write_model_relation_count_properties', true);
+ $this->phpdoc_separate_tags = $this->laravel['config']->get('ide-helper.phpdoc_separate_tags', false);
 
  $this->write = $this->write_mixin ? true : $this->write;
  //If filename is default and Write is not specified, ask what to do
@@ -1008,7 +1011,7 @@ protected function createPhpDocs($class)
  );
  }
 
- $serializer = new DocBlockSerializer();
+ $serializer = new DocBlockSerializer(0, ' ', true, null, $this->phpdoc_separate_tags);
  $docComment = $serializer->getDocComment($phpdoc);
 
  if ($this->write_mixin) {

src/Eloquent.php

@@ -70,7 +70,8 @@ public static function writeEloquentModelHelper(Command $command, Filesystem $fi
  return;
  }
 
- $serializer = new DocBlockSerializer();
+ $separateTags = $command->getLaravel()['config']->get('ide-helper.phpdoc_separate_tags', false);
+ $serializer = new DocBlockSerializer(0, ' ', true, null, $separateTags);
  $serializer->getDocComment($phpdoc);
  $docComment = $serializer->getDocComment($phpdoc);
 

src/Method.php

@@ -145,7 +145,7 @@ public function getRootMethodCall()
  */
  public function getDocComment($prefix = "\t\t")
  {
- $serializer = new DocBlockSerializer(1, $prefix);
+ $serializer = new DocBlockSerializer(1, $prefix, true, null, config('ide-helper.phpdoc_separate_tags', false));
  return $serializer->getDocComment($this->phpdoc);
  }
 

tests/Console/ModelsCommand/SeparateTags/Models/Post.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\SeparateTags\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class Post extends Model
+{
+ /**
+ * @comment Set the user's first name.
+ * @param $value
+ */
+ public function setFirstNameAttribute($value)
+ {
+ }
+
+ public function posts(): HasMany
+ {
+ return $this->hasMany(Post::class);
+ }
+}

tests/Console/ModelsCommand/SeparateTags/Test.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\SeparateTags;
+
+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.phpdoc_separate_tags', true);
+ }
+
+ 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/SeparateTags/__snapshots__/Test__test__1.php

@@ -0,0 +1,183 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\SeparateTags\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * Barryvdh\LaravelIdeHelper\Tests\Console\ModelsCommand\SeparateTags\Models\Post
+ *
+ * @property integer $id
+ * @property string|null $char_nullable
+ * @property string $char_not_nullable
+ * @property string|null $string_nullable
+ * @property string $string_not_nullable
+ * @property string|null $text_nullable
+ * @property string $text_not_nullable
+ * @property string|null $medium_text_nullable
+ * @property string $medium_text_not_nullable
+ * @property string|null $long_text_nullable
+ * @property string $long_text_not_nullable
+ * @property integer|null $integer_nullable
+ * @property integer $integer_not_nullable
+ * @property integer|null $tiny_integer_nullable
+ * @property integer $tiny_integer_not_nullable
+ * @property integer|null $small_integer_nullable
+ * @property integer $small_integer_not_nullable
+ * @property integer|null $medium_integer_nullable
+ * @property integer $medium_integer_not_nullable
+ * @property integer|null $big_integer_nullable
+ * @property integer $big_integer_not_nullable
+ * @property integer|null $unsigned_integer_nullable
+ * @property integer $unsigned_integer_not_nullable
+ * @property integer|null $unsigned_tiny_integer_nullable
+ * @property integer $unsigned_tiny_integer_not_nullable
+ * @property integer|null $unsigned_small_integer_nullable
+ * @property integer $unsigned_small_integer_not_nullable
+ * @property integer|null $unsigned_medium_integer_nullable
+ * @property integer $unsigned_medium_integer_not_nullable
+ * @property integer|null $unsigned_big_integer_nullable
+ * @property integer $unsigned_big_integer_not_nullable
+ * @property float|null $float_nullable
+ * @property float $float_not_nullable
+ * @property float|null $double_nullable
+ * @property float $double_not_nullable
+ * @property string|null $decimal_nullable
+ * @property string $decimal_not_nullable
+ * @property string|null $unsigned_decimal_nullable
+ * @property string $unsigned_decimal_not_nullable
+ * @property integer|null $boolean_nullable
+ * @property integer $boolean_not_nullable
+ * @property string|null $enum_nullable
+ * @property string $enum_not_nullable
+ * @property string|null $json_nullable
+ * @property string $json_not_nullable
+ * @property string|null $jsonb_nullable
+ * @property string $jsonb_not_nullable
+ * @property string|null $date_nullable
+ * @property string $date_not_nullable
+ * @property string|null $datetime_nullable
+ * @property string $datetime_not_nullable
+ * @property string|null $datetimetz_nullable
+ * @property string $datetimetz_not_nullable
+ * @property string|null $time_nullable
+ * @property string $time_not_nullable
+ * @property string|null $timetz_nullable
+ * @property string $timetz_not_nullable
+ * @property string|null $timestamp_nullable
+ * @property string $timestamp_not_nullable
+ * @property string|null $timestamptz_nullable
+ * @property string $timestamptz_not_nullable
+ * @property integer|null $year_nullable
+ * @property integer $year_not_nullable
+ * @property mixed|null $binary_nullable
+ * @property mixed $binary_not_nullable
+ * @property string|null $uuid_nullable
+ * @property string $uuid_not_nullable
+ * @property string|null $ipaddress_nullable
+ * @property string $ipaddress_not_nullable
+ * @property string|null $macaddress_nullable
+ * @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<int, Post> $posts
+ * @property-read int|null $posts_count
+ * @property-write mixed $first_name Set the user's first name.
+ *
+ * @method static \Illuminate\Database\Eloquent\Builder|Post newModelQuery()
+ * @method static \Illuminate\Database\Eloquent\Builder|Post newQuery()
+ * @method static \Illuminate\Database\Eloquent\Builder|Post query()
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereBigIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereBigIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereBinaryNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereBinaryNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereBooleanNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereBooleanNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereCharNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereCharNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereCreatedAt($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDateNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDateNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDatetimeNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDatetimeNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDatetimetzNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDatetimetzNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDecimalNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDecimalNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDoubleNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereDoubleNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereEnumNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereEnumNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereFloatNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereFloatNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereId($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereIpaddressNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereIpaddressNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereJsonNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereJsonNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereJsonbNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereJsonbNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereLongTextNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereLongTextNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereMacaddressNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereMacaddressNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereMediumIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereMediumIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereMediumTextNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereMediumTextNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereSmallIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereSmallIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereStringNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereStringNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTextNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTextNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTimeNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTimeNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTimestampNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTimestampNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTimestamptzNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTimestamptzNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTimetzNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTimetzNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTinyIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereTinyIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedBigIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedBigIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedDecimalNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedDecimalNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedMediumIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedMediumIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedSmallIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedSmallIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedTinyIntegerNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUnsignedTinyIntegerNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUpdatedAt($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUuidNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereUuidNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereYearNotNullable($value)
+ * @method static \Illuminate\Database\Eloquent\Builder|Post whereYearNullable($value)
+ *
+ * @mixin \Eloquent
+ */
+class Post extends Model
+{
+ /**
+ * @comment Set the user's first name.
+ * @param $value
+ */
+ public function setFirstNameAttribute($value)
+ {
+ }
+
+ public function posts(): HasMany
+ {
+ return $this->hasMany(Post::class);
+ }
+}