meioco3/next-ide-helper

Laravel ide helper 在强化的基础上重建

维护者

详细信息

github.com/a-long-way/next-ide-helper

主页

源代码

资助包维护！
soyhuce

安装: 1

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 5

dev-main 2024-05-10 09:35 UTC

Requires

Requires (Dev)

MIT aedf23cf2ef84043a7c3ec9c268a9fd0fc22765a

  • Bastien Philippe <bastien.philippe.woop@soyhuce.fr>

phpdoclaravelautocompletionidephpstorm

This package is auto-updated.

Last update: 2024-09-10 10:15:51 UTC

README

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status GitHub PHPStan Action Status Total Downloads

此包旨在成为一个易于扩展的 ide-helper 生成器。

它受到了 barryvdh/laravel-ide-helper 伟大工作的启发。

它为 Eloquent 魔法（模型属性、作用域、关系等）、可宏化的类的注册宏、容器实例等提供补全。

安装

您应使用 composer 安装此包

composer require --dev soyhuce/next-ide-helper

您可能想发布配置文件

php artisan vendor:publish --tag=next-ide-helper-config

完成！

使用

模型

命令 php artisan next-ide-helper:models 将生成多个元素以帮助您的 ide 理解您正在做什么。此包需要您有权访问已迁移的数据库。

它将为您的类添加 docblock 并创建一个 _ide_models.php 文件。此文件 不得 包含，而只应由您的 ide 分析。

属性

该命令从数据库解析模型属性。它们被添加到您的模型类 docblock 中。如果属性有类型转换，则包将正确地转换属性。

/**
 * @property int $id
 * @property string $name
 * @property string $email
 * @property \Illuminate\Support\Carbon|null $email_verified_at
 * @property string $password
 * @property string|null $remember_token
 * @property \Illuminate\Support\Carbon $created_at
 * @property \Illuminate\Support\Carbon $updated_at
 */
class User extends \Illuminate\Database\Eloquent\Model
{
    // ...
    protected $casts = [
        'email_verified_at' => 'datetime',
    ];
}

属性转换也将与自定义类型转换一起工作

use App\Email;

class EmailCast implements \Illuminate\Contracts\Database\Eloquent\CastsAttributes
{
    public function get($model, $key, $value, $attributes): Email
    {
        return new Email($value);
    }
    
    // ...
}

class User extends Model
{
    protected $casts = [
        'email' => EmailCast::class,
    ];
}

这将产生 @property \App\Email $email

注意类型必须定义为返回类型或在 get 方法的 docblock 中的 @return。

该命令还会将访问器中的属性添加为只读属性

/**
 * @property-read string $upper_name
 */
class User extends Model
{
    public function getUpperNameAttribute(): string
    {
        return Str::upper($this->name);
    }   
}

自定义集合

如果您的模型定义了自定义集合，则该命令将向模型的 docblock 中添加 all 方法以重新定义返回类型

use \App\Collections\UserCollection;

/**
 * @method static \App\Collections\UserCollection all(array|mixed $columns = ['*'])
 */
class User extends Model
{
    public function newCollection(array $models = []): UserCollection
    {
        return new UserCollection($models);
    }
}

查询构建器

如果您的模型定义了自定义 Eloquent 构建器，则该命令将向模型的 docblock 中添加一些标签。

use App\Builder\UserBuilder;
/**
 * @method static \App\Builder\UserBuilder query()
 * @mixin \App\Builder\UserBuilder
 */
class User extends Model
{
    public function newEloquentBuilder($query)
    {
        return new UserBuilder($query);
    }
}

它还将向构建器添加一些标签以帮助您的 ide

  • 基于模型属性的 where 子句
  • 结果值的返回值
use Illuminate\Database\Eloquent\Builder;

/**
 * @method \App\Builder\UserBuilder whereId(int|string $value)
 * @method \App\Builder\UserBuilder whereName(string $value)
 * @method \App\Builder\UserBuilder whereEmail(string $value)
 * @method \App\Builder\UserBuilder whereEmailVerifiedAt(\Illuminate\Support\Carbon|string|null $value)
 * @method \App\Builder\UserBuilder wherePassword(string $value)
 * @method \App\Builder\UserBuilder whereRememberToken(string|null $value)
 * @method \App\Builder\UserBuilder whereCreatedAt(\Illuminate\Support\Carbon|string $value)
 * @method \App\Builder\UserBuilder whereUpdatedAt(\Illuminate\Support\Carbon|string $value)
 * @method \App\User create(array $attributes = [])
 * @method \Illuminate\Database\Eloquent\Collection|\App\User|null find($id, array $columns = ['*'])
 * @method \Illuminate\Database\Eloquent\Collection findMany($id, array $columns = ['*'])
 * @method \Illuminate\Database\Eloquent\Collection|\App\User findOrFail($id, array $columns = ['*'])
 * @method \App\User findOrNew($id, array $columns = ['*'])
 * @method \App\User|null first(array|string $columns = ['*'])
 * @method \App\User firstOrCreate(array $attributes, array $values = [])
 * @method \App\User firstOrFail(array $columns = ['*'])
 * @method \App\User firstOrNew(array $attributes = [], array $values = [])
 * @method \App\User forceCreate(array $attributes = [])
 * @method \Illuminate\Database\Eloquent\Collection get(array|string $columns = ['*'])
 * @method \App\User getModel()
 * @method \Illuminate\Database\Eloquent\Collection getModels(array|string $columns = ['*'])
 * @method \App\User newModelInstance(array $attributes = [])
 * @method \App\User updateOrCreate(array $attributes, array $values = [])
 * @template TModelClass
 * @extends \Illuminate\Database\Eloquent\Builder<\App\User>
 */
class UserBuilder extends Builder
{
}

如果您的模型未定义自定义构建器，则 next-ide-helper:models 将在 _ide_models.php 中创建假类，并提供 docblock 以提供自动补全。

作用域

您的模型的所有作用域都将作为其构建器的方法定义（在自定义查询构建器或 _ide_models.php 中）。

class User extends Model
{
    public function scopeWhereVerified($query, bool $verified = true): void
    {
        $query->whereNull('email_verified_at', 'and', !$verified);
    }
}

这将在您的自定义构建器上产生 @method \App\Builder\UserBuilder whereVerified(bool $verified = true)。

请注意，如果只是调用 User::whereVerified()，则您的 ide 可能会抱怨 Non-static method 'whereVerified' should not be called statically, but the class has the '__magic' method.。这就是为什么我们建议您使用 User::query()->...。

关系

模型命令还将解析您的模型关系并提供大量补全助手。

/**
 * @property-read \Illuminate\Database\Eloquent\Collection<int, \App\Post> $posts
 */
class User extends Model
{
    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
}

class Post extends Model
{
    public function scopeWherePublished($query): void
    {
        return $query->whereNotNull('published_at');
    }
}

自定义构建器和自定义集合也将由 ide 正确解析

Larastan 友好标签

如果您使用 PHPStan 或 Larastan，可以通过将 models.larastan_friendly 配置设置为 true 来获取有关定义集合的更多信息。

使用此配置，您将在模型中获得额外的标签

/**
 * @phpstan-method static \App\Collections\UserCollection<int, \App\Models\User> all(array|mixed $columns = ['*'])
 */
class User extends Model {}

并在您的自定义构建器中

/**
 * @phpstan-method \Illuminate\Database\Eloquent\Collection<int, \App\User>|\App\User|null find($id, array $columns = ['*'])
 * @phpstan-method \Illuminate\Database\Eloquent\Collection<int, \App\User> findMany($id, array $columns = ['*'])
 * @phpstan-method \Illuminate\Database\Eloquent\Collection<int, \App\User>|\App\User findOrFail($id, array $columns = ['*'])
 * @phpstan-method \Illuminate\Database\Eloquent\Collection<int, \App\User> get(array|string $columns = ['*'])
 * @phpstan-method \Illuminate\Database\Eloquent\Collection<int, \App\User> getModels(array|string $columns = ['*'])
 * @template TModelClass
 * @extends \Illuminate\Database\Eloquent\Builder<\App\User>
 */
class UserBuilder extends Builder {}

扩展

有时，命令无法解决或预测所有可能的解决方案。

因此，这个包提供了一个自定义一些解决逻辑的方法，您可以在 next-ide-helper.models.extensions 配置中添加您的自定义解析器。

宏

此包提供 next-ide-helper:macros。命令解析所有注册的宏，并生成一个 _ide_macros.php 文件，为 Macroable 宏提供自动完成。

例如：

use Illuminate\Support\Collection;

Collection::macro('mapToUpper', function(): Collection {
    return $this->map(fn(string $item) => \Illuminate\Support\Str::upper($item));
});

多亏了 _ide_macros.php 文件，我们为 mapToUpper 方法提供了自动完成。

就像 _ide_models.php 一样，_ide_macros.php 文件不需要包含，只需由您的 IDE 分析。

Phpstorm 元数据

命令 php artisan next-ide-helper:meta 将生成一个 .phpstorm.meta.php 文件。它将为容器绑定和某些 Laravel 辅助函数提供完成。

工厂

命令 php artisan next-ide-helper:factories 将为您在工厂中添加文档块，以正确地类型化一些方法。它还将明确模型关系的魔术方法。

例如，如果您有：

class User extends Model                        
{
    public function role(): BelongsTo
    {
        return $this->belongsTo(Role::class);
    }

    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
    
    public function newCollection(array $models = [])
    {
        return new UserCollection($models);
    }
}

此命令将在 UserFactory 中生成文档块。

/**
 * @method \App\User createOne($attributes = [])
 * @method \App\User|\App\Collections\UserCollection create($attributes = [], ?\Illuminate\Database\Eloquent\Model $parent = null)
 * @method \App\User makeOne($attributes = [])
 * @method \App\User|\App\Collections\UserCollection make($attributes = [], ?\Illuminate\Database\Eloquent\Model $parent = null)
 * @method \App\User newModel(array $attributes = [])
 * @method \Database\Factories\UserFactory forRole($attributes = [])
 * @method \Database\Factories\UserFactory hasPosts($count = 1, $attributes = [])
 * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\User>
 */
class UserFactory extends Factory
{
    //    
}

别名

有时我们不想使用完全限定的类名，而更愿意使用 Laravel 别名。

命令 php artisan next-ide-helper:aliases 将创建一个您的 IDE 可以理解的文件。

然后，它将为您的 config/app.php 文件以及您使用的包中定义的别名提供自动完成、语法高亮等。

生成所有

您可以使用 next-ide-helper:all 生成所有 next-ide-helper 文件。

它将为您生成：

  • 模型
  • 宏
  • Phpstorm 元数据
  • 别名
  • 工厂（如果您正在使用 Laravel 8 基于类的模型工厂）

自定义应用引导

有时您可能希望在命令执行之前启动环境。例如，在多租户多数据库应用程序中，您需要启动您的租户连接，以便此包解决表列。

在这种情况下，您只需创建自己的启动器，并配置包以使用它。

class MultitenantBootstrapper implements \Soyhuce\NextIdeHelper\Contracts\Bootstrapper 
{
    private Tenancy $tenancy;

    public function __construct(Tenancy $tenancy)
    {
        $this->tenancy = $tenancy;    
    }

    public function bootstrap() : void
    {
        $tenant = \App\Tenant::firstOrFail();
        
        $this->tenancy->connect($tenant);
    }
}
// Note that this code is completely fictive.

现在，您只需将其添加到您的 next-ide-helper.php 配置文件中。

'bootstrapper' => \App\Support\MultitenantBootstrapper::class,

您的启动器从其构造函数中受益于 Laravel 依赖注入。

在 docblock 中自定义内容

某些命令将重置您的文档块。如果您不想删除某些内容，必须在文档块中添加一个 @generated 标签，告诉 nest-ide-helper 在何处插入其内容。

例如：

/**
 * Comment that will not be overwritten after docblock generation
 *  
 * @author John Doe
 * @package Foo Bar
 * @deprecated since 1.0.0
 * @api 
 * 
 * @generated
 * [the content generated by next-ide-helper will be inserted here]
 */
class SomeModel extends Model {}

更新日志

有关最近更改的更多信息，请参阅 更新日志。

贡献

有关详细信息，请参阅 贡献指南。

安全漏洞

请查看我们的安全策略，了解如何报告安全漏洞： 安全策略。

致谢

许可证

MIT 许可证（MIT）。有关更多信息，请参阅 许可证文件。