Weave Code
Backward Compatibility Check Laravel Package
roave/backward-compatibility-check
A CLI tool that compares two versions of a PHP library and flags backward-compatibility breaks. It reads git tags and composer.json autoload paths, then fails CI builds when public API changes would break downstream consumers.
Roave Backward Compatibility Check is a PHP tool that detects backward compatibility (BC) breaks between two versions of a library. It compares the current HEAD against the last SemVer tag in your git history, so you can catch accidental API changes before releasing.
Add it to your CI pipeline via vendor/bin/roave-backward-compatibility-check; it exits non-zero when BC breaks are found, failing the build automatically.
- Automatic git tag detection of the base version
- Compares public API changes across releases
- CI-friendly exit codes
- Works with
composer.jsonautoload paths - Optional Docker image (
nyholm/roave-bc-check)
Frequently asked questions about Backward Compatibility Check
- How do I install Roave BackwardCompatibilityCheck in a Laravel project?
- Run `composer require --dev roave/backward-compatibility-check` in your Laravel project’s root. The tool requires Git tags in SemVer format (e.g., `v1.2.3`) and a `composer.json` autoload section. No Laravel-specific setup is needed beyond standard Composer dependencies.
- Can this tool check for BC breaks in Laravel’s core packages (e.g., `illuminate/support`)?
- Yes, but only if you’re maintaining a fork or custom Laravel distribution. The tool scans any PHP classes under `composer.json` autoload paths. For official Laravel packages, use it to audit third-party dependencies like `spatie/laravel-*` instead.
- Will this break my CI if I have false positives (e.g., protected → private methods)?
- Configure `.roave-backward-compatibility-check.xml` to whitelist known-safe changes. Use the `<ignore>` tag for specific methods/properties or adjust regex patterns. Run locally first with `--dry-run` to test before CI integration.
- Does Roave BackwardCompatibilityCheck support Laravel’s PHP 8.1+ features (e.g., enums, attributes)?
- Yes, the tool supports PHP 8.0–8.5, covering Laravel 9–11. It detects breaking changes in enums, attributes, and new PHP 8.1+ features like first-class callable syntax. No additional configuration is required for Laravel-specific types.
- How do I integrate this into GitHub Actions for a Laravel package?
- Add a step to your workflow file: `vendor/bin/roave-backward-compatibility-check`. Use `if: github.ref == 'refs/heads/main'` to run only on the main branch. For Docker, replace with `docker run --rm -v $PWD:/app nyholm/roave-bc-check`. Fails the build on BC breaks by default.
- Can I exclude certain Laravel directories (e.g., `tests/`, `config/`) from BC checks?
- Yes, use the `--source` CLI argument to specify only your public API paths (e.g., `--source=src`). For complex exclusions, configure `.roave-backward-compatibility-check.xml` with `<source>` tags. Laravel’s `app/` and `database/` are typically excluded unless part of your package’s API.
- What’s the performance impact of running this in a large Laravel monorepo?
- Expect 1–3 minutes per run, depending on codebase size. For monorepos, compare branches directly (e.g., `main...feature-branch`) instead of tags. Use Docker to avoid local setup overhead. Run in parallel with PHPUnit or split checks by package using `--source`.
- Does this tool work with Laravel’s custom autoloading (e.g., non-PSR-4 paths)?
- No, it requires standard Composer autoload paths. If you use custom PSR-4 paths, extend `composer.json` autoload or pass them via `--source`. For Laravel, this rarely applies unless you’re using non-standard class locations like `app/Contracts/` without autoload config.
- How do I handle pre-release tags (e.g., `v1.0.0-beta`) in Laravel’s CI?
- Exclude pre-release tags by configuring `.roave-backward-compatibility-check.xml` with `<ignore-tag-pattern>.*-beta</ignore-tag-pattern>`. For Laravel, this is useful if you use beta tags for internal testing but only enforce BC on stable releases.
- Are there alternatives for Laravel-specific BC checking?
- For Laravel, consider `phpstan/extension-installer` + PHPStan’s `noUnusedPrivateProperties` rule for static analysis, or `vimeo/psalm` for stricter type checking. However, Roave’s tool is the most comprehensive for SemVer-compliant API comparisons and integrates natively with Git tags—critical for Laravel packages.
Weaver
How can I help you explore Laravel packages today?