README

完整的 PHPDocs，直接从源代码生成

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

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

• 安装
• 用法
  • 为 Laravel Facades 自动生成 PHPDoc
  • 为模型自动生成 PHPDoc
    • 模型目录
    • 忽略模型
    • 模型钩子
  • 为 Laravel Fluent 方法自动生成 PHPDoc
  • 为工厂构建器提供自动完成
  • 为容器实例提供 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 - 模型的 PHPDoc
• php artisan ide-helper:meta - PhpStorm Meta 文件

注意：您需要为 Sublime Text 安装 CodeComplice： 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 生成

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

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

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

为模型自动生成 PHPDoc

如果您不想自己编写属性，可以使用 php artisan ide-helper:models 命令来生成 PHPDoc，这些 PHPDoc 基于表的列、关系和获取器/设置器。

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

默认情况下，您会被提示覆盖或写入一个单独的文件（_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<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构建器方法

向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'
],

模型钩子

如果您需要从默认处理之外的信息源获取模型信息，您可以通过模型挂钩 hook 到生成过程以动态添加额外信息。只需创建一个实现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 方法自动生成 PHPDoc

如果您需要在迁移中为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时，请删除Redis ServiceProvider）。

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

许可协议

Laravel IDE Helper Generator是开源软件，采用MIT许可