Console commands.

The package registers two commands.

Both are registered only when the application is running in the console, and both resolve their settings through the same code, so the check can never disagree with the diagram it checks.

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 --group=billing
php artisan cartographer:erd --format=svg --theme=dracula
php artisan cartographer:erd --connection=reporting

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

What a bare run produces

With no options, the command regenerates everything the config declares: the main diagram, then each configured group in config order.

Narrowing the run turns that off. Passing --models, --depth, --only, --except, --output, or --stdout produces one diagram and leaves the group files untouched, because a narrowed run is not what the group files are. --group is the exception: it produces exactly that group's file.

--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.

--group

php artisan cartographer:erd --group=billing

Renders one configured group to its own configured path. A group is already a scope and already names its destination, so it cannot be combined with the options that would fight it:

   ERROR  A group is already a scope, so [--group] cannot be combined with
          [--only], [--except], [--models] or [--depth].

   ERROR  A group writes to its own configured path, so [--group] cannot be
          combined with [--output].

   ERROR  Unknown group [invoicing]. Configured groups: billing, catalog.

With no groups configured at all, the last message ends Configured groups: none.

--only

php artisan cartographer:erd --only=Order,Invoice
php artisan cartographer:erd --only='App\Models\Order'

Scopes the diagram to these models the way a group does. A relation leaving the set keeps its edge, and the model on the far side is drawn as a stub entity with no columns.

--except

php artisan cartographer:erd --except=Telemetry
php artisan cartographer:erd --except=Telemetry,AuditLog

Removes these models from the run entirely. Nothing is stubbed, and their edges go with them. It composes with exclude_models rather than replacing it: a model named either way is out.

Excluding everything fails rather than writing an empty diagram:

   ERROR  Every discovered model was excluded. Check [--except] and [cartographer.exclude_models].

--only and --except accept short and fully qualified names, like --models.

--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  Column mode 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
php artisan cartographer:erd --format=svg

Anything else fails:

   ERROR  Format must be one of: markdown, mmd, svg, png.

svg and png render through a locally installed mermaid-cli and replace the output extension with the format. See exporting images.

--theme and --font

php artisan cartographer:erd --format=svg --theme=dracula
php artisan cartographer:erd --format=png --theme=dracula --font=sans

Built-in themes are light and dracula, plus anything under cartographer.themes. Font stacks are mono, sans, and default.

Both apply to svg and png only. Passing either to a text format is a no-op with a notice, not an error, so a scripted run stays portable across formats:

   INFO  Themes and fonts apply to svg and png exports only. Text output stays
         theme-neutral so GitHub and GitLab can theme it themselves.

An unknown name fails, but only on a run that actually renders an image:

   ERROR  Unknown theme [solarized]. Available themes: dracula, light, midnight.
   ERROR  Unknown font [comic]. Available fonts: mono, sans, default.

See themes and fonts.

--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, so an interrupted run leaves the previous diagram intact.

An svg or png run replaces the extension with the format, so --format=svg --output=docs/erd.md writes docs/erd.svg. That is what stops image bytes landing in a file named .md.

Ignored when --stdout is passed, and rejected alongside --group.

--stdout

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

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.

An image export under --stdout writes the rendered artifact and no source file, so it is for one-off piping rather than for something you commit.

--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

One summary line per diagram written:

   INFO  Generated 9 entities and 18 edges. Written to [/srv/blog/docs/erd.md].
   INFO  Generated 5 entities and 6 edges for group [billing]. Written to [/srv/blog/docs/erd/billing.md].

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

   WARN  Model discovery path matched no directories: /srv/blog/src/Domain/*/Models
   WARN  Skipping model [App\Models\Ghost]: table [missing_ghosts] does not exist.
   WARN  The diagram is 63,412 characters, over the 50,000 character limit ...

Warnings never fail the run. They mean the diagram is smaller, or larger, than you may have expected, which the counts in the summary line confirm.

Discovery warnings are printed once for the whole run rather than once per group, so a set of five diagrams does not repeat the same unmatched path five times.

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

Exit codes

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

• An invalid option or config value, including a bad --columns, --format, --depth, --theme, or --font.
• --group combined with a scope option or --output, or naming a group that is not configured.
• No discovered models at all, or every discovered model excluded.
• An unknown, ambiguous, or table-less seed model.
• A connection that cannot be opened or introspected.
• An output path that cannot be written.
• A missing, unusable, failing, or timed-out mermaid-cli on an image export.

It does not fail on a skipped model, an unmatched discovery path, or a crossed renderer limit. All three warn and continue, which is what makes a glob for optional modules safe and what keeps a large diagram writable.

cartographer:check

php artisan cartographer:check
php artisan cartographer:check --group=billing
php artisan cartographer:check --connection=reporting

Regenerates every diagram the config declares, compares each against the file on disk, and reports all of them. It writes nothing, so it is safe on a read-only checkout.

There are no scope or format options on purpose. The check verifies what your configuration says should be committed, and a flag that changed what gets generated would let the check pass against something other than the committed set.

How each file is compared

An image is compared through its source because mermaid-cli output is not byte-stable between its own versions, so comparing the bytes would report drift on every renderer upgrade. It also means the check never runs mermaid-cli. See exporting images.

A file that was never generated counts as stale, not as an error. The fix is the same command either way.

What it prints

   INFO  3 diagram(s) up to date.

   ERROR  Stale: [/srv/app/docs/erd.md].
--- committed
+++ generated
@@ -14,1 +14,2 @@
-        bigint author_id FK
+        bigint author_id FK
+        bigint editor_id FK

   ERROR  Missing: [/srv/app/docs/erd/catalog.md].
   ERROR  2 of 3 diagram(s) out of date. Regenerate with: php artisan cartographer:erd

The diff is short by design: both sides come from the same renderer, so their differences cluster, and the shared head and tail are trimmed. It shows up to eight lines per side. It is there to tell you what moved, not to replace git diff on the regenerated file.

The closing line is an error rather than a warning, because on a failing run the instruction that fixes it belongs on the same stream as the failures it explains.

Exit codes

0 when every declared file matches. 1 when any is stale or missing, and on the failures that prevent a comparison: an invalid option or config value, an unknown group, an unreachable connection, and no discovered models.

A crossed renderer limit never fails the check. A diagram too large for GitHub to draw is still a correct diagram, and the file on disk still matches.

What to read next

• Configuration for the keys these options override.
• Continuous integration for cartographer:check in a pipeline.
• Troubleshooting for what each message means.