Configuration.

php artisan vendor:publish --tag=cartographer-config

Publishing is optional. The package merges its own defaults, so every key below has a value whether or not config/cartographer.php exists.

return [
    'paths' => [
        app_path('Models'),
    ],

    'exclude_models' => [
        // App\Models\Telemetry::class,
    ],

    'connection' => null,

    'output' => 'docs/erd.md',

    'format' => 'markdown',

    'columns' => [
        'mode' => 'all',
        'exclude' => [
            // App\Models\User::class => ['remember_token'],
        ],
    ],

    'export' => [
        'mermaid_cli' => null,
        'theme' => 'light',
        'font' => null,
    ],

    'themes' => [
        // 'midnight' => [
        //     'themeVariables' => ['background' => '#11131a'],
        //     'font' => 'sans',
        // ],
    ],

    'groups' => [
        // 'billing' => [App\Models\Invoice::class],
    ],

    'limits' => [
        'max_text_size' => 50000,
        'max_edges' => 500,
    ],

    'relations' => [
        'exclude' => [],
        'strict_types_only' => false,
    ],
];

Reference

Keys with no command option describe the application or the committed set rather than a single run: paths, exclude_models, columns.exclude, export.mermaid_cli, themes, groups, and both limits keys.

groups is the near miss. --group picks one of the configured groups for a run, but it cannot define one, because a group is a committed file and a file that exists only when someone remembers a flag is the problem groups solve.

Every key is defaulted at the leaf, so a config/cartographer.php published before a key existed merges cleanly and the missing key takes its packaged default. There is no need to republish the file after an upgrade unless you want the new comments.

Options that have a config key replace it rather than merging with it. --exclude-relations=morph ignores relations.exclude entirely for that run.

paths

'paths' => [
    app_path('Models'),
    base_path('src/Domain/*/Models'),
],

Each entry is expanded with glob() against directories, and each matched directory is scanned recursively for .php files. A pattern matching no directory warns and is skipped; discovering no models at all fails the command.

Full behaviour in model discovery.

exclude_models

'exclude_models' => [
    App\Models\Telemetry::class,
    App\Models\PasswordReset::class,
],

Excluded models produce no entity and no edges, and relations pointing at them are dropped. Every entry must be a loadable Eloquent model class name; anything else fails the command.

Use it for models with side-effecting methods, and for tables that are noise in a diagram, token tables, job tables, audit logs.

connection

'connection' => null,

null means the application's default connection. A string names a connection from config/database.php. Empty strings are rejected.

--connection= overrides it per run. Only one connection is read per run; see schema introspection.

output

'output' => 'docs/erd.md',

A relative path is resolved against the project root. An absolute path, Unix style, UNC, or a Windows drive letter, is used as given. Missing directories are created.

The file is written through a temporary file in the destination directory and moved into place, so an interrupted run leaves the previous diagram intact. --stdout skips writing entirely and ignores this key.

format

'format' => 'markdown',

For the two text formats the key controls the content, not the file extension. Set output to match the format you chose; nothing renames the file for you.

The two image formats are the exception: they replace the output extension with the format, so format => 'svg' on the default docs/erd.md writes docs/erd.svg. That is what stops image bytes landing in a file named .md. They also need a locally installed mermaid-cli, which is never a dependency of this package. See exporting images.

Any other value fails the command:

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

columns.mode

'columns' => [
    'mode' => 'all',
],

The "nullable" comment appears in all mode only. In keys mode the marker is the information, and repeating nullability alongside it adds width without adding meaning.

Any other value fails the command:

   ERROR  Column mode must be one of: all, keys, none.

columns.exclude

'columns' => [
    'exclude' => [
        App\Models\User::class => ['remember_token', 'two_factor_secret'],
        App\Models\Payment::class => ['gateway_payload'],
    ],
],

Hides named columns on the entity belonging to that model. Use it for secrets you would rather not name in a committed file, and for wide serialized columns that push the diagram sideways.

Three limits:

• It is keyed by model class, not by table name. Pivot tables have no model, so their columns cannot be excluded this way.
• Excluding a column does not remove its edges. The relation comes from the model, not the column.
• It applies to all and keys mode alike, so an excluded primary key disappears from both.

The value must map loadable model classes to arrays of non-empty column names; anything else fails the command.

export

'export' => [
    'mermaid_cli' => null,
    'theme' => 'light',
    'font' => null,
],

Everything under this key applies to the svg and png formats only. A text run ignores all three, which is what keeps a scripted --theme portable across formats.

mermaid_cli is a path to the renderer. null searches node_modules/.bin/mmdc in your project and then your PATH; a string stops the search and uses that binary, failing if it is missing or not executable.

theme names a preset, built-in or one of your own from themes. font is mono, sans, default, or null to keep whatever font the preset carries.

Both names are resolved only on a run that renders an image, so a typo surfaces the first time you export rather than on every command. Details in themes and fonts.

themes

'themes' => [
    'midnight' => [
        'themeVariables' => [
            'background' => '#11131a',
            'textColor' => '#e6edf3',
        ],
        'font' => 'sans',
    ],
],

Your own export presets, selectable by name exactly like the built-in light and dracula. themeVariables is required and passed to Mermaid as given; font is optional and defaults to mono.

Reusing a built-in name replaces it outright rather than merging into it, so a preset named light becomes the light theme for every run, including ones that never pass --theme.

Themes never enter the emitted Mermaid, so committed Markdown stays theme-neutral and hosted renderers keep theming it for the reader. Full behaviour in themes and fonts.

groups

'groups' => [
    'billing' => [App\Models\Invoice::class, App\Models\Payment::class],
    'catalog' => [
        'models' => [App\Models\Product::class],
        'output' => 'docs/catalog-erd.md',
    ],
],

Named subsets that each get their own committed diagram. A bare cartographer:erd writes the main diagram plus one file per group, and cartographer:check covers them all.

Both forms shown are accepted: a bare list of model classes, or an array with a models key and an optional output. Without output, a group's file lands beside the main diagram in a directory named after it, so docs/erd.md gives docs/erd/billing.md.

A relation leaving a group keeps its edge, with the model on the far side drawn as an empty stub entity. Each group must list at least one model. Full behaviour in diagrams per subsystem.

limits

'limits' => [
    'max_text_size' => 50000,
    'max_edges' => 500,
],

The limits hosted Mermaid renderers enforce. The defaults match what GitHub, GitLab, and the Mermaid live editor accept.

Crossing one produces a warning and nothing else. The diagram is never trimmed to fit, the file is written unchanged, and the exit code does not move. Set either key to null to switch that check off, which is right when you render with your own Mermaid configuration and have raised its limits.

Each value must be null or a positive integer. The limits are not applied to an image export at all, because Cartographer supplies the renderer configuration there and raises both. Details in renderer limits.

relations.exclude

'relations' => [
    'exclude' => ['through'],
],

Relation types to leave out, matched against the type names in relationship detection, plus the group aliases through and morph. Values are trimmed and lowercased, and hyphens and spaces become underscores.

--exclude-relations replaces this key for the run it is passed on.

relations.strict_types_only

'relations' => [
    'strict_types_only' => false,
],

When true, only methods declaring a Relation return type are invoked. When false, every public zero-argument method declared on the model is invoked and the return value is checked.

Off by default so untyped codebases work unchanged. Turn it on when your relation methods are typed: it makes generation cheaper and stops zero-argument methods with side effects from running. The cost is that an untyped relation method is skipped silently.

The value must be a boolean; a string 'true' fails the command.

Validation

Configuration is validated when the command runs, not at boot. Every failure prints one message and exits 1:

Two more come from resolving an export, and only on a run that renders one:

What to read next

• Console commands for the options that override these keys.
• Diagrams per subsystem for groups in depth.
• Themes and fonts for export and themes in depth.
• Troubleshooting for what to do about each message.