triquang/laravel-model-doc

A Laravel package to generate PHPDoc for Laravel models (@property varchar string $name...)

v1.0.0 2025-07-28 17:13 UTC

Requires

• php: ^8.0
• illuminate/support: ^11.0 || ^12.0

MIT

• Nguyễn Trí Quang

README

A Laravel Artisan command that generates PHPDoc blocks for your Eloquent models based on your database schema and relationships.

Example:

/**
 * @table users
 * @property  bigint    int     $id
 * @property  varchar   string  $name
 * @property  timestamp Carbon  $created_at
 * @property  timestamp Carbon  $updated_at
 * @property-read Collection|Post[] $posts
 */

🚀 Features

• Generate @property based on SQL column types.
• Detect @property-read from relationships.
• Support models in:
  • app/Models
  • Modules/*/app/Models (modular structure)
• Sort by:
  • PHP type (default)
  • Property name
  • DB type
• Supports multiple DB drivers: MySQL, PostgreSQL, SQLite, SQL Server, Oracle.

📦 Installation

This package is intended for development only.
Please install it using the --dev flag:

Install via Composer:

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

⚙️ Usage

Run the Artisan command:

php artisan gen:model-doc [options]

Options

Option	Description
--model	Only process a specific model (FQCN). Example: App\\Models\\User.
--dry-run	Show output to screen without modifying files.
--sort	Sort by: type (PHP type), name, or db (PHP + DB + name).
--ns	Select namespaces to scan. Example: App\\Domain\\Models.

🧠 How It Works

• Reads model classes from app/Models and Modules/*/app/Models or from namespaces
• Uses DB schema to map SQL types → PHP types
• Detects Eloquent relationships (e.g., hasMany, belongsTo)
• Writes /** ... */ docblock directly under <?php in model file

🧪 Examples

Generate all model docs:

php artisan gen:model-doc

Generate for a specific model:

php artisan gen:model-doc --model=App\\Models\\User

Dry-run mode (preview only):

php artisan gen:model-doc --dry-run

Scan custom namespaces only:

php artisan gen:model-doc --ns=Modules\\Quiz\\Models,App\\Models

💡 Note: Namespaces must be mapped in composer.json using psr-4 autoloading. This also applies to Modules/*/composer.json.

📄 Example Output

/**
 * @table books
 * @property  bigint     int       $id
 * @property  varchar    string    $title
 * @property  text       string    $summary
 * @property  timestamp  Carbon    $published_at
 * @property-read Author           $author
 * @property-read Collection|Tag[] $tags
 */

✅ Requirements

• PHP >= 8.0
• Laravel 11 / 12
• Composer

📄 License

MIT © Nguyễn Trí Quang

🙌 Contributing

PRs are welcome! Feel free to improve functionality or report issues via GitHub Issues.

📬 Contact

• GitHub: github.com/ntquangkk
• Email: [e-mail]