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

5.0.0 2020-06-22 11:14 UTC


Mutation testing badge Type Coverage Latest Stable Version License

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


  • 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 roave/backward-compatibility-check

Install with Docker

You can also use Docker to run roave-backward-compatibility-check:

docker run --rm -v `pwd`:/app nyholm/roave-bc-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.

Github action

You can use it as a Github Action like this:


on: [push]
name: Test
        name: Roave BC Check
        runs-on: ubuntu-latest
            - uses: actions/checkout@master
            - name: fetch tags
              run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
            - name: Roave BC Check
              uses: docker://nyholm/roave-bc-check-ga

Running manually

To generate additional documentation for changelogs:

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


If you need further guidance:

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


There are currently no configuration options available.