Catraca Laravel Package

Technical Evaluation

Architecture fit

• Catraca is a build-time, dev-only quality gate, not a runtime library. It belongs in the same tier as PHPStan, PHPCS, php-cpd and Pest coverage — require-dev, executed in CI and locally via a Composer script. Runtime footprint on the Laravel application is zero, so it does not touch the request lifecycle, container bindings, or deployment artifacts.
• Its concept (a ratchet: metrics may improve or hold, never regress) is complementary to, not a duplicate of, existing mechanisms. PHPStan/PHPCS baselines suppress a fixed set of pre-existing findings; a ratchet freezes a numeric watermark and fails on drift. Teams typically need both: baselines to make adoption possible, a ratchet to stop slow decay afterwards.
• It is framework-agnostic by nature, which is good for a Laravel shop with side packages, CLI tools and legacy PHP services — one gate, many repos.

Integration feasibility

• Low-friction trial: one composer require --dev line, a config file committed at repo root, one CI step. Realistically a half-day spike to prove exit-code behaviour and metric capture on a real application.
• The main coupling is not to Laravel but to the underlying analysers it wraps or reads (duplication, static analysis, coverage). If Catraca re-executes those tools, its effective version is bound to composer.lock; if it consumes their reports, the report format becomes the contract. This distinction must be confirmed before commitment — it determines both CI cost and failure surface.
• Exit-code semantics, machine-readable output (SARIF/JSON) and per-directory scoping are the three capability questions that decide whether it can be a blocking gate or only an advisory one.

Technical risk

• Maturity / bus factor. 20 stars and a single-maintainer profile is the dominant risk. Treat it as an unowned third-party dependency: acceptable as an advisory gate, risky as a hard release blocker without an exit plan.
• Version drift causing false regressions. A patch bump in PHPStan, php-cpd or the coverage driver can move the number and turn the gate red on unchanged code. This is the most likely day-to-day failure and must be designed around (pinned versions, re-baseline PR step).
• Human-factor erosion. Every hard gate invites the cheapest workaround: editing the ratchet file. Without review rules on that file (CODEOWNERS), the control degrades into theatre within two quarters.
• Release date sanity. The stated last release (2026-08-06) should be verified against the tag list and Packagist before adoption; a stale or inconsistent release signal changes the recommendation.

Key questions

1. Which metrics does it enforce (duplication %, cyclomatic complexity, coverage, PHPStan error count, PHPCS violations) and can a subset be enabled?
2. Does it run analysers or parse their output — and what does that imply for CI minutes and version pinning?
3. Where is the watermark stored, is it human-readable, and how does it behave on merge conflicts across concurrent PRs?
4. Does it support "no worse than baseline" on changed files only, or only whole-repo totals? Whole-repo-only is a poor fit for large legacy applications.
5. Are exit codes distinct (pass / regression / tool error), and is there machine-readable output for PR annotations?
6. What is the documented procedure for deliberately lowering a metric (refactor, dependency upgrade) and re-baselining?
7. PHP version support matrix, licence, and maintainer responsiveness on issues.

Integration Approach

Stack fit

• Target: Laravel 10/11/12 on PHP 8.2+, Composer-based, GitHub Actions or GitLab CI, with PHPStan/PHPCS/Pest already in require-dev. Catraca sits as the last quality step before merge, after lint and static analysis, so cheaper failures surface first.
• Canonical invocation pattern: a composer quality script that chains the analysers and Catraca, mirrored 1:1 by the CI job, so local and CI results agree. Divergence between the two is the fastest way to make a gate hated.
• For multi-repo estates, define a shared config preset (internal Composer package or a copied config) so thresholds do not drift per repository.

Migration path

1. Spike on one representative repository; capture current metric values and total runtime.
2. Shadow mode — wire into CI as a non-blocking step for two sprints, publishing the delta as a PR comment. This produces the evidence needed to set thresholds that do not instantly red-line the default branch.
3. Commit the watermark derived from the observed current state (slightly lenient to absorb tool noise).
4. Promote to blocking on pull requests only, not on the default branch and not on release tags.

Compatibility considerations

• Pin analyser versions in composer.lock and use the same PHP image locally and in CI; version skew between a developer's PHP and the CI runner is a common source of phantom regressions.
• Add the ratchet/baseline file to .gitattributes merge strategy guidance, or accept occasional manual conflict resolution in busy repos.
• Confirm behaviour on shallow CI clones and on partial checkouts — tooling that needs full history or full file sets will fail confusingly there.

Sequencing

• Phase 1 (week 1): spike + decision memo.
• Phase 2 (weeks 2–3): advisory gate in CI, one metric only (duplication or coverage floor — pick the one the team already argues about).
• Phase 3 (week 4–6): blocking gate on PRs, CODEOWNERS on the watermark file, runbook in CONTRIBUTING.md.
• Phase 4 (quarter 2): expand metric coverage; review whether the gate has ever caught a real regression, and prune if not.

Operational Impact

Maintenance

• Low but non-zero: one committed config plus one watermark file, both source-controlled. Expect one maintenance touch per quarter (tool upgrades, threshold review) plus an unplanned touch whenever an analyser bump shifts a number.
• Requires a named owner. Without one, the gate rots into a permanently red or permanently bypassed step — both worse than no gate.

Support

• No vendor support; community OSS only. An internal champion plus a short runbook ("gate is red — how to diagnose, how to legitimately re-baseline") is the whole support model.
• Escape hatch is cheap. The ratchet pattern is ~100 lines of scripting around the analysers' JSON output. Budget a two-day reimplementation as the contingency if the package stalls; this materially lowers the adoption risk and should be stated explicitly in the decision record.

Scaling

• Runtime is dominated by the wrapped analysers, not the wrapper. On a large monorepo, shard per package/domain and run the gate per shard; do not add it to pre-commit hooks if the pipeline exceeds a few seconds, or developers will --no-verify.
• Cost impact on CI minutes is modest and mostly attributable to analysers already running; the incremental cost is near zero if Catraca consumes existing reports rather than re-running tools.

Failure modes to design for

Ramp-up

• ~0.5 engineer-day to integrate and document; a 15-minute team briefing suffices because the concept is one sentence ("quality can improve, never regress").
• Cognitive load for developers is low provided the failure message states the metric, the old value, the new value, and the exact remediation command. Investing in that message is the single highest-leverage onboarding decision.

Bottom line for a TPM: adopt as a low-cost, advisory-first gate with a documented exit plan, not as untouchable release infrastructure. The integration cost is trivial and the ratchet concept addresses a real, recurring problem; the risk is concentrated entirely in the package's maturity and in organisational discipline around the watermark file.