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

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

某些类需要有效的数据库连接。如果您没有默认的有效连接，则某些 Facades 将不会被包含。您可以通过添加 -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;
});

模型的自动 PHPDocs

如果您不想自己编写属性，可以使用php artisan ide-helper:models命令来生成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<属性>，例如Post::whereTitle(…)，并将其自动转换为例如Post::where('title', '=', '…')。

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

魔法*_count属性

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

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

泛型注解

Laravel 9 引入了集合在 DocBlocks 中的泛型注解。PhpStorm 2022.3 及以上版本支持在 DocBlocks 中的 @property 和 @property-read 声明中使用泛型注解，例如使用 Collection 而不是 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 来禁用此功能。

自定义关系类型

如果你使用的是 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 Meta 文件（见下文）。

容器实例的 PhpStorm Meta

可以生成一个 PhpStorm meta 文件以 添加对工厂设计模式的支持。对于 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 辅助生成器是开源软件，遵循 MIT 许可协议