roave-backward-compatibility-check

Check for breaking changes since the last tag

$ roave-backward-compatibility-check

$ roave-backward-compatibility-check --from=[git_reference]

$ roave-backward-compatibility-check --to=[git_reference]

$ roave-backward-compatibility-check --format=markdown > [results.md]

vendor/bin/roave-backward-compatibility-check <base-reference> <head-reference> [options]

<base-reference>: The older Git reference (e.g., branch, tag, commit) or directory path to compare against.
<head-reference>: The newer Git reference or directory path to be checked for breaks.

base-reference
    The older version of the codebase for comparison. Can be a Git reference (e.g., main, HEAD~1) or a directory path.

head-reference
    The newer version of the codebase being checked for backward compatibility breaks. Can be a Git reference or a directory path.

--php-json <path>
    Specifies the path to a php.json file for configuring PHP version constraints during analysis.

--config <path>
    Specifies the path to a bc-check.php file for advanced configuration, allowing custom rules and exclusion of specific BC breaks.

--ignore-php-major-version-changes
    Ignores reported issues related to PHP major version changes, focusing only on code-level breaks.

--help
    Displays help information for the command.

--version
    Displays the application's version.

--verbose
    Increases the verbosity of command output.

--quiet
    Suppresses all command output messages.

The roave-backward-compatibility-check command is a powerful static analysis tool designed for PHP development, primarily used to prevent accidental backward compatibility (BC) breaks. It compares two versions of a PHP codebase, such as a feature branch against a stable main or master branch, or two distinct Git references/directories.

The tool identifies structural changes that could lead to breaks for consumers of a library or application, including removed public methods, changed method signatures, or alterations to class, interface, and trait definitions. This utility is particularly valuable in Continuous Integration/Continuous Deployment (CI/CD) pipelines, where it can automatically enforce BC standards before code is merged or deployed. By integrating this check into the development workflow, teams can maintain API stability and ensure that updates do not inadvertently break existing integrations or dependent projects. It requires PHP and typically operates within a project's vendor/bin directory after installation via Composer.

This command requires a PHP environment to run and is typically installed as a project dependency via Composer. It relies on git for comparing codebases when Git references are provided. As a static analysis tool, it may not detect all possible backward compatibility breaks, particularly those that manifest only at runtime or due to complex dynamic code execution. Proper configuration through bc-check.php is often necessary to ignore intentional breaks or tailor checks to specific project needs. It's designed for use within a PHP project's vendor/bin directory, not as a globally installed system command.

This tool is highly recommended for integration into Continuous Integration and Continuous Deployment pipelines. By adding it as a step in automated workflows, teams can automatically verify that pull requests or commits do not introduce unwanted backward compatibility breaks, ensuring robust API stability and preventing regressions.

The command offers extensive configurability through dedicated files: bc-check.php allows for fine-grained control over the analysis, including ignoring specific types of breaks or certain files/namespaces. php.json enables configuration of PHP version constraints for the analysis, which is crucial for projects targeting specific PHP environments.

The roave-backward-compatibility-check tool was developed by Roave, a software development consultancy, and is an open-source project hosted on GitHub. Its initial public release was in 2017. It was created to address the critical need for automated checks against accidental API or library changes that could break consumer code, a common challenge in maintaining stable software components. Since its inception, it has been actively maintained and updated, gaining adoption within the PHP community, especially in projects prioritizing strong backward compatibility guarantees.

composer(1), php(1), git(1), phpstan, psalm