byrcsc/laravel-cartographer · 1.x

Console commands.

The cartographer:erd command, every option with its default and the config key it overrides, what the command prints, and what its exit code means.

The package registers one command.

Command	What it does
`cartographer:erd`	Generate a Mermaid entity relationship diagram and write it out

It is registered only when the application is running in the console.

cartographer:erd

php artisan cartographer:erd
php artisan cartographer:erd --stdout
php artisan cartographer:erd --models=Post --depth=1 --columns=keys
php artisan cartographer:erd --format=mmd --output=docs/erd.mmd
php artisan cartographer:erd --connection=reporting

Option	Default	Config key	Effect
`--models=`	all models	—	Comma-separated seed models to focus on
`--depth=`	unlimited	—	Relationship hops to follow from the seeds
`--columns=`	`all`	`cartographer.columns.mode`	Column detail: `all`, `keys`, or `none`
`--exclude-relations=`	none	`cartographer.relations.exclude`	Comma-separated relation types to leave out
`--format=`	`markdown`	`cartographer.format`	`markdown` or `mmd`
`--output=`	`docs/erd.md`	`cartographer.output`	Where the file is written
`--stdout`	off	—	Print the diagram instead of writing a file
`--connection=`	default connection	`cartographer.connection`	Which database connection to introspect

An option that has a config key replaces it for that run, rather than merging with it.

--models

php artisan cartographer:erd --models=Post
php artisan cartographer:erd --models=Post,Invoice
php artisan cartographer:erd --models='App\Models\Post'

Short class names and fully qualified names both work. Quote the fully qualified form so the shell leaves the backslashes alone. Blank entries are ignored, so a trailing comma is harmless.

With no seeds, every discovered model with a table is included. Details in scoping a diagram.

--depth

php artisan cartographer:erd --models=Post --depth=0
php artisan cartographer:erd --models=Post --depth=2

Hops to follow outward from the seeds. 0 is the seeds alone; omitting the option follows every reachable edge. Direction is ignored — an edge is traversable from either end.

--depth with no --models has no effect: with no seed to measure from, the whole graph is produced.

The value must be zero or a positive integer:

   ERROR  Depth must be zero or a positive integer.

--columns

php artisan cartographer:erd --columns=keys

all emits every column with "nullable" where it applies, keys emits only PK, FK, and UK columns, none emits entity names with no column block. Anything else fails:

   ERROR  Columns must be one of: all, keys, none.

--exclude-relations

php artisan cartographer:erd --exclude-relations=through
php artisan cartographer:erd --exclude-relations=morph,belongs_to_many

Accepts exact type names, plus the group aliases through and morph. Values are trimmed and lowercased, and hyphens and spaces become underscores.

Passing the option with an empty value clears relations.exclude for that run.

--format

php artisan cartographer:erd --format=mmd

markdown wraps the diagram in a mermaid fence under a generation comment. mmd emits the bare erDiagram block. Anything else fails:

   ERROR  Format must be one of: markdown, mmd.

--output

php artisan cartographer:erd --output=docs/schema/erd.md
php artisan cartographer:erd --output=/srv/shared/erd.md

Relative paths resolve against the project root; absolute paths are used as given. Missing directories are created. The write goes through a temporary file in the destination directory and is moved into place.

Ignored when --stdout is passed.

--stdout

php artisan cartographer:erd --stdout
php artisan cartographer:erd --stdout --format=mmd > docs/erd.mmd

Prints the diagram and writes no file. Warnings and the summary line are suppressed, so the output is safe to pipe. If you are debugging discovery, run without --stdout to see the warnings.

--connection

php artisan cartographer:erd --connection=reporting

Names a connection from config/database.php. Omitted, the command uses cartographer.connection, and then the application's default connection.

What it prints

On success, one summary line:

   INFO  Generated 9 entities and 18 edges. Written to [/srv/blog/docs/erd.md].

Warnings come before it, one per skipped model or unmatched path:

   WARN  Model discovery path matched no directories: /srv/blog/src/Domain/*/Models
   WARN  Skipping model [App\Models\Ghost]: table [missing_ghosts] does not exist.

Warnings never fail the run. They mean the diagram is smaller than you may have expected, which the entity count in the summary line confirms.

Under --stdout, neither warnings nor the summary are printed — only the diagram.

Exit codes

0 on success, 1 on failure. The command fails on:

An invalid option or config value, including a bad --columns, --format, or --depth.
No discovered models at all.
An unknown, ambiguous, or table-less seed model.
A connection that cannot be opened or introspected.
An output path that cannot be written.

It does not fail on a skipped model or an unmatched discovery path. Both warn and continue, which is what makes a glob for optional modules safe.