Backward Compatibility Check Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   or via Docker:

   docker run --rm -v $(pwd):/app nyholm/roave-bc-check
   

2. First Run:

   vendor/bin/roave-backward-compatibility-check
   

   • Automatically compares the latest minor version tag (e.g., v1.2.0) with HEAD.
   • Fails the build if backward compatibility (BC) breaks are detected.

3. CI Integration: Ensure your CI pipeline fetches all git history (e.g., fetch-depth: 0 in GitHub Actions):

   steps:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
     - run: vendor/bin/roave-backward-compatibility-check
   

First Use Case: Pre-Merge Check

• Trigger: Run in a pre-commit hook or CI pipeline before merging feature branches.
• Example:

  vendor/bin/roave-backward-compatibility-check --format=github-actions
  

  • Outputs GitHub Actions annotations for easy PR review.

Implementation Patterns

1. CI/CD Workflow

• Best Practice: Run after tests but before deployment to catch BC breaks early.

  jobs:
    test:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
          with:
            fetch-depth: 0
        - run: composer install
        - run: phpunit
        - run: vendor/bin/roave-backward-compatibility-check
  

2. Custom Baseline Configuration

• File: .roave-backward-compatibility-check.xml
• Use Case: Ignore known BC breaks (e.g., deprecated methods marked for removal).

  <roave-bc-check>
      <baseline>
          <ignored-regex>#\[BC\] REMOVED: MyDeprecatedClass::oldMethod\(\)#</ignored-regex>
      </baseline>
  </roave-bc-check>
  

3. Output Formats

4. Laravel-Specific Integration

• Hook into post-test in phpunit.xml:

  <phpunit>
      <extensions>
          <extension class="Roave\BackwardCompatibilityCheck\PHPUnit\Extension"/>
      </extensions>
  </phpunit>
  

• Custom Rule: Extend the checker to whitelist Laravel-specific BC changes (e.g., Facade method additions).

Gotchas and Tips

Common Pitfalls

1. Missing Git Tags:

   • Error: No baseline tag found.
   • Fix: Ensure SemVer-compliant tags (e.g., v1.0.0) exist and are fetched in CI.
   • Workaround: Manually specify a baseline:

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

2. False Positives:

   • Issue: Legitimate changes (e.g., adding optional params) flagged as BC breaks.
   • Fix: Use <ignored-regex> in .roave-backward-compatibility-check.xml:

     <ignored-regex>#\[BC\] CHANGED: Added optional \$param to MyClass::method\(\)#</ignored-regex>
     

3. Performance:

   • Slow on Large Codebases: The tool parses all autoloaded classes.
   • Tip: Run in parallel with other tests or cache results in CI.

4. PHP Version Mismatch:

   • Error: Unsupported PHP version.
   • Fix: Ensure your CI PHP version matches the tool’s supported versions.

Debugging Tips

• Verbose Output:

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

  • Shows detailed parsing logs for troubleshooting.

• Dry Run:

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

  • Lists potential BC breaks without failing the build.

• Custom Autoload Paths: If using non-standard autoloading (e.g., custom psr-4 paths), specify them:

  vendor/bin/roave-backward-compatibility-check --autoload-path=app/
  

Extension Points

1. Custom Rules:

   • Extend the checker by implementing Roave\BackwardCompatibilityCheck\Rule\RuleInterface.
   • Example: Add a rule to ignore Laravel’s HasFactory trait changes.

2. Plugin System:

   • The tool supports plugins for custom logic. See Roave’s docs.

3. GitHub Action:

   • Use the official action for zero-config setup:

     - uses: Nyholm/roave-bc-check-docker@v1
     

Laravel-Specific Quirks

• Facade Methods:

  • Adding/removing Facade methods may trigger false positives.
  • Workaround: Ignore the Facade class in .roave-backward-compatibility-check.xml:

    <ignored-class>Illuminate\Support\Facades\Route</ignored-class>
    

• Service Providers:

  • Changes to register()/boot() methods are not BC breaks but may be flagged.
  • Tip: Exclude app/Providers/ from checks if needed.

• Dynamic Proxies:

  • Laravel’s Eloquent or Collections may generate proxy classes.
  • Fix: Ensure autoload-dev includes proxy paths in composer.json.