https://github.com/romanzipp/laravel-model-doc
📝 Generate PHPDoc comments for Laravel Models
https://github.com/romanzipp/laravel-model-doc
eloquent ide laravel orm php showcase
Last synced: 7 days ago
JSON representation
📝 Generate PHPDoc comments for Laravel Models
- Host: GitHub
- URL: https://github.com/romanzipp/laravel-model-doc
- Owner: romanzipp
- License: mit
- Created: 2021-01-15T07:51:12.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-03-19T05:57:10.000Z (about 1 month ago)
- Last Synced: 2025-03-29T01:11:55.059Z (25 days ago)
- Topics: eloquent, ide, laravel, orm, php, showcase
- Language: PHP
- Homepage:
- Size: 117 KB
- Stars: 26
- Watchers: 1
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Laravel Model PHPDoc Generator
[](https://packagist.org/packages/romanzipp/laravel-model-doc)
[](https://packagist.org/packages/romanzipp/laravel-model-doc)
[](https://packagist.org/packages/romanzipp/laravel-model-doc)
[](https://github.com/romanzipp/Laravel-Model-Doc/actions)
Generate PHPDoc comments for Laravel Models including [**database columns**](https://laravel.com/docs/eloquent), [**relationships**](https://laravel.com/docs/eloquent-relationships), [**accessors**](https://laravel.com/docs/eloquent-mutators#accessors-and-mutators), [**query scopes**](https://laravel.com/docs/eloquent#query-scopes) and [**factories**](https://laravel.com/docs/eloquent-factories).
## Contents
- [Installation](#installation)
- [Configuration](#configuration)
- [Features](#features)
- [Testing](#testing)
## Installation
```
composer require romanzipp/laravel-model-doc --dev
```
#### Laravel <= 10
If you use a Laravel version lower than 11, you also need to install the `doctrine/dbal` package:
```shell
composer require doctrine/dbal:^3.0 --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](config/model-doc.php) 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**
```php
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
```php
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 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.
```php
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](config/model-doc.php) 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](https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/types.html) package for database types. You can find a list of supported types [here](https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/types.html#mapping-matrix).
Laravel provides an example for `timestamp` type mapping [here](https://laravel.com/docs/10.x/migrations#modifying-columns-on-sqlite).
Here is an example for `enum` type mapping in `database.php` config file:
```php
'dbal' => [
'types' => [
'enum' => Doctrine\DBAL\Types\StringType::class,
],
],
```
## Features
- [x] Generate `@property` tags from attributes
- [x] Look for attributes type casts
- [x] Do not generate attribute `@property` tag if accessor exists
- [x] Generate `@method` tags from relationships
- [x] Generate `@property` tags from relationships
- [x] Generate `@property` tags from relationship counts
- [x] Generate `@method` tags query scopes
- [x] 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](https://lando.dev/).
```
lando start
lando phpunit
```