romanzipp / laravel-model-doc
Laravel Model PHPDoc Generator
Fund package maintenance!
romanzipp
Installs: 46 843
Dependents: 1
Suggesters: 0
Security: 0
Stars: 23
Watchers: 2
Forks: 6
Open Issues: 5
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
- dev-master
- 3.0.3
- 3.0.2
- 2.2.0
- 2.1.1
- 2.1.0
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.2.8
- 1.2.7
- 1.2.6
- 1.2.5
- 1.2.4
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.1
- 1.1.0
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.1.2
- 0.1.1
- 0.1.0
- 0.0.8
- 0.0.7
- 0.0.6
- 0.0.5
- 0.0.4
- 0.0.3
- 0.0.2
- 0.0.1
- dev-ensure-backwards-compatibility
- dev-add-generics
This package is auto-updated.
Last update: 2024-11-07 09:48:56 UTC
README
Generate PHPDoc comments for Laravel Models including database columns, relationships, accessors, query scopes and factories.
Contents
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
- 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 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