README

为 Laravel 模型生成 PHPDoc 注释，包括 数据库列、关系、访问器、查询作用域 和 工厂。

内容

• 安装
• 配置
• 功能
• 测试

安装

composer require romanzipp/laravel-model-doc --dev

配置

将配置复制到配置文件夹

php artisan vendor:publish --provider="romanzipp\ModelDoc\Providers\ModelDocServiceProvider"

用法

php artisan model-doc:generate

有关更具体的用例，请参阅 配置文件。

准备你的模型

1. 添加相应的 表名
2. 添加 关系 方法返回 类型
3. 添加 访问器 方法返回 类型

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class MyModel extends Model
{
    protected $table = 'models'; // 1. Add the corresponding table name
    
    public function teams(): HasMany // 2. Add relation methods return types
    {
        return $this->hasMany(Team::class);
    }
    
    public function getNameAttribute(): string // 3. Add accessor methods return types
    {
        return ucfirst($this->name);
    }
}

示例

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

/**
 * @property string $id
 * @property string $title
 * @property string $pretty_title
 * @property string|null $icon
 * @property int $order
 * @property bool $enabled
 * @property array $children
 * @property \Illuminate\Support\Carbon|null $created_at
 * @property \Illuminate\Support\Carbon|null $updated_at
 *
 * @property \Illuminate\Database\Eloquent\Collection|\App\Models\Team[] $teams
 * @property int|null $teams_count
 *
 * @method static \Illuminate\Database\Eloquent\Builder whereTeamName(string $name)
 * 
 * @method static \Database\Factoies\MyUserFactory<self> factory($count = null, $state = [])
 */
class MyUser extends Model
{
    use HasFactory;

    protected $table = 'users';

    protected $casts = [
        'children' => 'array',
    ];

    public function teams(): HasMany
    {
        return $this->hasMany(Team::class);
    }

    public function scopeWhereTeamName(Builder $builder, string $name)
    {
        $builder->where('name', $name);
    }

    public function getPrettyTitleAttribute(): string
    {
        return ucfirst($this->title);
    }
    
    protected static function newFactory()
    {
        return new \Database\Factoies\MyUserFactory();
    }
}

设置自定义路径

您可以使用 usePath 静态方法设置生成器的自定义基本路径。

use Illuminate\Support\ServiceProvider;
use romanzipp\ModelDoc\Services\DocumentationGenerator;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        DocumentationGenerator::usePath(fn () => base_path('app/Models'));
    }
}

有关更具体的用例，请参阅 配置文件。

使用详细模式

如果在生成模型文档时遇到错误，您可以使用 --v 选项获取有关错误的更多信息。

php artisan model-doc:generate --v

自定义数据库类型

如果在详细模式下遇到类似于 Unknown database type enum requested 的错误，您可以在 Laravel 的 database.php 配置文件中添加该自定义类型映射。Laravel 使用 Doctrine DBAL 包进行数据库类型。您可以在 此处 找到支持类型的列表。Laravel 在 此处 提供了 timestamp 类型映射的示例。

以下是 database.php 配置文件中 enum 类型映射的示例

'dbal' => [
    'types' => [
        'enum' => Doctrine\DBAL\Types\StringType::class,
    ],
],

功能

• 从属性生成 @property 标签
• 查找属性类型转换
• 如果存在访问器，则不生成属性 @property 标签
• 从关系生成 @method 标签
• 从关系生成 @property 标签
• 从关系计数生成 @property 标签
• 生成查询作用域的 @method 标签
• 从访问器生成 @property 标签
• 只有当访问器没有真实属性或修改器时，才生成 @property-readonly

测试

SQLite

./vendor/bin/phpunit

MariaDB

需要 Lando。

lando start
lando phpunit