#Laravel 的 IDE Helper 生成器

完整的 PHPDocs，直接来自源代码

此包生成辅助文件，使您的 IDE 能够提供准确的自动完成功能。生成基于您项目中的文件，因此它们始终是最新的。

它支持 Laravel 8+ 和 PHP 7.3+

• 安装
• 用法
  • Laravel Facades 的自动 PHPDoc 生成
  • 模型的自动 PHPDocs
    • 模型目录
    • 忽略模型
    • 模型钩子
  • Laravel Fluent 方法的自动 PHPDocs 生成
  • 工厂构建器的自动完成
  • 容器实例的 PhpStorm 元数据
• 许可证

#安装

使用以下命令使用 Composer 要求此包

composer require --dev barryvdh/laravel-ide-helper

此包利用了 Laravel 的包自动发现机制，这意味着如果您在生产环境中没有安装开发依赖项，它也不会被加载。

如果您出于某种原因希望手动控制它

• 将包添加到 composer.json 中的 extra.laravel.dont-discover 键中，例如

  "extra": {
    "laravel": {
      "dont-discover": [
        "barryvdh/laravel-ide-helper"
      ]
    }
  }

• 将以下类添加到 config/app.php 中的 providers 数组中

  Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class,

  如果您希望仅在非生产环境中手动加载它，您可以将其添加到 AppServiceProvider 的 register() 方法中

  public function register()
  {
      if ($this->app->isLocal()) {
          $this->app->register(\Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class);
      }
      // ...
  }

注意：避免在开发环境中缓存配置，这可能会在安装此包后导致问题；如果在运行命令时遇到问题，请先通过 php artisan cache:clear 清除缓存

#用法

查看 此 Laracasts 视频，了解快速入门/说明！

• php artisan ide-helper:generate - Laravel Facades 的 PHPDoc 生成
• php artisan ide-helper:models - 模型的 PHPDocs
• php artisan ide-helper:meta - PhpStorm 元数据文件

注意：您确实需要 CodeComplice for Sublime Text：https://github.com/spectacles/CodeComplice

#Laravel Facades 的自动 PHPDoc 生成

您现在可以自己重新生成文档（以供将来更新）

php artisan ide-helper:generate

注意：首先需要清除 bootstrap/compiled.php，因此在生成之前运行 php artisan clear-compiled。

这将生成文件 _ide_helper.php，您的 IDE 预计会额外解析它以进行自动完成。您可以使用配置 filename 来更改其名称。

您可以在 composer.json 中配置它，以便每次更新依赖项时都执行此操作

"scripts": {
    "post-update-cmd": [
        "Illuminate\\Foundation\\ComposerScripts::postUpdate",
        "@php artisan ide-helper:generate",
        "@php artisan ide-helper:meta"
    ]
},

您也可以发布配置文件以更改实现（例如，将接口更改为特定类）或设置 --helpers 的默认值。

php artisan vendor:publish --provider="Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider" --tag=config

生成器尝试识别真实的类，但如果找不到，您可以在配置文件中定义它。

某些类需要一个可用的数据库连接。如果您没有默认的可用连接，则某些 Facades 将不会被包含。您可以通过添加 -M 选项来使用内存中的 SQLite 驱动程序。

您可以选择包含辅助文件。默认情况下，它未启用，但您可以使用 --helpers (-H) 选项覆盖它。Illuminate/Support/helpers.php 已经设置好了，但您可以在配置文件中添加/删除您自己的文件。

#宏和 mixin 的自动 PHPDoc 生成

此包可以为宏和 mixin 生成 PHPDocs，这些 PHPDocs 将被添加到 _ide_helper.php 文件中。

但这只有在声明宏时使用类型提示才有效。

Str::macro('concat', function(string $str1, string $str2) : string {
    return $str1 . $str2;
});

#模型的自动 PHPDocs

如果您不想自己编写属性，可以使用命令 php artisan ide-helper:models 来生成基于表列、关系和 getter/setter 的 PHPDocs。

注意：此命令需要一个可用的数据库连接来内省每个模型的表

默认情况下，系统会询问您覆盖或写入单独的文件（_ide_helper_models.php）。您可以使用 --write (-W) 选项将注释直接写入您的模型文件，或者使用 --nowrite (-N) 强制不写入。

或者，使用 --write-mixin (-M) 选项只会将 mixin 标签添加到您的模型文件，并将其余部分写入 (_ide_helper_models.php)。类名将不同于模型，避免了 IDE 重复的烦恼。

在写入信息之前，请确保备份您的模型。

写入模型应该保留现有的注释，并且只追加新的属性/方法。现有的 PHPDoc 被替换，如果没有找到则被添加。使用 --reset (-R) 选项，现有的 PHPDocs 将被忽略，并且只保存新找到的列/关系作为 PHPDocs。

php artisan ide-helper:models "App\Models\Post"

/**
 * App\Models\Post
 *
 * @property integer $id
 * @property integer $author_id
 * @property string $title
 * @property string $text
 * @property \Illuminate\Support\Carbon $created_at
 * @property \Illuminate\Support\Carbon $updated_at
 * @property-read \User $author
 * @property-read \Illuminate\Database\Eloquent\Collection|\Comment[] $comments
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post newModelQuery()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post newQuery()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post query()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post whereTitle($value)
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post forAuthors(\User ...$authors)
 * …
 */

使用 --write-mixin (-M) 选项

/**
 * …
 * @mixin IdeHelperPost
 */

#模型目录

默认情况下，会扫描 app/models 中的模型。可选参数告诉您要使用哪些模型（包括 app/models 之外的模型）。

php artisan ide-helper:models "App\Models\Post" "App\Models\User"

您也可以使用 --dir 选项扫描不同的目录（相对于基本路径）

php artisan ide-helper:models --dir="path/to/models" --dir="app/src/Model"

您可以发布配置文件 (php artisan vendor:publish) 并设置默认目录。

#忽略模型

可以使用 --ignore (-I) 选项忽略模型

php artisan ide-helper:models --ignore="App\Models\Post,App\Models\User"

或者可以通过设置 ignored_models 配置来忽略模型

'ignored_models' => [
    App\Post::class,
    Api\User::class
],

#神奇的 where* 方法

Eloquent 允许在您的模型上调用 where<Attribute>，例如 Post::whereTitle(…)，并自动将其转换为 Post::where('title', '=', '…')。

如果您出于某种原因不希望生成它们（每个列一个），您可以通过配置 write_model_magic_where 并将其设置为 false 来禁用它们。

#神奇的 *_count 属性

您可以使用 ::withCount 方法来计算关系中的结果数量，而无需实际加载它们。然后，这些结果将按照 <columname>_count 约定放置在属性中。

默认情况下，这些属性在 phpdoc 中生成。您可以通过将配置 write_model_relation_count_properties 设置为 false 来关闭它们。

#泛型注释

Laravel 9 在 DocBlocks 中引入了集合的泛型注释。PhpStorm 2022.3 及更高版本支持在 @property 和 @property-read 声明中使用泛型注释，例如 Collection<User> 而不是 Collection|User[]。

可以通过将配置 use_generics_annotations 设置为 false 来禁用这些功能。

#支持基于 DocBlock 的 @comment

为了更好地支持 IDE，关系和 getter/setter 可以像表列一样为属性添加注释。因此，使用自定义 docblock @comment。

class Users extends Model
{
    /**
     * @comment Get User's full name
     *
     * @return string
     */
    public function getFullNameAttribute(): string
    {
        return $this->first_name . ' ' .$this->last_name ;
    }
}
 
// => after generate models
 
/**
 * App\Models\Users
 *
 * @property-read string $full_name Get User's full name
 * …
 */

#专用 Eloquent Builder 方法

Eloquent 模型添加了一个新方法，名为 newEloquentBuilder 参考，在这里我们可以添加支持创建新的专用类，而不是在模型本身中使用局部作用域。

如果由于某种原因不希望生成它们（每个列一个），可以通过配置 write_model_external_builder_methods 并将其设置为 false 来禁用此功能。

#不支持的或自定义数据库类型

常见的列类型（例如 varchar、integer）会正确映射到 PHP 类型（string、int）。

但有时您可能希望在数据库中使用自定义列类型，例如 geography、jsonb、citext、bit 等，这些类型可能会抛出“未知数据库类型”异常。

对于这些特殊情况，您可以通过配置 custom_db_types 来映射它们。示例

'custom_db_types' => [
    'mysql' => [
        'geography' => 'array',
        'point' => 'array',
    ],
    'postgresql' => [
        'jsonb' => 'string',
        '_int4' => 'array',
    ],
],

#自定义关系类型

如果您使用的是 Laravel 中没有内置的关系，则需要在配置中指定名称和返回类才能获得正确的生成。

'additional_relation_types' => [
    'externalHasMany' => \My\Package\externalHasMany::class
],

找到的关系通常会根据关系的名称生成一个返回值。

如果您的自定义关系不遵循这种传统的命名方案，您可以手动定义其返回类型。可用的选项是 many 和 morphTo。

'additional_relation_return_types' => [
    'externalHasMultiple' => 'many'
],

#模型钩子

如果您需要从默认情况下未处理的来源获取模型的额外信息，则可以使用模型钩子将生成过程挂钩，以动态添加额外信息。只需创建一个实现 ModelHookInterface 的类，并将其添加到配置中的 model_hooks 数组中。

'model_hooks' => [
   MyCustomHook::class,
],

run 方法将在生成期间为每个模型调用，并接收当前运行的 ModelsCommand 和当前 Model，例如：

class MyCustomHook implements ModelHookInterface
{
    public function run(ModelsCommand $command, Model $model): void
    {
        if (! $model instanceof MyModel) {
            return;
        }
 
        $command->setProperty('custom', 'string', true, false, 'My custom property');
        $command->unsetMethod('method');
        $command->setMethod('method', $command->getMethodType($model, '\Some\Class'), ['$param']);
    }
}

/**
 * MyModel
 *
 * @property integer $id
 * @property-read string $custom

#Laravel Fluent 方法的自动 PHPDocs 生成

如果您需要对迁移中的 Fluent 方法提供 PHPDocs 支持，例如

$table->string("somestring")->nullable()->index();

发布供应商后，只需将 config/ide-helper.php 文件中的 include_fluent 行更改为

'include_fluent' => true,

然后运行 php artisan ide-helper:generate，您现在将看到 IDE 识别所有 Fluent 方法。

#工厂构建器的自动完成

如果您希望 factory()->create() 和 factory()->make() 方法返回正确的模型类，则可以使用 config/ide-helper.php 文件中的 include_factory_builders 行启用自定义工厂构建器。在 Laravel 8 或更高版本中已弃用。

'include_factory_builders' => true,

要使此功能正常工作，您还必须发布 PhpStorm 元文件（见下文）。

#容器实例的 PhpStorm 元文件

可以生成一个 PhpStorm 元文件来 添加对工厂设计模式的支持。对于 Laravel，这意味着我们可以让 PhpStorm 了解我们从 IoC 容器中解析的是什么类型的对象。例如，events 将返回 Illuminate\Events\Dispatcher 对象，因此使用元文件，您可以调用 app('events')，它将自动完成 Dispatcher 方法。

php artisan ide-helper:meta

app('events')->fire();
\App::make('events')->fire();
 
/** @var \Illuminate\Foundation\Application $app */
$app->make('events')->fire();
 
// When the key is not found, it uses the argument as class name
app('App\SomeClass');
// Also works with
app(App\SomeClass::class);

注意：您可能需要重新启动 PhpStorm 并确保已索引 .phpstorm.meta.php。

注意：当您收到 FatalException: 类未找到时，请检查您的配置（例如，当您没有配置 S3 时，请从配置中删除 S3 作为云驱动程序。当您不使用 Redis 时，请从配置中删除 Redis ServiceProvider）。

您可以通过配置 meta_filename 更改生成的文件名。这对于您想要利用 PhpStorm 对 目录 .phpstorm.meta.php/ 的支持的情况很有用：放置在其中的所有文件都将被解析，如果您想为 PhpStorm 提供其他文件。

#许可证

Laravel IDE Helper Generator 是在 MIT 许可证 下发布的开源软件。