README

Fork off of romanzipp/Laravel-Model-Doc

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

Installation
Configuration
Features
Testing

Installation

composer require boktoso-enterprise/laravel-model-doc --dev

Configuration

Copy configuration to config folder:

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

Usage

php artisan model-doc:generate

See the configuration file for more specific use cases.

Prepare your models

Add the corresponding table name
Add relation methods return types
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 BoktosoEnterprise\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

Specify the Model to update

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 --model={modelClass}

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,
    ],
],

Testing

SQLite

./vendor/bin/phpunit

MariaDB

Requires Lando.

lando start
lando phpunit

boktoso-enterprise / laravel-model-doc

Maintainers

Details