README

A CI quality gate for method-level change risk in PHP projects.

Why this tool exists

Complex code with low test coverage is risky to change. The CRAP score captures this pattern in a single number. crap-check turns that signal into a CI gate: if any method exceeds the threshold, the build fails.

This matters in any workflow where code can be generated, refactored, or expanded quickly — including AI-assisted development — because static analysis and basic tests can pass while change risk quietly accumulates at method level.

What is the CRAP score?

CRAP (Change Risk Anti-Patterns) is a metric that combines cyclomatic complexity and test coverage. A method scores higher when it is both complex and poorly tested. The formula is:

CRAP(m) = comp(m)² × (1 - cov(m)/100)³ + comp(m)

A low CRAP score means the method is either simple, well-tested, or both. A high score is a signal worth investigating — not necessarily a hard blocker, but a starting point for review.

What this package does

Reads a Crap4J XML report generated by PHPUnit
Compares each method's CRAP score against a configurable threshold
Prints the violations sorted by severity
Exits with a non-zero code so CI fails when the threshold is exceeded
Diagnoses environment and PHPUnit configuration (doctor command)

What this package does NOT do

Generate code coverage (that is PHPUnit's job, with PCOV or Xdebug)
Replace tools like Codecov for overall coverage tracking
Apply per-method or per-path ignores (planned for a future release)
Read Clover or other coverage formats

Installation

composer require --dev lvandi/php-crap-checker

Usage

Basic usage

# 1. Generate the Crap4J report with PHPUnit
php -d pcov.enabled=1 vendor/bin/phpunit --coverage-crap4j build/crap4j.xml

# 2. Check the threshold
vendor/bin/crap-check check build/crap4j.xml --threshold=30

The report argument defaults to build/crap4j.xml and --threshold defaults to 30.

Options

Option	Default	Description
`report`	`build/crap4j.xml`	Path to the Crap4J XML report
`--threshold`	`30`	Maximum allowed CRAP score (exclusive)
`--max-violations`	(none)	Maximum number of violations before CI fails
`--max-age`	(none)	Maximum report age; accepts minutes (`60`), or duration strings (`30m`, `2h`)
`--format`	`text`	Output format (`text`, `json`)

Usage in GitHub Actions

- name: Run PHPUnit with Crap4J coverage
  run: php -d pcov.enabled=1 vendor/bin/phpunit --coverage-crap4j build/crap4j.xml

- name: Check CRAP threshold
  run: vendor/bin/crap-check check build/crap4j.xml --threshold=30

Full example with PHP matrix:

jobs:
  ci:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php: ["8.3", "8.4"]
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: pcov
          coverage: pcov

      - run: composer install --no-interaction --prefer-dist

      - run: php -d pcov.enabled=1 vendor/bin/phpunit --coverage-crap4j build/crap4j.xml

      - run: vendor/bin/crap-check check build/crap4j.xml --threshold=30

Usage with Codecov

php-crap-checker and Codecov serve different purposes and work well together:

- name: Run PHPUnit with coverage
  run: |
    php -d pcov.enabled=1 vendor/bin/phpunit \
      --coverage-clover build/clover.xml \
      --coverage-crap4j build/crap4j.xml

- name: Check CRAP threshold
  run: vendor/bin/crap-check check build/crap4j.xml --threshold=30

- name: Upload coverage to Codecov
  uses: codecov/codecov-action@v5
  with:
    files: build/clover.xml
    fail_ci_if_error: true

Codecov tracks overall and patch coverage. crap-check enforces a per-method CRAP threshold. They complement each other.

Exit codes

Code	Meaning
`0`	OK — no violations
`1`	CRAP threshold exceeded
`2`	Invalid input (e.g. non-numeric threshold)
`3`	Report file not found or not readable
`4`	Invalid XML in report
`5`	Report valid but contains no methods

Output examples

No violations

CRAP threshold OK. Max allowed: 30
Analyzed methods: 128
Violations: 0

Violations found

CRAP threshold exceeded. Max allowed: 30

3 violations found:

1) App\Legacy\ReportGenerator::generate()
   File: src/Legacy/ReportGenerator.php:10
   CRAP: 72.00
   Complexity: 18
   Coverage: 0.00%

2) App\Service\OrderImporter::import()
   File: src/Service/OrderImporter.php:42
   CRAP: 46.23
   Complexity: 12
   Coverage: 41.60%

3) App\Service\ShippingCalculator::calculate()
   File: src/Service/ShippingCalculator.php:88
   CRAP: 35.10
   Complexity: 9
   Coverage: 22.00%

Report not found

Report not found: build/crap4j.xml

Generate it with:
php -d pcov.enabled=1 vendor/bin/phpunit --coverage-crap4j build/crap4j.xml

A note on PCOV and Xdebug

PCOV and Xdebug are not required by this package. They are required by PHPUnit to generate the Crap4J report. Once the report exists, crap-check reads the XML and needs no coverage driver.

In CI, install PCOV (faster) or Xdebug only in the step that generates coverage:

- uses: shivammathur/setup-php@v2
  with:
    php-version: "8.3"
    extensions: pcov
    coverage: pcov

If you already have a report from a previous step or artifact, you can run crap-check without any coverage extension.

Interpreting a high CRAP score

A high CRAP score on a method is a signal, not a verdict. Before raising the threshold or suppressing the check, consider:

Add tests: if the method is complex but untested, coverage will bring the score down
Reduce complexity: extract helper methods or simplify branching logic
Accept and document: some methods are inherently complex and well-understood — a future baseline feature will allow explicit exceptions

Mechanically writing tests just to lower the number defeats the purpose. Use the score to guide meaningful improvement.

Adopting on a legacy project

If your codebase already has many violations, a zero-tolerance threshold from day one is counterproductive. See docs/ADOPTING.md for gradual adoption strategies: start permissive and tighten over time, cap violations with --max-violations, and how to talk to your team about the metric.

Planned

Future releases may add:

baseline support (snapshot a list of known violations, block only new ones)
--fail-on=new and --fail-on=worsened
ignore rules for paths and specific methods
GitHub Actions annotations

Requirements

PHP >=8.3
ext-simplexml
symfony/console ^7.0

Development

PHP runs inside Docker. Build the image once (uses your host UID/GID to avoid file permission issues):

make build
make install

Common commands:

make test        # PHPUnit
make qa          # PHPUnit + PHPStan (CI gate)
make stan        # PHPStan level 9
make cs-fix      # PHP CS Fixer
make infection   # Mutation testing

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines on opening issues and submitting pull requests.

To report a security vulnerability, follow the process described in SECURITY.md.

This project is released under the MIT License.

lvandi / php-crap-checker

Maintainers

Package info

Statistics

Security