byrcsc/laravel-cartographer · 1.x

Installation and setup.

Install the package as a dev dependency, publish the config file, point it at your model directories, and confirm the command can reach a migrated database.

Install the package

composer require --dev byrcsc/laravel-cartographer

Install it as a dev dependency. The package registers one Artisan command and nothing else — no routes, no middleware, no migrations, no runtime code path. Production never needs it.

The service provider is discovered automatically. It registers cartographer:erd only when the application is running in the console.

Publish the config file

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

That writes config/cartographer.php. Publishing is optional: the package merges its own defaults, so the command works without it. Publish when you need to change the model paths, the output location, or any of the exclusions.

Every key is documented in configuration.

Point it at your models

The one key most applications change is paths. It defaults to a single directory:

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

Globs are expanded, so modular and domain-driven layouts work without listing each module:

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

Each entry must match at least one directory. A path that matches nothing produces a warning and is skipped, rather than failing the run. Matched directories are scanned recursively.

Make sure a database is reachable

Cartographer reads structure from a live connection, so the command needs a database it can introspect, and that database has to be migrated:

php artisan migrate
php artisan cartographer:erd

A local development database is the normal target. Any connection works — --connection= picks one per run, and cartographer.connection sets a default.

Two consequences are worth knowing before you wire this into anything:

A model whose table is missing is skipped with a warning, not drawn from the model definition. An unmigrated database produces a diagram missing the tables that were never created.
The connection only needs permission to read schema metadata. Nothing the package runs selects from your tables.

Generate a first diagram

php artisan cartographer:erd

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

The default output path is docs/erd.md, relative to the project root. The directory is created if it does not exist.

To see the diagram without writing anything:

php artisan cartographer:erd --stdout

Commit the output

The generated file is meant to be committed. Determinism is the reason it is worth committing: the same models and the same schema always produce a byte-identical file, so the diff only moves when the application does.

git add docs/erd.md
git commit -m "docs: add generated ERD"

Keeping the diagram current covers when to regenerate, and continuous integration covers failing a build when the committed diagram falls behind.