README

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

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

3.x 分支支持 Laravel 10 和 11。对于旧版本，请使用 2.x 版本。

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

安装

使用以下命令使用 composer 安装此包：

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

注意

如果您遇到 doctrine/dbal 版本冲突，请尝试： composer require --dev barryvdh/laravel-ide-helper --with-all-dependencies

此包利用了 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 Meta 文件

注意：您需要 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

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

一些类需要一个有效的数据库连接。如果你没有默认的工作连接，某些门面将不会包含在内。你可以通过添加-M选项使用内存中的SQLite驱动程序。

如果你的应用中使用了实时门面，这些也将通过@mixin注解包含在生成的文件中，并在门面下方扩展原始类。

注意：此功能使用在storage/framework/cache文件夹中的生成实时门面文件。这些文件是在使用实时门面时按需生成的，所以如果框架尚未生成，则不会包含在辅助文件中。先运行路由/命令/代码，然后重新生成辅助文件，这次实时门面将包含在内。

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

宏和混入的自动PHPDoc生成

此包可以为宏和混入生成PHPDocs，并将其添加到《_ide_helper.php》文件中。

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

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

模型的自动 PHPDocs

如果你不想自己编写属性，可以使用命令php artisan ide-helper:models根据表列、关系和获取器/设置器生成PHPDocs。

注意：此命令需要有效数据库连接以反查每个模型的表

默认情况下，你会被要求覆盖或写入一个单独的文件（《_ide_helper_models.php》）。你可以使用--write (-W)选项直接将注释写入模型文件，或者使用--nowrite (-N)强制不写入。

或者使用--write-mixin (-M)选项，将只添加混入标签到你的模型文件中，其余部分写入（《_ide_helper_models.php》）。类名将与模型不同，以避免IDE重复的烦恼。

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

写入模型应保留现有注释并仅追加新属性/方法。它不会更新已更改的属性/方法。

使用--reset (-R)选项，将替换整个现有的PHPDoc，包括任何已做的注释。

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，例如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 而不是 Collection|User[]。

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

基于 DocBlock 支持 @comment

为了更好地支持 IDE，关系和获取器/设置器也可以对属性添加注释，就像表列一样。因此使用了自定义的 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 来禁用此功能。

自定义关系类型

如果你使用的是 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 Meta

可以生成一个 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 已被索引。

注意：当您收到致命异常：找不到类时，检查您的配置（例如，在没有配置 S3 时删除 S3 作为云驱动程序。如果您不使用 Redis ServiceProvider，请将其删除）。

您可以通过配置 meta_filename 来更改生成的文件名。这可能在您想要利用 PhpStorm 对 directory .phpstorm.meta.php/ 的支持时很有用：放置在该目录中的所有文件都将被解析，如果您想向 PhpStorm 提供额外的文件。

许可证

Laravel IDE Helper Generator 是开源软件，许可协议为 MIT 协议