Php Deprecation Detector Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer global require wapmorgan/php-deprecation-detector
   

   Or download the PHAR and make it executable.

2. First Scan:

   phpdd app/ --target=8.2 --exclude=vendor
   

   • --target: Specify the PHP version you're migrating to (e.g., 8.2).
   • --exclude: Skip third-party dependencies (e.g., vendor).

3. Quick Check:

   phpdd -t 8.1 -a 7.4 app/
   

   • -t: Target PHP version (e.g., 8.1).
   • -a: Start checks from this version (e.g., 7.4).

First Use Case

Pre-Migration Audit: Run phpdd on your Laravel project before upgrading PHP to identify deprecated functions, constants, or syntax (e.g., mysql_* functions, call_user_func_array with pass-by-reference). Example:

phpdd --target=8.2 --output=json --output-file=deprecations.json app/

Use the JSON output to programmatically review issues in CI/CD pipelines.

Implementation Patterns

Workflows

1. CI/CD Integration:

   • Add a script to composer.json:

     "scripts": {
       "php:deprecation-check": "phpdd --target=8.2 --exclude=vendor --output=junit --output-file=phpunit.xml app/"
     }
     

   • Run in GitHub Actions:

     - name: Check deprecations
       run: composer php:deprecation-check
     

2. Pre-Commit Hook: Use husky or pre-commit to scan staged files:

   phpdd --target=8.2 --max-size=500kb --file-extensions=php,blade.php app/
   

3. Laravel-Specific Checks:

   • Exclude vendor and bootstrap/cache:

     phpdd --target=8.2 --exclude=vendor,bootstrap/cache app/
     

   • Focus on Blade templates:

     phpdd --target=8.2 --file-extensions=php,blade.php resources/views/
     

4. Custom Rules: Skip checks for specific functions (e.g., legacy code):

   phpdd --target=8.2 --skip-checks=mysql_,ereg_ app/
   

Integration Tips

• Laravel Artisan Command: Create a custom command (php artisan php:deprecation-check) to wrap phpdd:

  // app/Console/Commands/CheckDeprecations.php
  public function handle()
  {
      $command = 'phpdd --target=' . config('app.php_version') . ' --exclude=vendor app/';
      shell_exec($command);
  }
  

• IDE Integration: Use the JSON output to create custom IDE warnings (e.g., PHPStorm annotations).

• Database Migrations: Scan database/migrations separately for deprecated SQL functions (e.g., mysql_query):

  phpdd --target=8.2 --file-extensions=php database/migrations/
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • Static methods with the same name as deprecated functions (e.g., Widget::widget) may trigger false alarms. Use --skip-checks to exclude them:

     phpdd --skip-checks=widget app/
     

2. Performance:

   • Large files (>1MB) are skipped by default. Adjust with --max-size:

     phpdd --max-size=2mb app/
     

3. Symfony Console Compatibility:

   • If using Symfony Console <6.0, ensure compatibility by pinning the version:

     composer require symfony/console:^5.4
     

4. Blade Template Parsing:

   • Blade files (*.blade.php) may not parse correctly. Use --file-extensions to include them:

     phpdd --file-extensions=php,blade.php resources/views/
     

5. Pass-by-Reference:

   • call_user_func_array with pass-by-reference may trigger warnings. Exclude with:

     phpdd --skip-checks=call_user_func_array app/
     

Debugging

1. Verbose Output: Enable debug mode for detailed logs:

   phpdd -vvv --target=8.2 app/
   

2. JSON Validation: Validate the JSON output against the schema to debug parsing issues.

3. Exclusion Quirks:

   • Use absolute paths for --exclude if relative paths fail:

     phpdd --exclude=/full/path/to/vendor app/
     

Extension Points

1. Custom Checkers: Extend the package by adding new rules (e.g., Laravel-specific deprecations like Route::bind in older versions). Fork the repo and modify src/Checker/.

2. Post-Processing: Use the JSON output to generate pull requests or Slack alerts:

   $report = json_decode(file_get_contents('deprecations.json'), true);
   foreach ($report->problems as $issue) {
       // Trigger GitHub API to create PR or send Slack message
   }
   

3. PHP Version Matrix: Run checks for multiple target versions in a loop:

   for version in 7.4 8.0 8.1 8.2; do
       phpdd --target=$version --output=json --output-file=report_$version.json app/
   done
   

Laravel-Specific Tips

1. Service Provider Checks: Scan app/Providers for deprecated service provider methods (e.g., registerGlobalScopes in older Laravel versions):

   phpdd --target=8.2 --file-extensions=php app/Providers/
   

2. Facades: Check for deprecated facades (e.g., Input::old() → request()->old()):

   phpdd --target=8.2 --skip-checks=Input,Request app/
   

3. Event Listeners: Audit app/Listeners for deprecated event methods:

   phpdd --target=8.2 app/Listeners/
   

4. Config Files: Scan config/ for deprecated INI directives (e.g., session.use_trans_sid):

   phpdd --target=8.2 --file-extensions=php config/