phauthentic/bc-check

Backward compatibility checker for PHP APIs

1.0.0-rc4 2026-02-08 20:21 UTC

Requires

• php: ^8.3
• nikic/php-parser: ^5.0
• symfony/config: ^7.0
• symfony/console: ^7.0
• symfony/dependency-injection: ^7.0
• symfony/finder: ^7.0
• symfony/messenger: ^7.0
• symfony/process: ^7.0
• symfony/yaml: ^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.0

GPL-3.0-or-later

README

BC Check analyzes PHP code between two git commits to detect backward compatibility (BC) breaking changes using AST parsing. It helps library maintainers follow Semantic Versioning by identifying changes that could break dependent code.

"With a system of the size and importance of API, it is necessary to have some formalized rules to govern how updates are incorporated while still keeping the API stable." — Semantic Versioning 2.0.0

Features 💎

• BC Break Detection:
  • Detects removed public/protected classes, methods, properties, and constants
  • Detects method signature changes (parameters, types, defaults)
  • Detects return type changes
  • Detects visibility reductions
  • Detects added final, abstract, static, readonly modifiers
  • Detects interface implementation changes
  • Detects parent class changes
• Flexible Configuration:
  • YAML-based configuration
  • Regex patterns for include/exclude filtering
  • Custom source directories
  • External detector loading for custom BC break detection
• Multiple Output Formats:
  • Human-readable text output
  • JSON output for programmatic use
  • GitHub Actions annotations
  • SARIF (Static Analysis Results Interchange Format)
  • Checkstyle XML
  • JUnit XML
  • GitLab Code Quality
• CI/CD Ready:
  • Exit codes for build success/failure
  • GitHub Actions, GitLab CI, CircleCI, Jenkins examples
  • Docker support

Installation ⚙️

composer require --dev phauthentic/bc-check

Or download the PHAR from the releases page.

Documentation 📚

• Installation - Install via Composer, PHAR, or Docker
• Usage - CLI usage, examples, output formats
• Configuration - YAML config options, regex patterns
• Detectors - List of all detected BC breaks
• Output Formats - Detailed format examples and specifications
• Custom Detectors - Create your own detectors
• CI Integration - GitHub Actions, GitLab CI, etc.
• Docker External Projects - Run via Docker against legacy codebases
• Development - Development setup and workflows

Quick Start 🚀

# Basic usage
vendor/bin/bc-check check /path/to/repo v1.0.0 v2.0.0

# With configuration file
vendor/bin/bc-check check /path/to/repo v1.0.0 v2.0.0 --config=bc-check.yaml

# JSON output
vendor/bin/bc-check check /path/to/repo v1.0.0 v2.0.0 --format=json

For more usage examples and options, see the Usage Guide.

Reporting Issues 🪲

If you find a bug or have a feature request, please open an issue on the GitHub repository.

When reporting issues, please provide:

• PHP version
• BC Check version
• Minimal code example that reproduces the issue
• Expected vs actual behavior

License ⚖️

Copyright Florian Krämer

Licensed under the MIT License.