Gate your CI on architecture¶

By the end of this page, a pull request that adds a dead event, a dispatch loop or a new dispatch Loom can't resolve fails your build, and reviewers see what changed in a PR comment.

You need Loom installed as a dev dependency (composer require lucasp1337/laravel-loom --dev) and a repository on GitHub. The examples use an order and checkout app.

Run the gate locally first¶

Scan the branch, then check the index the scan wrote.

php artisan loom:scan
php artisan loom:check

Suppose a branch adds a stock-reservation listener that dispatches InventoryAdjusted, and a recount listener that handles it and dispatches OrderPlaced again. It also adds an unused OrderCancelled event, an untyped LegacyAudit listener, and a dispatch built from a variable. The check fails:

orphan-listeners — Every listener handles at least one event
  ✗ Listener App\Listeners\LegacyAudit handles no events.
orphan-events — Every event is dispatched or handled
  ✗ Event App\Events\OrderCancelled is never dispatched and never handled.
cyclic-dispatch — No cyclic event/job dispatch chains
  ✗ Cyclic dispatch: App\Events\InventoryAdjusted → App\Events\OrderPlaced → App\Events\InventoryAdjusted
3 violation(s) across 3 rule(s).

The dynamic dispatch isn't in that list: without a baseline, unresolved-dispatches is silent (next section). The command exited 1, and that exit code is the gate: a CI step that runs loom:check fails on any non-zero code. Each rule and what to do about it is in Check rules and output formats.

Stop new unresolved dispatches without fixing the old ones¶

A dispatch like event(new $eventClass()) can't be traced to a class, so Loom lists it under unresolved_dispatches instead of guessing. Your existing app probably has some, and you don't want to fix them all before turning the gate on.

loom:check on its own does not police them, even though the rule is listed in its output:

php artisan loom:check

All checks passed.

That was a scan with one unresolved dispatch in it. Give the rule a reference point, a baseline index from a known-good commit:

mkdir -p .loom
cp storage/loom/index.json .loom/baseline.json
git add .loom/baseline.json

Now the rule fails only on dispatches the baseline doesn't have. Here the baseline predates the dynamic event(new $eventClass()) line:

php artisan loom:check --baseline=.loom/baseline.json

unresolved-dispatches — No new unresolved dispatches (strict: none at all)
  ✗ Unresolved dispatch (dynamic_class_name) at app/Services/Checkout.php:14: event(new $eventClass())
1 violation(s) across 1 rule(s).

Once the count is zero, drop the baseline and use --strict, which fails on any unresolved dispatch:

php artisan loom:check --strict

See what changed¶

The check says whether the index is allowed. loom:diff says what moved between two indexes, which is what a reviewer wants to see.

php artisan loom:diff .loom/baseline.json storage/loom/index.json

unresolved_dispatches
  + {"file":"app/Services/Checkout.php","line":14,"expression":"event(new $eventClass())","reason":"dynamic_class_name"}

One + line means one new unresolved dispatch, and nothing else changed. The command exited 1 because changes exist. That is not an error: loom:diff follows git diff --exit-code, so 0 means no changes, 1 means changes, and 2 means it couldn't read an input.

Run both on every pull request¶

The repository ships a GitHub Action that scans the branch, runs loom:check, diffs against the base branch and posts one sticky PR comment. Add .github/workflows/loom.yml:

name: Loom
on: pull_request

permissions:
  contents: read
  pull-requests: write

jobs:
  loom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lucasp1337/laravel-loom@v0.4.0
        with:
          strict: "true"

pull-requests: write lets the action post the comment. strict: "true" fails the build on any unresolved dispatch. Orphans, cycles and schema errors always fail it.

The job is green when the check exits 0. It fails with the same exit code the check returned, and the PR comment lists the violations from the markdown format.

To fail the build on any architectural change, not just policy violations, add fail-on-diff: "true".

Inputs that make it fail¶

Use these to confirm the gate is wired up before you rely on it.

You're done when the first row turns your PR red and reverting it turns it green.