README

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

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

• 安装
• 用法
  • 为 Laravel Facades 自动生成 PHPDoc
  • 为模型自动生成 PHPDoc
    • 模型目录
    • 忽略模型
    • 模型钩子
  • 为 Laravel Fluent 方法自动生成 PHPDoc
  • 为工厂构建器提供自动完成
  • 为容器实例提供 PhpStorm Meta
• 与 Lumen 一起使用
  • 启用 Facades
  • 添加 Service Provider
  • 添加额外的 Facades
• 许可协议

安装

使用以下命令使用 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 - 模型的 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

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

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

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

为宏和混入自动生成 PHPDoc

此包可以为添加到 _ide_helper.php 文件的宏和混入生成 PHPDoc。

但只有在声明宏时使用类型提示时，此功能才有效。

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

为模型自动生成 PHPDoc

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

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

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

或者使用 --write-mixin (-M) 选项，只会将混合标签添加到模型文件中，其余部分写入（_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)
 * …
 */

使用 --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 来关闭它们。

支持基于 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 来禁用此功能。

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

常见的列类型（例如 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',
    ],
],

模型钩子

如果您需要从默认处理之外的资源获取模型额外信息，可以通过模型钩子连接到生成过程，即时添加额外信息。只需创建一个实现 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

如果您需要在迁移中支持 PHPDocs 中的 Fluent 方法，例如：

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

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

'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，请删除 Redis ServiceProvider）。

您可以通过配置 meta_filename 来更改生成的文件名。这在您想利用 PhpStorm 也支持 directory .phpstorm.meta.php/ 的情况下很有用，它将解析放置在该目录中的任何文件，如果您想向 PhpStorm 提供额外的文件。

与 Lumen 一起使用

此包专注于 Laravel 开发，但它也可以通过一些方法在 Lumen 中使用。因为 Lumen 工作方式略有不同，它类似于 Laravel 的裸骨版本，主要配置参数位于 bootstrap/app.php 中，因此必须进行一些修改。

启用 Facades

虽然 Laravel IDE Helper 可以自动生成默认的 Facades 以进行代码提示，但 Lumen 默认不激活 Facades。如果您计划使用它们，您必须在 Create The Application 部分下启用它们，取消注释此行

// $app->withFacades();

从那里，您应该能够使用 create_alias() 函数将额外的 Facades 添加到您的应用程序中。

添加 Service Provider

您可以在 app/Providers/AppServiceProvider.php 中安装 Laravel IDE Helper，并取消注释注册 App Service Providers 的这一行，以便它能够正确加载。

// $app->register(App\Providers\AppServiceProvider::class);

如果您不使用该行，通常在管理多个 Laravel/Lumen 安装时很有用，您必须在 bootstrap/app.php 的 Register Service Providers 部分下添加此行代码。

if ($app->environment() !== 'production') {
    $app->register(\Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class);
}

之后，Laravel IDE Helper 应该可以正常工作。在生成过程中，脚本可能会抛出一些异常，说某些类不存在或存在一些未定义的索引。这是正常的，因为 Lumen 删除了一些默认包，如 Cookies、Storage 和 Session。如果您计划添加这些包，您将必须手动添加它们，并在需要时创建额外的 Facades。

添加额外的 Facades

目前，Lumen IDE Helper 不考虑在 bootstrap/app.php 下使用 create_alias() 创建的额外 Facades，因此您需要创建一个 config/app.php 文件，并在 aliases 数组中再次添加您的自定义别名，如下所示：

return [
    'aliases' => [
        'CustomAliasOne' => Example\Support\Facades\CustomAliasOne::class,
        'CustomAliasTwo' => Example\Support\Facades\CustomAliasTwo::class,
        //...
    ]
];

运行 php artisan ide-helper:generate 后，建议（但不是必须）将 config/app.php 重命名为其他名称，直到您需要重新生成文档或部署到生产环境。Lumen 5.1+ 会读取此文件进行配置参数，如果文件存在，则可能会覆盖一些配置。

许可协议

Laravel IDE Helper 生成器是开源软件，遵循 MIT 许可证