Psalm Plugin Api Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Integration: The psalm/psalm-plugin-api provides a stable, versioned API for building Psalm plugins, making it a strong fit for teams using PHP static analysis (e.g., type checking, code quality enforcement) within a Laravel or broader PHP ecosystem.
• Extensibility: Aligns well with monorepos or modular PHP projects where custom static analysis rules are needed (e.g., domain-specific business logic validation).
• Toolchain Synergy: Complements existing Laravel tooling (e.g., Pest, PHPStan, Laravel Pint) by enabling custom Psalm plugins for project-specific constraints (e.g., validation of Eloquent relationships, API contract enforcement).

Integration Feasibility

• Low Friction for PHP Teams: Requires minimal setup beyond Psalm installation (composer require vimeo/psalm + plugin API).
• Laravel-Specific Use Cases:
  • Validation Rules: Enforce custom type constraints (e.g., "this method must return a Carbon instance").
  • Dependency Analysis: Detect circular dependencies in service containers or Facades.
  • API Contracts: Validate request/response shapes (e.g., JSON:API compliance).
• IDE/Editor Support: Works with PHPStorm, VSCode (via Intelephense), and other tools leveraging Psalm’s static analysis.

Technical Risk

• Psalm Version Lock: Plugin API stability depends on Psalm’s semantic versioning. Major Psalm updates may require plugin adjustments.
• Performance Overhead: Heavy static analysis (e.g., deep type inference) could slow down CI/CD pipelines if not optimized.
• False Positives/Negatives: Custom rules may need tuning to avoid noisy warnings or missed issues.
• Documentation Gap: Lack of stars/activity suggests limited community examples; teams may need to build internal documentation.

Key Questions

1. Why Psalm Over PHPStan?
   • Does the team already use Psalm, or is this a new adoption?
   • Are there specific Psalm features (e.g., property type inference, callable return types) that justify the choice?
2. Plugin Scope:
   • Will plugins be internal (private repo) or open-source (published to Packagist)?
   • What’s the maintenance burden for keeping plugins updated with Psalm versions?
3. CI/CD Impact:
   • How will analysis results be actioned (e.g., block merges, annotate PRs)?
   • Are there performance baselines for acceptable runtime?
4. Team Adoption:
   • How will developers be trained to interpret Psalm plugin warnings?
   • Will plugins replace or complement existing tools (e.g., Pest tests, Laravel’s built-in validation)?

Integration Approach

Stack Fit

• PHP 8.1+: Psalm 5+ (latest stable) requires PHP 8.1; Laravel 9+ is compatible.
• Composer Ecosystem: Plugin API integrates via Composer, aligning with Laravel’s dependency management.
• Toolchain Placement:
  • Local Development: Run Psalm via ./vendor/bin/psalm or Laravel’s php artisan psalm (if using laravel-shift/psalm wrapper).
  • CI/CD: Execute as a pre-commit hook (e.g., via Laravel Pint’s php-cs-fixer) or GitHub Actions step.

Migration Path

1. Assess Current Tooling:
   • Audit existing static analysis (PHPStan, Pest, custom scripts) to identify gaps Psalm plugins could fill.
2. Pilot Plugin:
   • Start with a low-risk plugin (e.g., validating a single model’s type constraints).
   • Example: Enforce that a UserRepository method returns User[] (not mixed).
3. Gradual Rollout:
   • Add plugins to psalm.config.php incrementally:

     <?php
     return [
         'plugins' => [
             'vendor/package/plugin', // Custom or published plugin
         ],
     ];
     

4. CI/CD Integration:
   • Fail builds on warnings (configurable via --no-cache or --init flags).
   • Example GitHub Actions step:

     - name: Run Psalm
       run: vendor/bin/psalm --init --no-cache
     

Compatibility

• Laravel-Specific Quirks:
  • Dynamic Properties: Psalm may flag Laravel’s dynamic properties (e.g., $request->input()) as errors; suppress with @psalm-suppress.
  • Service Container: Use @psalm-suppress MixedReturnType for methods returning container-bound classes.
• Plugin Development:
  • Extend Psalm\Plugin\PluginInterface; leverage Psalm\CodeLocation for precise error reporting.
  • Example: Create a plugin to validate that Illuminate\Database\Eloquent\Model subclasses use fillable arrays correctly.

Sequencing

1. Phase 1: Setup
   • Install Psalm (composer require vimeo/psalm).
   • Configure psalm.config.php with project-specific rules.
2. Phase 2: Plugin Development
   • Build or adopt a plugin (e.g., for API contracts or business logic).
   • Test locally with ./vendor/bin/psalm --init.
3. Phase 3: CI/CD Enforcement
   • Integrate Psalm into the pipeline; start with warnings-only mode.
4. Phase 4: Optimization
   • Tune plugins to reduce false positives.
   • Document common suppression patterns (e.g., @psalm-suppress UndefinedClass).

Operational Impact

Maintenance

• Plugin Updates:
  • Monitor Psalm’s changelog for breaking changes; update plugins accordingly.
  • Automate testing: Run plugins against a test suite (e.g., PHPUnit) to catch regressions.
• Deprecation Management:
  • Psalm’s API may evolve; plan for plugin refactoring during major Psalm upgrades.
• Documentation:
  • Maintain a RUNBOOK for common Psalm plugin errors and their fixes.

Support

• Developer Onboarding:
  • Train teams on interpreting Psalm errors (e.g., MixedReturnType, UndefinedClass).
  • Provide cheat sheets for @psalm-* suppression annotations.
• Debugging Workflow:
  • Use psalm --log-errors=verbose to diagnose plugin issues.
  • Leverage Psalm’s IDE integration for real-time feedback.
• Escalation Path:
  • For plugin bugs, file issues in the plugin’s repo (if open-source) or internally.

Scaling

• Performance:
  • Cache results (--init flag) to avoid full analysis on every run.
  • Parallelize analysis in CI using psalm --parallel.
  • Exclude paths (e.g., vendor/, storage/) in psalm.config.php to reduce runtime.
• Team Growth:
  • Plugin modularity: Encourage small, focused plugins (e.g., one per domain) to isolate maintenance.
  • Community plugins: Reuse or contribute to published plugins (e.g., psalm/plugin-symfony) to reduce effort.
• Monorepo Challenges:
  • Use psalm.config.php’s project_files to scope analysis to relevant directories.

Failure Modes

Ramp-Up

• Quick Wins:
  • Start with existing Psalm rules (no plugins) to demonstrate value.
  • Example: Enforce null checks with --strict-types.
• Training:
  • Workshops: Hands-on session on writing a simple plugin (e.g., validate a Money class).
  • Pair Programming: Onboard senior devs first to build internal expertise.
• Metrics:
  • Track time-to-fix for Psalm warnings to justify investment.
  • Measure defect catch rate (e.g., bugs found by plugins vs. tests).
• Phased Rollout:
  • Phase 1: Optional local analysis (no CI enforcement).
  • Phase 2: CI warnings (non-blocking).
  • Phase 3: CI failures (blocking merges).