triquang/laravel-model-doc

Generates PHPDoc annotations (@property, etc.) for Eloquent models, supporting both standard and modular Laravel applications.

1.1.0 2025-08-21 06:35 UTC

Requires

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

MIT

• Nguyễn Trí Quang

• generator
• phpdoc
• module
• annotation
• model
• laravel
• modular
• docblock
• property

README

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

Example:

/**
 * @table quizzes
 * @property  int     $id           bigint     No description
 * @property  string  $description  text       No description
 * @property  string  $level        enum       {easy, medium, difficult}
 * @property  string  $title        varchar    No description
 * @property  Carbon  $created_at   timestamp  No description
 * @property  Carbon  $updated_at   timestamp  No description
 * @property-read Collection|QuizQuestion[] $questions
 */

🚀 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: Modules\\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

Dry-run mode (preview only):

php artisan gen:model-doc --dry-run --sort=db

Generate for a specific model:

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

Scan custom namespaces only:

php artisan gen:model-doc --ns=App\\Models,Modules\\Quiz\\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  int     $id             bigint      No description
 * @property  string  $title          varchar     The title of the book
 * @property  string  $description    text        A detailed description of the book
 * @property  string  $status         enum        {draft, published, archived}
 * @property  Carbon  $publish_date   date        No description
 * @property  Carbon  $created_at     timestamp   No description
 * @property  Carbon  $updated_at     timestamp   No description
 * @property-read Author $author
 * @property-read Collection|Tag[] $tags
 * @property-read Collection|Review[] $reviews
 */

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