Weave Code
Backward Compatibility Check Laravel Package
roave/backward-compatibility-check
CLI tool to detect backward-compatibility breaks between two versions of a PHP library. Compares the last SemVer git tag to current HEAD (or chosen refs) and fails CI on API breaks. Install via Composer or run with Docker.
roave/backward-compatibility-check is a CLI tool for verifying backward compatibility (BC) between two versions of a PHP library. It’s designed for CI: compare your latest SemVer tag against HEAD, and fail the build when API breaks are detected.
It assumes a git-tagged workflow and Composer autoload coverage, making it a practical guardrail for maintaining stable public APIs across releases.
- Detects the last SemVer tag and compares it to the current branch/
HEAD - Returns non-zero exit codes on BC breaks for CI enforcement
- Works with standard composer.json autoload configuration
- Supports running via Docker for easy, isolated usage
- Helps audit public API changes before publishing releases
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?