Quick start.

This walkthrough creates a diagram for your current Laravel application. It assumes the package is installed and the database is migrated.

1. Generate the diagram

Run the command without options:

php artisan cartographer:erd

Cartographer reports how many entities and relationships it found:

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

An entity usually represents a model table. Cartographer also includes pivot tables used by many-to-many relationships, so the entity count can be higher than the model count.

2. Open the result

Open docs/erd.md. GitHub and GitLab render its Mermaid block as a diagram.

The file lists relationships first:

erDiagram
    categories ||--o{ posts : "posts"
    comments }o--|| posts : "post"
    posts }o--o{ tags : "tags"
    posts }o--|| users : "author"

The label at the end of each line is the Eloquent relation method. In this example, posts }o--|| users : "author" comes from Post::author().

Entity blocks list the table columns:

    posts {
        bigint author_id FK
        text body "nullable"
        bigint category_id FK "nullable"
        bigint id PK
        varchar title
    }

PK, FK, and UK mark primary keys, foreign keys, and unique keys. These markers come from the database schema.

3. Commit the file

Add the diagram to the same commit as the application change that produced it:

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

Cartographer sorts the output before writing it. If your models and database have not changed, running the command again leaves the file unchanged.

4. Check the diagram after a schema change

After running a new migration, regenerate the diagram and review the diff:

php artisan migrate
php artisan cartographer:erd
git diff docs/erd.md

The diff shows added or removed tables, columns, keys, and relationships.

You can also check the committed diagram without changing it:

php artisan cartographer:check

   INFO  1 diagram(s) up to date.

The command exits with code 1 when the diagram is missing or out of date. It does not write any files, so you can run it in CI.

What to read next

• Scoping a diagram to show one part of a large application.
• Diagrams per subsystem to save named scopes in the configuration file.
• Keeping the diagram current to regenerate it through Composer scripts or Git hooks.
• Continuous integration to add the check command to a build.
• Console commands to see every command option.