romanzipp/laravel-model-doc

Laravel Model PHPDoc Generator

3.0.2 2024-03-19 17:39 UTC

Requires

• php: ^8.2
• illuminate/console: ^11.0
• illuminate/database: ^11.0
• illuminate/support: ^11.0
• phpowermove/docblock: ^4.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• orchestra/testbench: ^9.0
• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^11.0
• romanzipp/php-cs-fixer-config: ^3.0

MIT

• romanzipp

README

Generate PHPDoc comments for Laravel Models including database columns, relationships, accessors, query scopes and factories.

Contents

• Installation
• Configuration
• Features
• Testing

Installation

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

Configuration

Copy configuration to config folder:

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

Usage

php artisan model-doc:generate

See the configuration file for more specific use cases.

Prepare your models

1. Add the corresponding table name
2. Add relation methods return types
3. Add accessor methods return types

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);
    }
}

Example

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();
    }
}

Set custom path

You can set a custom base path for the generator using the usePath static method.

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

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

See the configuration file for more specific use cases.

Use verbose mode

If you get an error when generating the documentation for a model, you can use the --v option to get more information about the error.

php artisan model-doc:generate --v

Custom database types

If (in verbose mode) you get an error like Unknown database type enum requested, you can add that custom type mapping in Laravel's database.php config file. Laravel uses the Doctrine DBAL package for database types. You can find a list of supported types here. Laravel provides an example for timestamp type mapping here.

Here is an example for enum type mapping in database.php config file:

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

Features

• Generate @property tags from attributes
• Look for attributes type casts
• Do not generate attribute @property tag if accessor exists
• Generate @method tags from relationships
• Generate @property tags from relationships
• Generate @property tags from relationship counts
• Generate @method tags query scopes
• Generate @property tags from accessors
• Only generate @property-readonly if accessor has no real attribute or mutator

Testing

SQLite

./vendor/bin/phpunit

MariaDB

Requires Lando.

lando start
lando phpunit