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'],
        ],
    ],

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

Reference

Three keys have no command option: paths, exclude_models, and columns.exclude. They describe the application rather than a single run.

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

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

Any other value fails the command:

   ERROR  Format must be one of: markdown, mmd.

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

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:

What to read next

• Console commands for the options that override these keys.
• Model discovery for paths and exclude_models in depth.
• Troubleshooting for what to do about each message.