dottedai/laravel-model-annotator

Laravel command to annotate Eloquent models with database schema, relationships, and casts.

dev-main 2025-05-12 17:06 UTC

Requires

• php: ^8.0
• illuminate/support: ^9.0|^10.0|^11.0

MIT

• Matheus Puppe

README

Laravel Model Annotator is a developer tool that automatically adds PHPDoc annotations to your Eloquent model classes based on your database schema. It improves IDE autocompletion and static analysis for properties, relationships, and casted attributes and now export full model documentation to a markdown file.

🚀 Features

• ✅ Annotates all model properties based on database columns.
• 🔁 Detects and documents Eloquent relationships (hasMany, belongsTo, etc).
• 🧠 Adds annotations for casted attributes using Laravel's $casts.
• ✨ IDE-friendly annotations for better autocompletion and PHPStan support.
• 🪄 Works out of the box — just install and run.

📦 Installation

Option 1: Via Composer

If published to Packagist:

composer require dottedai/laravel-model-annotator --dev

Option 2: Local Development

1. Clone or download the repository into a packages directory:

mkdir -p packages/dottedai
git clone https://github.com/dottedai/laravel-model-annotator packages/dottedai/laravel-model-annotator

1. Add to your composer.json:

"repositories": [
  {
    "type": "path",
    "url": "packages/dottedai/laravel-model-annotator"
  }
]

1. Require it locally:

composer require dottedai/laravel-model-annotator:*

⚙️ Usage

After installation, run the Artisan command:

php artisan models:annotate

This will scan the app/Models directory and update each model class with a PHPDoc block containing:

• @property for columns (with types and nullability),
• @property for relationships,
• @property for casted attributes.

🧪 Example Output

/**
 * @property int $id
 * @property string $name
 * @property string|null $email
 * @property \App\Models\Team $team
 * @property Carbon\Carbon $created_at
 */
class User extends Model

Export Markdown Documentation

php artisan models:export-docs

Generates a MODEL_DOCS.md in the root directory with all properties, casts, and relationships grouped by model.

🧪 Example Output (MODEL_DOCS.md)

# Eloquent Model Annotations

## User

### Properties
- `int $id`
- `string $name`
- `?string $email`

### Casts
- `datetime $created_at`

### Relationships
- `\App\Models\Team $team`

🛠 Configuration

By default:

• Scans app/Models.
• Infers column types and nullability from DB schema.
• Detects relationship methods with no arguments.
• Reads $casts array from the model.

🧠 How It Works

• Uses Laravel’s Schema Builder to inspect each model’s database table.
• Reflects on model methods to identify Eloquent relationships.
• Combines schema and relationship data into a single annotation block.
• Rewrites the top of the model file with the updated docblock.

🧱 Requirements

• PHP 8.0+
• Laravel 9, 10, or 11

📄 License

This project is open-sourced under the MIT license.