Installation and setup.

Cartographer runs during development and writes documentation files. It does not add runtime behaviour to your application.

1. Install the package

Install Cartographer as a development dependency:

composer require --dev byrcsc/laravel-cartographer

Laravel discovers the package automatically. The installation adds two Artisan commands: cartographer:erd and cartographer:check.

2. Prepare the database

Cartographer reads tables and columns from a database connection. Make sure your development database exists and has all migrations applied:

php artisan migrate

The connection only needs permission to read schema information. Cartographer does not read rows from your application tables.

If a model's table is missing, the command skips that model and prints a warning. Run all migrations before generating the diagram.

3. Configure custom model paths

Skip this step when your models live in app/Models.

Publish the configuration file when your models live elsewhere:

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

Update paths in config/cartographer.php:

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

Each path must point to a directory or match directories through a glob. Cartographer scans those directories recursively for model classes.

Publishing the configuration file is optional. The package uses its default settings when the file does not exist.

4. Verify the setup

Generate a diagram:

php artisan cartographer:erd

A successful run reports the output path:

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

The default path is docs/erd.md. Cartographer creates the directory when it does not exist.

If no models are found, check the configured paths. If models are skipped, confirm that the selected database is migrated.

Optional image renderer

The default Markdown output needs no renderer. GitHub and GitLab render its Mermaid block.

Install mermaid-cli only when you need SVG or PNG files:

npm i -D @mermaid-js/mermaid-cli

Cartographer finds node_modules/.bin/mmdc without extra configuration. See exporting images for image formats and renderer settings.

What it does not install

The package does not add routes, middleware, migrations, or browser-facing pages. It also does not install Node.js, a browser, or mermaid-cli.

What to read next

• Quick start to generate, review, and commit your first diagram.
• Configuration to change the output, columns, connection, or model paths.
• Model discovery to troubleshoot modular model layouts.