Download the PHP package byrcsc/laravel-cartographer without Composer

Laravel Cartographer

Generate a Mermaid entity relationship diagram of your Laravel application from its Eloquent models and database schema. Every app eventually needs one: onboarding a developer, planning a migration, working out what still points at a table. Drawn by hand, it is wrong within a month.

The package provides the diagram generator. Your application keeps ownership of its models, its schema, and where the output file lives. Cartographer never reads your data.

Tested on MySQL, PostgreSQL, and SQLite.

One artisan command writes a Markdown file that GitHub and GitLab render on sight. Commit it, and each schema change shows up as a diff in the pull request that caused it.

Installation

Install as a dev dependency:

Publish the config file if you want to change the defaults:

What the diagram is built from

Cartographer never reads your data. It builds every diagram from two sources:

• Your models. Relationship methods are resolved through Eloquent itself, so foreign keys, pivot tables, and polymorphic names come out exactly as your application resolves them. This covers belongsTo, hasOne, hasMany, belongsToMany, every morph* relation, and the through relations.
• Your schema. Tables, columns, types, and keys come from Laravel's native schema introspection on your development connection. Structure only: no query ever touches your rows.

Because the schema is read from the database, it stays correct on apps with squashed migrations, raw SQL migrations, and long migration histories.

Quick start

Generate the full ERD to docs/erd.md:

Everything is included by default. Use the options to limit it:

What is included

• One artisan command, cartographer:erd, that writes a Markdown file with a mermaid fence, a raw .mmd file, or a rendered svg or png.
• Model discovery across configured paths, with glob patterns so modular and DDD layouts work.
• Named groups in config, each written to its own committed diagram beside the main one, with cross-group relations kept as edges to stub entities.
• --only, --except, --models, and --depth for scoping a single run without touching the committed files.
• cartographer:check, a CI command that fails when a committed diagram no longer matches your models and schema.
• Image export through a locally installed mermaid-cli, with a light and a dracula preset, three font stacks, and your own named presets.
• A warning when a diagram crosses the size limits hosted Mermaid renderers enforce, so you find out on the run that caused it.

Splitting a big app into groups

One diagram of a hundred tables is a wall, and past a certain size no hosted renderer will draw it at all. Name the subsets your team actually talks about, and each one gets its own committed diagram:

A bare php artisan cartographer:erd now writes the full diagram plus one file per group, derived from the main output path: docs/erd.md gives docs/erd/billing.md and docs/erd/catalog.md. Give a group an output key to place its file elsewhere. --group=billing regenerates one on its own, and cartographer:check covers every group alongside the full diagram.

A relation that leaves a group keeps its edge, and the model on the far side is drawn as an empty box. You can see that an invoice belongs to a user without the billing diagram growing a copy of the user table:

For a one-off diagram that is not worth committing, --only and --except scope a single run without touching the group files. --only scopes the diagram the way a group does, stubs and all. --except removes those models entirely, on top of whatever exclude_models already drops.

See Diagrams per subsystem and Scoping a diagram.

Rendering to SVG or PNG

Text output is the default because it reviews well and every host draws it. When you need a picture instead, --format=svg and --format=png render one through a locally installed mermaid-cli:

mermaid-cli is never a dependency of this package. Cartographer looks for it at export.mermaid_cli, then in your project's node_modules/.bin/mmdc, then on your PATH, and tells you how to install it if none of those has one.

An export writes the rendered docs/erd.svg and the Mermaid source it came from at docs/erd.svg.mmd. The source is written beside the image because that is what cartographer:check compares: mermaid-cli output is not byte-stable between its own versions, so checking the image itself would report drift every time someone upgraded it. Checking never runs mermaid-cli, so CI can verify an exported diagram without installing node.

Two presets are built in, light and dracula, and --font swaps a preset's font stack for mono, sans, or Mermaid's own default. Define your own under themes and select it by name exactly like a built-in. Themes never enter the Mermaid source: they are passed to the renderer at export time, so committed Markdown stays theme-neutral and GitHub keeps theming it to whatever the reader has chosen.

See Exporting images and Themes and fonts.

Keeping it honest in CI

A committed diagram is only useful while it is true. cartographer:check regenerates everything your config declares, compares it against the files on disk, and exits 1 listing each stale or missing file with a short diff and the command that fixes it:

It writes nothing, so it is safe on a read-only checkout. The diagram is built from your database structure, so the check needs a migrated database in the same way your test suite does:

--group=billing checks one group and --connection= picks the connection. Use --group to split the check across CI jobs, never as the only check: a bare cartographer:check is what proves every committed file is current.

See Continuous integration.

Configuration

The published config/cartographer.php documents every key inline.

Full defaults and validation rules are in the configuration reference.

Important behavior

• Output is deterministic. Tables, columns, and edges are always emitted in the same order, so the committed ERD only changes when your schema or models do.
• Relations are found by invoking model methods. Cartographer instantiates each model and calls its public zero-argument methods inside a guard, keeping the ones that return a Relation. Building a relation object does not run a query. If your models have zero-argument methods with side effects, either exclude those models or turn on strict_types_only and type your relation methods.
• A diagram is never trimmed to fit. GitHub, GitLab, and the Mermaid live editor cap what they will draw at 50,000 characters of source and 500 edges. Past either one, the command warns and still writes the full file. The warning never changes the exit code. --columns=keys, groups, and --format=svg are the ways out, cheapest first.
• Themes apply to images only. Passing --theme or --font to a text format is a no-op with a notice, not an error, so a scripted run stays portable across formats.
• An export is checked through its source, never its bytes, and the size limits do not apply to one: you supply the renderer configuration, so an export succeeds on diagrams GitHub refuses to draw.
• --stdout writes the diagram and nothing else. Warnings are suppressed so the stream stays pipeable, and an image export writes no source file.

Documentation

• Introduction
• Installation and setup
• Quick start
• How a diagram is built
• Model discovery
• Relationship detection
• Schema introspection
• Scoping a diagram
• Diagrams per subsystem
• Exporting images
• Themes and fonts
• Renderer limits
• Keeping the diagram current
• Continuous integration
• Configuration
• Console commands
• Diagram syntax
• PHP API
• Testing
• Troubleshooting

Development

The local checks mirror CI:

PHPStan runs at max with no baseline. Tests use SQLite locally and run against MySQL and PostgreSQL in CI. tests/SurfaceTest.php pins the public class list, and the snapshots under tests/.pest/ pin the rendered diagram output. A failure in either is asking whether you meant to change what users see. See CONTRIBUTING.md.

workbench/ is a bootable demo application with a schema that exercises every relation type the detector supports. composer build sets it up and composer serve runs it.

Out of scope

Things this package will not do, so you can decide quickly whether it fits:

• Parse migration files. Migrations are history, not a schema. The database structure is the single source of truth.
• Read table data. No query ever runs against your rows. Introspection reads structure only.
• Support Laravel 11 or older. Laravel 11 no longer receives security patches. Laravel 10 and older also need doctrine/dbal for introspection, which is a permanent second code path for end-of-life framework versions.
• Support ORMs other than Eloquent.
• Ship a renderer. Image export shells out to a mermaid-cli you install. The package will not vendor node, a browser, or a Mermaid build.
• Add routes, pages, or anything browser-facing to your app. Cartographer is an artisan command that writes files.

Versioning

The package follows semantic versioning.

• Upgrading within 1.x is safe. Nothing you use will break.
• Only a new major version, like 2.0.0, can break your code.
• If the README or the documentation describes it, it is safe to build on. If they don't, treat it as internal and expect it to change.

One deliberate exception: the exact layout of the generated diagram is not covered. Cardinality notation, edge labels, and column ordering may be refined in a minor release, which will show up as a diff in your committed ERD the next time you regenerate it. Determinism is guaranteed, so a given schema always produces the same file on a given version, but the rendering itself is free to improve. Anything that moves lines gets a changelog entry.

Bug fixes go into the newest version only. To get a fix, upgrade to it.

Questions and issues

• Stuck, or have an idea? Start a discussion. Usage questions and feature ideas both live there.
• Found a bug you can reproduce? Open an issue. A failing test is the fastest way to a fix, and a short reproduction is the next best thing.
• Found a security problem? Please don't open a public issue. See SECURITY.md for how to report it privately.
• Planning a pull request? CONTRIBUTING.md covers the setup and the three checks it needs to pass.

This package is maintained by one person, so replies can take a while. Everything gets read.

License

MIT. See CHANGELOG.md.