Laravel Erd Laravel Package

Getting Started

Install the package as a dev dependency so it never ships to production:

composer require kevincobain2000/laravel-erd --dev
php artisan vendor:publish --tag=laravel-erd

The first place to look after install is config/laravel-erd.php. It controls where the generator scans for models, where the output HTML lands, and which models to skip. Verify the path (or model_path) points at app/Models if your app uses the modern Laravel 8+ layout; older flat app/ layouts need the default adjusted.

Generate your first diagram:

php artisan generate:erd

This writes a self-contained HTML file (typically under public/ — check the config output key). Open it in a browser; you should see nodes for each model with edges for hasMany/belongsTo/hasOne relationships. Your first use case is almost always onboarding: run it on an existing codebase, drop the HTML into your team wiki, and give new developers a single page that answers "how is this app wired."

If the diagram is empty or incomplete, the model namespace or path is wrong — that is the single most common failure. Confirm app_path('Models') matches the config before digging into anything else.

Implementation Patterns

Snapshot for onboarding docs. Commit the generated HTML to a docs/ folder (or publish it as a static artifact) so new hires get a diagram without running anything. Add a composer script so it's trivial to regenerate:

"scripts": {
  "erd": "php artisan generate:erd"
}

Diff-driven review. Because the package parses model source (not a live DB), you can regenerate on every PR and diff the HTML or the underlying graph. A relationship added without a corresponding migration, or a migration without a relationship, shows up as drift. Wire it into a GitHub Action that uploads the HTML as a build artifact on main.

Pre-refactor reconnaissance. Before splitting a monolith model or extracting a bounded context, generate the ERD and inspect the degree of each node. Models with 15+ incoming edges are the ones that will cost you the most to untangle; the diagram makes that cost visible in a way php artisan model:show never does across the whole app.

Targeted diagrams per domain. The config supports scanning a specific subdirectory. For multi-domain apps, generate one ERD per namespace (e.g. app/Models/Billing, app/Models/Catalog) by copying the config or swapping the path per invocation. Smaller diagrams are dramatically more readable than a single 200-node monster.

Pair with migrations and factories. Use the ERD alongside php artisan schema:dump output. The ERD shows intent (Eloquent relations); the schema dump shows reality (foreign keys). Discrepancies between the two are where bugs hide — especially missing belongsTo inverses and orphaned joins.

Exclude noisy models. Audit tables, pivot models, and framework-internal models pollute the graph. Add them to exclude in config rather than filtering the output visually afterward.

Gotchas and Tips

It parses source, not runtime. The generator reads model files statically rather than booting the container and reflecting on Eloquent. Consequences:

• Relationships defined in traits, base classes, or via resolveRelationUsing() won't appear.
• Dynamic relationship names (return $this->hasMany($this->relatedModel)) often fail to resolve.
• Conditional or macro-registered relations are invisible.

If a relation is missing from the diagram, check whether it's literally declared with a string class name inside the model file. This is the #1 source of "why is my edge gone" complaints.

Namespaces must be fully qualified. belongsTo(User::class) resolves cleanly; belongsTo('App\User') may or may not depending on the version. Stick to ::class syntax in your models, both for IDE support and for this tool.

Polymorphic relations render poorly. morphMany and morphTo frequently produce edges to the wrong model or no edge at all, because the target is stored as a string column, not a class reference. Don't trust morph edges; annotate them manually in your docs if they matter.

Output path matters for auth. If the HTML lands in public/, anyone hitting the URL sees your entire schema. Either keep it out of public/, put it behind auth middleware in a route, or ensure the file is .gitignored in web deployments. This is easy to miss in a rush.

Large apps degrade. With 150+ models the diagram becomes unintelligible regardless of zoom. Prefer scoped generation per domain (see Implementation Patterns) over trying to make one giant diagram work.

No DB connection required — a feature, not a bug. Because it's static analysis, you can generate ERDs in CI without a database, on a fresh clone, or against a stale .env. Useful for docs pipelines; also means it won't catch relations that only exist in the DB via manual foreign keys.

Regenerate after every migration touching relations. There's no watch mode and no cache invalidation — the file goes stale silently. Treat it like a build artifact, not a live view.

Extension point: wrap the command. Since the package's command is thin, the cleanest customisation is a small artisan command of your own that calls generate:erd, post-processes the HTML (inject a title, filter nodes by namespace, add a timestamp), and writes it wherever your docs site expects. Don't fork the package — it's low-activity and you'll be maintaining the fork forever.