Catraca Laravel Package

Getting Started

Catraca is a ratchet, not a linter. It does not find problems itself — it consumes the output of tools you already run (PHPStan/Larastan, PHPUnit/Pest coverage, phpcpd, PHPMD, etc.) and fails the build when a metric gets worse than the last accepted value. Think of it as a composer.lock for code quality: a committed file that records the current debt level and only allows it to shrink.

1. Install as a dev dependency

composer require --dev b7s/catraca

2. Bootstrap the ratchet file

vendor/bin/catraca --help          # confirm available verbs first
vendor/bin/catraca init            # writes catraca.yml / config + baseline

The docs on the repo are thin, so --help and the README schema section are your first stops. Verify the exact subcommand names (init, check, update/ratchet) before scripting them into CI — do not copy-paste command names from blog posts.

3. Pick exactly one metric for the first run

For a Laravel app the cheapest, highest-signal starting point is the PHPStan/Larastan error count:

vendor/bin/phpstan analyse --error-format=json > build/phpstan.json || true
vendor/bin/catraca check

4. Where to look first

• The generated catraca.yml — it is the whole contract; read it before touching anything else.
• The committed baseline/metrics file — that diff in a PR is the quality report.
• Your composer.json scripts block and .github/workflows/*.yml — this is where the package earns its keep.

First real use case: you inherit a Laravel app with 412 Larastan errors and 38% coverage. You wire Catraca in today, it records 412/38% as the ceiling, and from that moment every PR either improves those numbers or fails. No big-bang cleanup required.

Implementation Patterns

Baseline-as-lockfile (the core pattern). Commit the metrics file. Review its diff in code review the same way you review composer.lock changes. A PR that only touches the baseline file is a red flag; a PR that lowers the number alongside real refactoring is the goal.

Correct ordering in CI. Catraca must run after the tools whose reports it reads, and those tools must be allowed to finish even when they exit non-zero:

- run: vendor/bin/phpstan analyse --error-format=json --no-progress > build/phpstan.json || true
- run: php artisan test --coverage-clover=build/clover.xml || true
- run: vendor/bin/phpcpd app/ --log-pmd build/pmd-cpd.xml || true
- run: vendor/bin/catraca check

The || true is deliberate and is the single most common wiring mistake — with set -e the pipeline dies at PHPStan and Catraca never gets a chance to compare.

Laravel composer script so devs get the same gate locally:

"scripts": {
    "quality": [
        "@php vendor/bin/pint --test",
        "@php vendor/bin/phpstan analyse --error-format=json --no-progress",
        "@php vendor/bin/catraca check"
    ]
}

Use --continue-on-error style composition, or run Catraca as the last step of a script that tolerates earlier failures, so composer quality always reports the ratchet verdict.

The "deliberate improvement" workflow. Ratchets are two-phase:

1. Refactor / delete dead code / add tests in a normal PR.
2. In the same PR, run the update verb (vendor/bin/catraca update or equivalent — confirm from --help) to lock in the new, better numbers.

Never run the update verb on an unchanged codebase just to silence CI. That is the one anti-pattern that turns a ratchet into a rubber stamp.

Ratchet a Laravel-specific set, not everything at once. Sensible staged rollout:

Monorepo / multi-app. Keep one config per application root and invoke with --configuration=path/to/catraca.yml, or run the command once per package in a matrix. Don't share one baseline across packages — a win in app/ will mask a regression in packages/billing/.

Trend tracking. Because the metrics file is plain text in git, git log -p catraca.yml (or .catraca/) gives you a free, zero-infrastructure quality dashboard. Wire a small job to post the delta as a PR comment if you want it visible.

Gotchas and Tips

Pin the analyzer versions. A PHPStan minor upgrade routinely changes error counts (new rules, better inference). If Catraca compares against a stale baseline produced by PHPStan 1.x while CI runs 1.y, you get phantom regressions that have nothing to do with the PR. Pin phpstan/phpstan, larastan/larastan, and phpunit/phpunit in composer.lock and bump them in dedicated PRs that also update the ratchet file.

Coverage is non-deterministic. Parallel test runs, --order-by=random, and conditional @codeCoverageIgnore blocks all nudge the percentage. Ratchet coverage only if you can make it stable (single-process run for the measurement step, or a tolerance setting if the tool supports one). Otherwise start with error counts and duplication, which are exact.

Xdebug/PCOV presence changes coverage entirely. Coverage is 0% — or the file is missing — on a CI image without a coverage driver, which reads as a catastrophic regression. Assert the clover file exists before Catraca runs.

Paths must be stable. Reports containing absolute paths (/home/runner/work/...) will not match a baseline generated on a laptop. Generate reports with relative paths and run Catraca from the repo root.

Don't ratchet a legacy codebase with a red build. If PHPStan currently reports 400 errors, you cannot make the pipeline green by ratcheting — Catraca will hold the line at 400, and any PR touching unrelated code that shifts the count trips it. First make the underlying tool pass (phpstan-baseline.neon, @phpstan-ignore), then ratchet. Catraca guards against regression; it does not grant amnesty.

Protect the baseline file. Add a CODEOWNERS entry or a required reviewer for catraca.yml. The whole mechanism is only as trustworthy as the review of that file's diffs.

Local/CI drift. PHP version, loaded extensions, APP_ENV, and whether vendor/ was installed with --no-dev all change analyzer output. Run composer quality inside the same container image CI uses, or expect "works on my machine" ratchet failures.

CI exit-code plumbing. Catraca's value is the non-zero exit on regression. Make sure your workflow step is not marked continue-on-error: true at the job level, or the gate silently disappears.

Escape hatch for emergencies. Know how to bypass the check (--no-check style flag, or disabling the step) and treat each use as a tracked incident. If a team bypasses it more than once a quarter, the ratchet is set too aggressively.

Maintenance risk. At 20 stars with a single maintainer, treat this as a small, replaceable tool. Pin an exact version, and keep in mind that the failure mode is graceful: if the project stalls, equivalent behavior is achievable with phpstan --fail-on-warning, a committed PHPStan baseline, and a Codecov coverage threshold. Don't let it become load-bearing infrastructure you cannot swap out.

Extension points. Check whether the package exposes a metric/collector interface for custom measurements (e.g. counting TODO comments, counting DB::raw occurrences). If it does, that is the cleanest way to ratchet project-specific rules that no off-the-shelf analyzer covers — and it beats writing another bespoke CI script.