Backward Compatibility Check Laravel Package

Product Decisions This Supports

• Semantic Versioning Enforcement: Automatically block BC-breaking changes in minor/patch releases, ensuring compliance with SemVer. This aligns with roadmaps for libraries targeting long-term maintainability (e.g., "We will only release breaking changes in major versions").
• Developer Experience (DX) for Open Source: Reduce manual changelog maintenance by integrating BC checks into CI/CD pipelines, freeing engineers to focus on features. Example: "We want to cut 20% of our changelog writing time by automating BC detection."
• Build vs. Buy: Justify investing in tooling over manual reviews or third-party audits (e.g., "This costs $0 vs. $5K/year for a commercial BC scanner").
• Use Cases:
  • Library Authors: Enforce BC guarantees for downstream consumers (e.g., Laravel packages, Composer dependencies).
  • Enterprise PHP Monorepos: Prevent accidental BC breaks across microservices sharing a codebase.
  • Legacy System Modernization: Identify safe upgrade paths for deprecated APIs (e.g., PHP 7.4 → 8.4).
  • Compliance: Meet contractual BC requirements (e.g., "Our SaaS API must maintain BC for 3 years").

When to Consider This Package

Adopt if:

• Your project uses SemVer and releases minor/patch versions to public repositories (e.g., Packagist, GitHub).
• You maintain a PHP library with external dependencies or consumers (even internal ones).
• Your team lacks manual BC review processes or relies on ad-hoc changelog checks.
• You need CI-native validation (e.g., GitHub Actions, GitLab CI) without custom scripts.
• Your codebase includes complex APIs (e.g., enums, generics, reflection-heavy classes) where manual checks are error-prone.

Look elsewhere if:

• You’re a monolithic application with no versioned releases (use static analysis tools like Psalm or PHPStan instead).
• Your team doesn’t follow SemVer (e.g., uses calendar versioning like 2024.1.0).
• You need runtime BC detection (e.g., checking user-provided code at execution time; consider phpstan/extension-installer or custom runtime checks).
• Your project is trunk-based development with no tagged releases (the tool requires git tags for baseline comparison).
• You require GUI/IDE integration (this is CLI-only; pair with a linter like PHPStorm for visual feedback).

How to Pitch It (Stakeholders)

For Executives: *"This tool automates backward compatibility (BC) checks for our PHP libraries, ensuring we never accidentally break downstream consumers—saving us from costly support issues and reputation damage. For example, if we change a method signature in a minor release, the tool flags it in CI, forcing us to either:

1. Fix the BC break (proactive), or
2. Bump the major version (transparent). This aligns with our SemVer commitment and reduces manual QA overhead by 30%+."*

Key Metrics to Highlight:

• Risk Reduction: Prevents "oops" BC breaks that could trigger cascading updates for 100+ dependencies.
• Developer Productivity: Shifts BC checks from post-release fire drills to pre-merge CI gates.
• Cost Avoidance: Eliminates need for paid third-party audits (e.g., $5K/year for commercial tools).

For Engineers: *"This is like phpcs but for API contracts. It runs in CI and:

• Detects BC breaks between tagged versions (e.g., v1.2.0 → HEAD).
• Supports custom ignores (e.g., @internal methods, experimental APIs).
• Integrates with GitHub Actions in 2 lines of YAML.
• Outputs machine-readable formats (JSON, GitHub Actions annotations) for dashboards.

Example workflow:

# .github/workflows/bc-check.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Critical: Fetches all tags
- run: composer require --dev roave/backward-compatibility-check
- run: vendor/bin/roave-backward-compatibility-check

No false positives: It uses PHP’s reflection API to parse actual code, not regex heuristics."*

For Open Source Maintainers: *"This is the ‘standard’ BC checker for PHP libraries. It’s used by projects like Symfony and Doctrine, and it’s MIT-licensed (no vendor lock-in). If we adopt it, we’ll:

• Align with the ecosystem: Most PHP libraries use this tool.
• Reduce support burden: Fewer ‘it broke when you upgraded’ issues.
• Future-proof: Supports PHP 8.4, enums, and modern PHP features."*