Keeping the diagram current.

A committed diagram is only useful while it is true. The cheapest way to keep it true is to regenerate it in the same step that changes the schema, so the diff lands in the pull request that caused it.

When to regenerate

Regenerate after anything that changes either input:

Nothing else moves the file. Rewriting a controller, adding a scope, or reformatting a model changes nothing, because neither input changed.

Regenerate with your migrations

Bind the two together in a Composer script so migrating locally always refreshes the diagram:

{
  "scripts": {
    "migrate": ["@php artisan migrate", "@php artisan cartographer:erd"],
    "erd": "@php artisan cartographer:erd"
  }
}

composer migrate

Do not add cartographer:erd to a deployment script. Production has no reason to write into the repository, and the package is a dev dependency that will not be installed there.

Review the diff

The point of committing the file is the diff:

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

     posts {
         bigint author_id FK
+        bigint editor_id FK
         text body "nullable"

Read the diff as a second opinion on the migration. A new FK marker that you did not intend, an edge that disappeared because a relation method was renamed, an entity that vanished because a table was dropped, each of those shows up here before it shows up in production.

An empty diff after a schema change means the change did not reach the database you generated against. Check that the migration ran on the connection Cartographer is reading.

Ask whether it is current

cartographer:check answers that question without writing anything:

php artisan cartographer:check

   INFO  3 diagram(s) up to date.

   ERROR  Stale: [/srv/app/docs/erd.md].
--- committed
+++ generated
@@ -14,1 +14,2 @@
-        bigint author_id FK
+        bigint author_id FK
+        bigint editor_id FK

   ERROR  1 of 3 diagram(s) out of date. Regenerate with: php artisan cartographer:erd

It covers everything your config declares, the main diagram and every group, so it catches the file you forgot rather than the one you remembered to look at. Run it locally when you are not sure, and in CI where it belongs permanently.

Catch a stale diagram before you push

A pre-commit hook keeps the file honest without anyone remembering:

#!/usr/bin/env bash
# .git/hooks/pre-commit
set -euo pipefail

php artisan cartographer:erd
git add docs/erd.md docs/erd/

That regenerates and stages every diagram on every commit. It needs a reachable database, so it is the wrong choice for a team where not everyone runs one locally. In that case, prefer failing the build, see continuous integration.

A gentler variant checks instead of writing, and lets the developer decide:

#!/usr/bin/env bash
# .git/hooks/pre-commit
set -euo pipefail

php artisan cartographer:check

For a shared hook that lives in the repository, point git at a tracked directory:

git config core.hooksPath .githooks

Multiple diagrams

If you generate a set, regenerate the whole set together. A script that produces some diagrams from today's schema and leaves others on last month's is worse than no diagrams.

Declaring the set as groups is what makes that automatic:

'groups' => [
    'billing' => [App\Models\Invoice::class, App\Models\Payment::class],
    'catalog' => [App\Models\Product::class],
],

A bare cartographer:erd regenerates every one of them, and cartographer:check verifies every one of them. There is no script to keep in sync and no flag to remember, which is the whole reason groups live in config rather than on the command line.

What a clean regeneration proves

Running the command twice with no changes leaves the working tree clean. That is worth knowing, because it means any diff at all is a real change to your models or your schema, never renumbering, reordering, or timestamp noise. The output carries no date and no version stamp for exactly this reason.

What to read next

• Continuous integration to fail a build on a stale diagram.
• Diagrams per subsystem for generating a set.
• Troubleshooting if a regeneration produces an unexpected diff.