Backward Compatibility Check Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev roave/backward-compatibility-check
   

   Add to composer.json under require-dev if not using global install.

2. First Run:

   vendor/bin/roave-backward-compatibility-check
   

   • Automatically compares the latest SemVer-compliant Git tag (e.g., v1.2.3) with HEAD.
   • Fails the build if BC breaks are detected (non-zero exit code).

3. CI Integration: Ensure Git tags are fetched (e.g., fetch-depth: 0 in GitHub Actions):

   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
   

First Use Case: Pre-Release Validation

• Scenario: Before tagging a new minor version (1.2.0 → 1.3.0), verify no BC breaks exist.
• Command:

  vendor/bin/roave-backward-compatibility-check --baseline=1.2.0
  

• Output: Terminal output lists BC violations (e.g., removed methods, changed parameter types).

Key Files to Review

1. .roave-backward-compatibility-check.xml (if exists):
   • Configure ignored regex patterns for false positives.
   • Example:

     <ignored-regex>#\[BC\] REMOVED: Method TestClass\#deprecatedMethod\(\)#</ignored-regex>
     

2. composer.json:
   • Ensure autoload covers all source paths (required for accurate analysis).

Implementation Patterns

Workflow: Daily Development

1. Local Checks:

   • Run manually during feature development to catch BC breaks early:

     vendor/bin/roave-backward-compatibility-check --baseline=origin/main
     

   • Use --format=markdown to generate a changelog-friendly report:

     vendor/bin/roave-backward-compatibility-check --format=markdown > CHANGELOG.md
     

2. Branch-Specific Baselines:

   • Compare against a specific branch (e.g., feature-branch vs. main):

     vendor/bin/roave-backward-compatibility-check --baseline=main
     

3. CI Pipeline Integration:

   • GitHub Actions Example:

     - name: BC Check
       run: vendor/bin/roave-backward-compatibility-check --format=github-actions
     

   • Output: Annotates PRs with BC break details (if using --format=github-actions).

Laravel-Specific Patterns

1. Service Container Classes:

   • BC checks will flag:
     • Removed/renamed bound interfaces.
     • Changed method signatures in service providers.
   • Mitigation: Use --baseline to compare against the last stable version before major releases.

2. Eloquent Models:

   • Detects:
     • Removed/renamed columns (via fillable, casts).
     • Changed method signatures in accessors/mutators.
   • Tip: Exclude internal methods with @internal PHPDoc to avoid noise.

3. Custom Artisan Commands:

   • Flags BC breaks in command signatures (e.g., removed optional arguments).

Advanced: Custom Baselines

1. Dynamic Baselines:

   • Use --baseline to compare against a specific commit/tag:

     vendor/bin/roave-backward-compatibility-check --baseline=v1.2.0
     

   • Useful for comparing against a release candidate.

2. Ignoring False Positives:

   • Add regex patterns to .roave-backward-compatibility-check.xml:

     <ignored-regex>#\[BC\] CHANGED: Parameter \$model of App\Services\#update\(\)#</ignored-regex>
     

   • Laravel Example: Ignore changes to Illuminate\Contracts dependencies.

Gotchas and Tips

Pitfalls

1. Git Tag Requirements:

   • Gotcha: Fails silently if no SemVer-compliant tags exist (e.g., v1.2.3).
   • Fix: Manually specify --baseline or ensure tags are pushed to remote.

2. False Positives in Laravel:

   • Issue: Framework updates (e.g., Laravel core classes) may trigger false BC breaks.
   • Fix: Ignore vendor paths in .roave-backward-compatibility-check.xml:

     <ignored-path>vendor/laravel/</ignored-path>
     

3. Enum and Attribute Changes:

   • Gotcha: Adding/removing enum cases or attributes is flagged as a BC break.
   • Fix: Use --baseline to compare against a version where the change was intentional.

4. Reflection Errors:

   • Gotcha: Custom __call/__callStatic methods may cause parsing errors.
   • Fix: Exclude problematic classes with:

     <ignored-class>App\DynamicProxy\Handler</ignored-class>
     

Debugging Tips

1. Verbose Output:

   • Enable debug mode for detailed logs:

     vendor/bin/roave-backward-compatibility-check --verbose
     

2. Dry Run:

   • Test without failing the build:

     vendor/bin/roave-backward-compatibility-check --dry-run
     

3. JSON Output for Scripting:

   • Parse results programmatically:

     vendor/bin/roave-backward-compatibility-check --format=json > bc-results.json
     

   • Example: Filter for critical breaks in a script:

     $results = json_decode(file_get_contents('bc-results.json'), true);
     $critical = array_filter($results, fn($item) => $item['type'] === 'REMOVED');
     

Extension Points

1. Custom Formatters:

   • Extend the JsonFormatter or create a new formatter by implementing FormatterInterface.
   • Example: Generate a Slack notification for BC breaks.

2. Hooks for Pre/Post-Analysis:

   • Use --hook to run scripts before/after analysis (e.g., cleanup temporary files):

     vendor/bin/roave-backward-compatibility-check --hook="php ./scripts/pre-bc-check.php"
     

3. PHP 8.4+ Support:

   • Note: The package supports PHP 8.4 but disables hook-related features (e.g., set_hook()).
   • Workaround: Use --baseline for manual comparisons.

Laravel-Specific Quirks

1. Facade Changes:

   • Gotcha: Renaming/removing facade aliases (e.g., App::make() → app()) may not be detected.
   • Fix: Manually verify config/app.php alongside BC checks.

2. Dynamic Proxies:

   • Gotcha: Laravel’s dynamic proxies (e.g., Eloquent) may cause parsing errors.
   • Fix: Exclude proxy classes in config:

     <ignored-class>App\Proxies\*</ignored-class>
     

3. Service Provider Booting:

   • Tip: Run BC checks after composer dump-autoload to ensure up-to-date class maps:

     composer dump-autoload && vendor/bin/roave-backward-compatibility-check