- What is b7s/catraca and how does the ratchet principle work?
- Catraca is a PHP quality guardian that enforces a ratchet: your quality metrics can improve or stay the same, but they can never regress. It freezes a numeric watermark for metrics such as test coverage, duplication or analyser error counts, and fails the build when a change pushes a metric in the wrong direction. It is a build-time, dev-only tool installed with require-dev, so it adds zero runtime footprint to your Laravel application. Think of it as a lock that only turns one way for code quality.
- How do I install b7s/catraca in a Laravel application?
- Install it as a dev dependency with composer require --dev b7s/catraca, commit the generated config file at the repository root, and add a single Catraca step to your CI pipeline. The lowest-friction trial is roughly a half-day spike: prove the exit-code behaviour and metric capture against a real application before making it a blocking gate. Mirror the exact same invocation in a composer quality script so local runs and CI produce identical results.
- Which PHP and Laravel versions does b7s/catraca support?
- The package targets modern stacks, with Laravel 10, 11 and 12 on PHP 8.2 or newer being the intended fit. It is framework-agnostic by nature, so the same gate can be reused across side packages, CLI tools and legacy PHP services in a multi-repo estate. Version support can change between releases, so check the composer.json constraints and Packagist metadata for the exact release you plan to pin, and verify the tag list against Packagist before adoption.
- Does Catraca run PHPStan, PHPCS and Pest, or does it read their reports?
- This is the first question to settle before committing, because it determines both CI cost and failure surface. If Catraca re-executes the analysers, its effective version is bound to your composer.lock; if it consumes their machine-readable reports, the report format becomes the contract you depend on. Confirm which model applies, then pin those analyser versions so a patch bump cannot silently turn the gate red on unchanged code.
- Where does Catraca store the quality watermark, and should I commit it?
- The watermark lives in a human-readable config file committed at the repository root, which is exactly what makes the gate reviewable. Commit it and protect it with CODEOWNERS, because every hard gate invites the cheapest workaround: editing the ratchet file itself. Without review rules on that file the control degrades into theatre within a couple of quarters. Also plan for merge conflicts on that file when several pull requests land at once.
- How do I re-baseline Catraca after a deliberate refactor or dependency upgrade?
- Deliberate metric changes such as a refactor, a framework upgrade or a new analyser minor version should go through an explicit re-baseline pull request that updates the watermark with a reviewer assigned. Keep that PR separate from feature work so the diff is auditable and obviously intentional. Pin your analyser versions and document a re-baseline procedure, otherwise false regressions become the day-to-day failure mode.
- Does Catraca support per-directory scoping or changed-files-only checks?
- Per-directory scoping and a no-worse-than-baseline check on changed files are the two capability questions that decide whether Catraca fits a large legacy Laravel codebase or only a small greenfield one. Whole-repo totals are a poor fit for big applications where regressions are usually local to one module. Confirm whether your target release supports per-directory scope before you rely on it as a release gate.
- Can Catraca be a blocking gate in CI, and what do the exit codes mean?
- It can serve either as an advisory step or as a blocking gate; the deciding factors are distinct exit codes for pass, regression and tool error, plus machine-readable output such as JSON or SARIF for PR annotations. Place it as the last quality step before merge, after lint and static analysis, so cheaper failures surface first. Confirm that a tool error is distinguishable from a genuine regression before you block releases on it.
- How is Catraca different from PHPStan and PHPCS baselines?
- Baselines and ratchets solve different problems and are complementary rather than duplicates. PHPStan and PHPCS baselines suppress a fixed set of pre-existing findings so you can adopt the tools on legacy code; a ratchet freezes a numeric watermark and fails on drift so the codebase cannot slowly decay afterwards. Most teams need both: a baseline to make adoption possible, and Catraca to keep the trend moving in one direction.
- Is b7s/catraca actively maintained and safe to depend on?
- Treat it as an unowned third-party dependency: the project is small, single-maintainer and has a low star count, so bus factor and release cadence are the dominant risks. That is acceptable for an advisory gate but risky as a hard release blocker without an exit plan. Because it is dev-only with zero runtime footprint, removing it later is cheap, as no request lifecycle, container bindings or deployment artifacts are affected. Check maintainer responsiveness on issues and verify the last release date against the tag list before pinning.