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]

roave-backward-compatibility-check [options] <old-version-directory> <new-version-directory>

--format=<format>
    Specifies the output format (e.g., `text`, `json`, `xml`). Default is `text`.

--ignore=<file>
    A file containing a list of BC break signatures to ignore. Each signature should be on a new line.

--extensions=<extensions>
    Comma-separated list of file extensions to scan (e.g., `php,inc`). Default is `php`.

<old-version-directory>
    The directory containing the code of the old version.

<new-version-directory>
    The directory containing the code of the new version.

The `roave-backward-compatibility-check` command is a PHP tool used to analyze two versions of a PHP library or application to identify potential backward compatibility (BC) breaks. It compares the public API (classes, interfaces, traits, methods, constants, properties) of the old version against the new version and reports any changes that could cause existing code to break when upgrading. This tool is essential for library maintainers and application developers who want to ensure a smooth upgrade path for their users.

The check looks for removals, signature changes, deprecations without replacements, and other modifications to the public API that could impact existing code relying on the older version. It provides detailed reports on detected BC breaks, helping developers to understand the impact of their changes and make informed decisions about how to mitigate them. Proper usage of this tool significantly reduces the risk of unexpected errors during upgrades and improves the overall user experience.

The tool relies on accurate reflection and parsing of PHP code. Dynamic features like `eval()` and highly complex code constructs might not be perfectly analyzed. The quality of the analysis depends on the defined public API. It only checks public interfaces, not internal implementation details. Also it requires a PHP environment to be present.

The `roave-backward-compatibility-check` command returns 0 on success and a non-zero value if any backward compatibility breaks are detected.

• To check compatibility between versions in `v1` and `v2` directories:
  roave-backward-compatibility-check v1 v2
• To check compatibility and output in JSON format:
  roave-backward-compatibility-check --format=json v1 v2
• To ignore specific BC breaks defined in `ignore.txt`:
  roave-backward-compatibility-check --ignore=ignore.txt v1 v2

The `roave-backward-compatibility-check` is part of the Roave tooling suite, which aims to provide tools for PHP development and maintenance. It's been actively developed and used by PHP developers to ensure backward compatibility in their libraries and applications. The command has evolved over time with improved parsing capabilities, more detailed reporting, and support for different output formats. Usage has increased as more developers recognize the importance of maintaining backward compatibility for a better user experience.