Tool to compare two revisions of a public API to check for BC breaks

5.0.7 2021-05-28 15:36 UTC


Mutation testing badge Latest Stable Version License

A tool that can be used to verify BC breaks between two versions of a PHP library.

This fork changes internal classes and methods interpretation according to PHPStan backward compatibility promise.


  • Your project uses git
  • Your project uses composer.json to define its dependencies
  • All source paths are covered by an "autoload" section in composer.json
  • Changes need to be committed to git to be covered. You can implement your own logic to extract sources and dependencies from a project though.


composer require --dev ondrejmirtes/backward-compatibility-check


Adding to a continuous integration pipeline

The typical intended usage is to just add roave-backward-compatibility-check to your CI build:


This will automatically detect the last minor version tagged, and compare the API against the current HEAD. If any BC breaks are found, the tool returns a non-zero status, which on most CI systems will cause the build to fail.

NOTE: detecting the base version only works if you have git tags in the SemVer-compliant x.y.z format, such as 1.2.3.

NOTE: since this tool relies on tags, you need to make sure tags are fetched as part of your CI pipeline. For example in a GitHub action, note the use of fetch-depth: 0:

    name: Roave Backwards Compatibility Check
      runs-on: ubuntu-latest
        - uses: actions/checkout@v2
            fetch-depth: 0
        - name: "Install PHP"
          uses: shivammathur/setup-php@v2
            coverage: "none"
            php-version: "7.4" # https://github.com/Roave/BackwardCompatibilityCheck/issues/283
        - name: "Install dependencies"
          run: "composer install --no-interaction"
        - name: "Check for BC breaks"
          run: "vendor/bin/roave-backward-compatibility-check"

Running manually

To generate additional documentation for changelogs:

vendor/bin/roave-backward-compatibility-check --format=markdown > results.md


If you need further guidance:

vendor/bin/roave-backward-compatibility-check --help


There are currently no configuration options available.