Psalm Insane Comparison Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Plugin: The package is a Psalm plugin, meaning it integrates into the static analysis pipeline (pre-runtime) rather than requiring runtime instrumentation. This aligns well with Laravel’s PHP-centric ecosystem, where static analysis tools (e.g., Psalm, PHPStan) are commonly used for quality assurance.
• Migration-Specific: Targets a PHP 7 → PHP 8 behavioral change, making it highly relevant for Laravel projects upgrading to PHP 8.x/9.x. The RFC change (string-to-number comparisons) is a known pain point in legacy codebases.
• Non-Invasive: Operates at the code analysis level without modifying runtime behavior, reducing risk of breaking existing functionality.
• Complementary to Existing Tools: Works alongside Laravel’s built-in tools (e.g., php artisan test) and other static analyzers (PHPStan, Pest).

Integration Feasibility

• Psalm Compatibility: Supports Psalm v5+ (explicitly tested with v6), which is widely adopted in modern Laravel projects. Psalm is often preferred over PHPStan in Laravel due to its deeper PHP 8+ feature support.
• Composer-Based: Installation is zero-configuration (Composer + CLI enablement), requiring minimal setup. No Laravel service provider or Facade integration needed.
• CI/CD Friendly: Can be gated in CI pipelines (e.g., GitHub Actions, GitLab CI) to block merges with "insane comparisons," enforcing PHP 8 compatibility early.
• IDE Integration: Psalm plugins typically work with PHPStorm/VSCode via Psalm’s IDE plugins, enabling real-time feedback during development.

Technical Risk

• False Positives/Negatives:
  • Risk of overzealous flagging (e.g., intentional numeric-string comparisons in legacy logic).
  • May miss edge cases (e.g., dynamic variable comparisons where types aren’t statically analyzable).
  • Mitigation: Configure Psalm’s error level (e.g., treat as info initially) and whitelist known-safe comparisons.
• Psalm Version Lock:
  • Hard dependency on Psalm (not PHPStan or other tools). If the team uses PHPStan, this plugin won’t work without Psalm.
  • Mitigation: Evaluate Psalm adoption as part of the migration strategy.
• Performance Overhead:
  • Static analysis adds CPU/memory usage during composer psalm runs. For large codebases, this could slow down CI.
  • Mitigation: Cache Psalm results (e.g., psalm --init-cache) and run in parallel where possible.
• PHP 8+ Only:
  • The plugin’s purpose is PHP 8 migration, so it’s irrelevant for PHP 7.x projects. Ensure the team is aligned on upgrading.

Key Questions

1. Psalm Adoption:
   • Is Psalm already used in the codebase? If not, what’s the effort to onboard it (configuration, learning curve)?
2. Migration Timeline:
   • Is PHP 8 upgrade imminent? If not, is this plugin worth the setup cost now?
3. False Positive Tolerance:
   • How strict should the plugin’s error level be (e.g., error vs. info)?
4. Whitelisting Strategy:
   • Are there known legacy patterns (e.g., is_numeric() checks) that should be excluded?
5. CI/CD Integration:
   • Should this block merges (--fail-on-error) or run as a pre-commit check?
6. Alternatives:
   • Would PHPStan’s phpstan/extension-installer + custom rules achieve similar goals with less Psalm dependency?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • No framework-specific changes required. Works with vanilla PHP and Laravel’s dependency injection.
  • Testability: Can be integrated into Laravel’s testing pipeline (e.g., run Psalm in phpunit.xml or composer.json scripts).
  • Artisan Integration: Add a custom Artisan command to wrap Psalm with this plugin:

    // app/Console/Commands/RunPsalm.php
    public function handle() {
        $this->call('vendor:publish', ['--provider' => 'PsalmPluginServiceProvider']);
        $this->call('psalm', ['--plugin' => 'orklah/psalm-insane-comparison']);
    }
    

• Toolchain Synergy:
  • Pair with:
    • Pest/Laravel Test: Ensure tests pass under PHP 8.
    • Laravel Pint/Pint: Enforce consistent code style post-migration.
    • Git Hooks: Run Psalm via pre-commit (e.g., with husky).

Migration Path

1. Phase 1: Assessment
   • Install Psalm and the plugin in a staging environment.
   • Run composer psalm and review flagged issues. Prioritize high-impact comparisons (e.g., in auth, validation, or payment logic).
2. Phase 2: Incremental Fixes
   • Fix issues in small PRs (e.g., one file/class at a time).
   • Use the plugin’s suggested fixes (strict typing, casts, or @var annotations).
3. Phase 3: CI Enforcement
   • Add Psalm to CI with --fail-on-error (e.g., GitHub Actions):

     - name: Psalm Insane Comparisons
       run: vendor/bin/psalm --plugin=orklah/psalm-insane-comparison --fail-on-error
     

4. Phase 4: PHP 8 Upgrade
   • Once all issues are resolved, upgrade PHP version in staging/production.
   • Re-run Psalm to confirm no regressions.

Compatibility

• Laravel Versions:
  • Works with Laravel 8+ (PHP 8+ required for the RFC change).
  • For Laravel 7.x, consider running in a parallel branch before upgrading.
• Psalm Configuration:
  • Ensure psalm.xml includes:

    <plugin_class>Orklah\PsalmInsaneComparison\Plugin</plugin_class>
    

  • Configure error levels:

    <error_level>3</error_level> <!-- or lower for non-blocking -->
    

• Dependency Conflicts:
  • No known conflicts with Laravel core or popular packages (e.g., laravel/framework, spatie/laravel-permission).

Sequencing

1. Pre-Migration:
   • Install Psalm and the plugin in a feature branch.
   • Run against a subset of the codebase (e.g., app/Http/Controllers).
2. During Migration:
   • Fix issues in priority order (e.g., critical paths first).
   • Use psalm --stats to track progress.
3. Post-Migration:
   • Remove the plugin if no longer needed (or keep for future PHP upgrades).
   • Document the migration process for future reference.

Operational Impact

Maintenance

• Plugin Updates:
  • Monitor for new Psalm versions (plugin may lag behind).
  • Update the plugin via Composer (composer update orklah/psalm-insane-comparison).
• Psalm Configuration:
  • Maintain psalm.xml to suppress false positives (e.g., for legacy code).
  • Example suppression:

    <ignore_errors>
        <error>InsaneComparison</error>
        <pattern>app/OldLegacyClass.php</pattern>
    </ignore_errors>
    

• Deprecation Risk:
  • Low risk (MIT license, active maintenance). If abandoned, fork or replace with a similar tool.

Support

• Developer Onboarding:
  • Train developers on:
    • How to read Psalm error messages.
    • The plugin’s false-positive scenarios.
  • Document common fixes (e.g., === vs. == tradeoffs).
• Debugging:
  • Psalm provides detailed error locations (file:line), easing debugging.
  • Use --no-cache to rule out stale analysis.

Scaling

• Large Codebases:
  • Run Psalm in parallel (e.g., split by directory):

    find app -name "*.php" | xargs -P 4 vendor/bin/psalm --plugin=orklah/psalm-insane-comparison
    

  • Use --init-cache to speed up repeated runs.
• Performance:
  • Expect ~10–30% slower than normal Psalm runs (varies by codebase size).
  • Cache results in CI (e.g., GitHub Actions cache).

Failure Modes