README

A Laravel package that scans your Eloquent models and validates their relationships against your actual database schema. It detects missing inverse relationships, circular dependencies, missing foreign key columns, missing indexes, and more — then reports a health score for your model layer.

Requirements

Installation

Install via Composer:

composer require devlin/laravel-model-analyzer

Laravel's package auto-discovery registers the service provider automatically. If you have auto-discovery disabled, add the provider manually in config/app.php:

'providers' => [
    Devlin\ModelAnalyzer\ModelAnalyzerServiceProvider::class,
],

Publish the config file

php artisan vendor:publish --provider="Devlin\ModelAnalyzer\ModelAnalyzerServiceProvider"

This creates config/model-analyzer.php.

Configuration

// config/model-analyzer.php

return [
    // Directories where your Eloquent models live
    'model_paths' => [
        app_path('Models'),
        app_path(), // Laravel < 8
    ],

    // Fully-qualified class names to skip
    'excluded_models' => [
        'Illuminate\Notifications\DatabaseNotification',
    ],

    // Database tables to skip
    'excluded_tables' => [
        'migrations',
        'failed_jobs',
        'password_resets',
        'personal_access_tokens',
    ],

    // Database connection to use (null = default connection)
    'database_connection' => null,

    // When true, warnings are treated as errors (non-zero exit code)
    'strict_mode' => env('MODEL_ANALYZER_STRICT', false),

    // Point weights used to calculate the 0–100 health score
    'health_weights' => [
        'has_inverse'     => 30,
        'no_circular'     => 30,
        'column_exists'   => 20,
        'has_index'       => 10,
        'has_foreign_key' => 10,
    ],
];

Commands

model-analyzer:analyze

Runs a full analysis of all discovered models and prints a report.

php artisan model-analyzer:analyze

Options:

Examples:

# Default CLI report
php artisan model-analyzer:analyze

# JSON output (pipe-friendly, useful in CI)
php artisan model-analyzer:analyze --format=json

# Fail CI if any warnings exist
php artisan model-analyzer:analyze --strict

# Analyze a single model
php artisan model-analyzer:analyze --models=User

Exit codes:

• 0 — no errors (warnings are allowed unless --strict is used)
• 1 — errors found, or warnings found with --strict

model-analyzer:health

Displays a summary health score and grouped recommendation report.

php artisan model-analyzer:health

Exit codes:

• 0 — no errors
• 1 — one or more errors detected

model-analyzer:list-models

Lists all Eloquent models discovered in the configured paths.

php artisan model-analyzer:list-models

Options:

Examples:

php artisan model-analyzer:list-models
php artisan model-analyzer:list-models --with-relationships
php artisan model-analyzer:list-models --json

What It Detects

Health Score

The model-analyzer:analyze and model-analyzer:health commands calculate a 0–100 health score based on the number and severity of issues found relative to the total number of relationships. A score of 100 means no issues were detected.

CI Integration

Run the analyzer in strict mode to fail your pipeline when any issue is found:

# GitHub Actions example
- name: Analyze models
  run: php artisan model-analyzer:analyze --strict

Or allow warnings but fail only on errors (the default):

- name: Analyze models
  run: php artisan model-analyzer:analyze

Running Tests

composer test

License

MIT