Psalm Plugin Laravel Package

Technical Evaluation

Architecture Fit

• Strong alignment with Laravel/PHP ecosystems: The plugin integrates seamlessly with Psalm, a leading static analysis tool for PHP, and PHP Standard Library (PSL), which is gaining traction for type-safe data validation. This is particularly valuable for Laravel applications where runtime validation (e.g., Laravel’s Validator) can be replaced or augmented with static type checking.
• Complementary to Laravel’s type system: While Laravel lacks native static typing, this plugin enables PSL-powered type inference for arrays, strings, and iterables, bridging the gap between dynamic and static analysis. This is especially useful for:
  • API request/response validation.
  • Eloquent model attribute constraints.
  • Business logic layers where PSL shapes define data contracts.
• Non-intrusive: The plugin operates at the analysis layer (Psalm) rather than modifying Laravel’s core, reducing risk of conflicts with existing tooling (e.g., PHPStan, Pest).

Integration Feasibility

• Low friction for adoption:
  • Composer-based installation (composer require php-standard-library/psalm-plugin --dev) aligns with Laravel’s dependency management.
  • Psalm plugin system is battle-tested; enabling the plugin via psalm-plugin enable is straightforward.
  • No Laravel-specific modifications required—works with any PHP project using Psalm.
• Compatibility with Laravel’s stack:
  • Psalm 4/5 support: Laravel teams using Psalm (e.g., for Laravel 9+) can leverage this plugin without version conflicts.
  • PSL 1.x/2.x support: If the application uses PSL for runtime validation, the plugin enhances static analysis without requiring PSL changes.
  • IDE integration: Psalm’s type hints (e.g., PhpStorm, VSCode) will reflect PSL shapes, improving developer experience.
• Potential challenges:
  • Psalm configuration overhead: Teams new to Psalm may need to invest time in configuring psalm.xml to include PSL types (e.g., psalm.parse_ini_files=false for Laravel’s .env files).
  • False positives/negatives: PSL’s strict typing may surface edge cases in Laravel’s dynamic features (e.g., magic methods, dynamic properties). Mitigation: Gradual rollout with psalm --init to auto-generate configs.

Technical Risk

Key Questions for the TPM

1. Adoption Scope:
   • Should this be mandatory for all PHP modules or opt-in for PSL-heavy components?
   • How will we measure success (e.g., % of PRs caught by Psalm, reduction in runtime validation errors)?
2. Tooling Integration:
   • Will we integrate Psalm into Git hooks (pre-commit) or CI gates (pre-merge)?
   • Should we extend Laravel’s phpunit.xml to include Psalm checks?
3. Team Readiness:
   • Does the team have Psalm experience? If not, what training/resources are needed?
   • How will we handle false positives (e.g., Laravel’s dynamic methods)?
4. Long-Term Vision:
   • Could this plugin replace runtime validation (e.g., Laravel’s Validator) for certain use cases?
   • Should we explore custom Psalm rules for Laravel-specific patterns (e.g., Eloquent relationships)?

Integration Approach

Stack Fit

• Primary Tools:
  • Psalm: Static analysis engine (already used in Laravel for type checking).
  • PHP Standard Library (PSL): Runtime validation library (if used in the codebase).
  • Composer: Dependency management (plugin is Composer-installable).
• Secondary Tools:
  • PHPStorm/VSCode: IDEs with Psalm integration for type hints.
  • GitHub Actions/GitLab CI: For running Psalm in CI pipelines.
• Laravel-Specific Considerations:
  • Artisan Commands: Could add a php artisan psalm:init command to auto-configure Psalm for Laravel.
  • Service Providers: Register Psalm’s autoloader in AppServiceProvider if not using global Composer autoloading.
  • Testing: Use PestPHP’s @psalm annotations to correlate test expectations with static types.

Migration Path

Compatibility

• Psalm Versions:
  • Psalm 5.x: Recommended for Laravel 9+ (supports PHP 8.1+).
  • Psalm 4.x: Fallback for older Laravel versions (test compatibility).
• PSL Versions:
  • PSL 2.x: Preferred for new code (better type coverage).
  • PSL 1.x: Supported but may lack some Psalm plugin features.
• PHP Versions:
  • PHP 8.1+: Required for Psalm 5.x and PSL 2.x.
  • PHP 8.0: May work with Psalm 4.x but lacks some PSL features.
• Laravel-Specific:
  • Dynamic Features: Psalm may flag Laravel’s magic methods (e.g., collect(), Str::of()) as "undefined." Mitigation:
    • Use @psalm-suppress annotations for known edge cases.
    • Extend Psalm’s stub files for Laravel classes.
  • Environment Files: Configure Psalm to ignore .env files (psalm.parse_ini_files=false).

Sequencing

1. Pre-requisite: Ensure Psalm is installed and configured in the project.
2. Plugin Enable: Run psalm-plugin enable php-standard-library/psalm-plugin.
3. Configuration: Update psalm.xml to include PSL types and suppress Laravel-specific noise.
4. Testing: Run Psalm on a small codebase to validate type improvements.
5. CI Integration: Add Psalm to the CI pipeline with a --strict flag.
6. Developer Onboarding: Document Psalm + PSL usage in the team’s internal wiki.
7. Iterate: Refine Psalm configs based on feedback and expand coverage.

Operational Impact

Maintenance

• Plugin Updates:
  • Monitor the GitHub repo for breaking changes (e.g., Psalm 6.x compatibility).
  • Update the plugin annually or when major Psalm/PSL versions are released.
• Psalm Configuration:
  • Maintain psalm.xml to suppress false positives (e.g., Laravel’s magic methods).
  • Document configuration changes in the team’s runbook.
• Dependency Management:
  • Pin Psalm and PSL versions in composer.json to avoid unexpected updates.
  • Use composer why-not to audit dependency conflicts.

Support

• Developer Support:
  • Provide a cheat sheet for common Psalm + PSL patterns (e.g., shapes, iterables).
  • Create a Slack channel or internal doc for troubleshooting (e