Technical Evaluation

Architecture Fit

Psalm is a static analysis tool designed to identify errors, type inconsistencies, and potential bugs in PHP codebases. For a Laravel-based application, it aligns well with:

Type Safety: Laravel (especially with PHP 8+) benefits from stricter typing, and Psalm can enforce this rigorously.
Legacy Codebases: Many Laravel projects mix older PHP (7.4/8.0) with modern practices, and Psalm’s backward-compatible fixes (e.g., docblock vs. native type hints) make it adaptable.
CI/CD Integration: Psalm’s exit codes (0=clean, 2=issues) fit naturally into CI pipelines (e.g., GitHub Actions, GitLab CI) to block merges on type errors.
Refactoring Support: The psalm-refactor and psalter tools enable safe, automated codebase improvements (e.g., namespace moves, unused property removal), critical for large Laravel monoliths.

Key Misalignments:

Performance Overhead: Psalm’s analysis is CPU-intensive (especially with --threads). For large Laravel apps (10K+ files), initial runs may require dedicated CI workers or caching strategies.
False Positives: Laravel’s dynamic features (e.g., magic methods, Illuminate\Support\Facades) may trigger noise. Custom stubs or configuration tweaks (e.g., stub_files) are needed to reduce false positives.

Integration Feasibility

Component	Feasibility	Notes
Laravel Core	High	Psalm works with vanilla PHP; Laravel’s dependency injection and service containers are analyzable.
Eloquent ORM	Medium	Requires custom stubs for dynamic queries (e.g., `Model::where()`).
Blade Templates	Low	Psalm ignores `.blade.php` by default; exclude patterns needed.
Artisan Commands	High	Static methods and closures are fully supported.
Third-Party Pkgs	Medium	Some packages (e.g., legacy ones) lack type info; stubs or ignore rules required.

Critical Paths:

Configuration: Laravel’s autoloading (PSR-4) and composer.json must be mirrored in psalm.json (e.g., src, app, database paths).
Stub Files: For frameworks like Laravel, pre-built stubs (e.g., laravel-stubs) are essential to avoid false positives.
CI Setup: Psalm should run post-testing (after composer install) to ensure dependencies are resolved.

Technical Risk

Risk Area	Severity	Mitigation
False Positives	High	Invest time in custom stubs and `psalm.json` tuning (e.g., `ignore_errors`).
Performance	Medium	Use `--threads=4` and `--diff` in CI; cache results between runs.
Backward Incompatibility	Low	Psalter’s `--safe-types` flag prevents risky auto-fixes.
Tooling Ecosystem	Medium	Limited Laravel-specific plugins; rely on community stubs (e.g., `vimeo/psalm-plugin-laravel`).
Maintainer Dependence	Low	MIT license; active community, but commercial support (Daniil Gentili) is an option.

Key Questions for the Team:

Codebase Maturity: How many legacy PHP 7.4 files exist? Psalm’s fixes for these may require manual review.
CI Budget: Can we allocate high-memory workers (Psalm needs ~4GB RAM for large apps)?
Developer Adoption: Will teams accept Psalm’s strictness (e.g., blocking merges on type errors)?
Stub Maintenance: Who will maintain custom stubs for third-party packages?
Refactoring Scope: Are there large-scale namespace/class moves planned? Psalm’s refactoring tool could accelerate this.

Integration Approach

Stack Fit

Psalm integrates seamlessly with:

PHP 8.0+: Native type hints are fully supported; Psalm can enforce stricter rules than PHP’s runtime.
Laravel 9+: Modern Laravel uses PHP 8.1+ and strict typing, reducing Psalm’s noise.
Composer: Installs as a dev dependency (composer require vimeo/psalm --dev).
CI Systems: Works with GitHub Actions, GitLab CI, and CircleCI via custom workflows.

Stack Limitations:

PHP 7.4: Psalm can analyze but may require docblock-only fixes (e.g., @return instead of : string).
Windows CI: Psalm’s file path handling may need adjustments for Windows-based runners.

Migration Path

Phase	Action	Tools/Config
1. Pilot Project	Run Psalm on a single module (e.g., `app/Http/Controllers`).	`./vendor/bin/psalm --init` → `psalm.json`
2. Configuration	Tune `psalm.json` for Laravel: add stubs, exclude Blade files.	`stub_files`, `exclude_patterns`
3. CI Integration	Add Psalm to CI; start with `--no-cache` to avoid flaky runs.	GitHub Actions: `psalm --diff`
4. Fix Critical Issues	Address high-severity errors (e.g., `TypeError`, `UndefinedMethod`).	`psalter --issues=MissingReturnType`
5. Refactoring	Use `psalm-refactor` for namespace moves or class renames.	`--move`, `--rename` flags
6. Full Enforcement	Set Psalm to fail builds on errors; gradually tighten rules.	`exit_code: 2` in `psalm.json`

Recommended Order:

Analyze → Identify false positives and configure stubs.
Fix → Use psalter for low-risk auto-fixes (e.g., MissingReturnType).
Refactor → Leverage psalm-refactor for large-scale changes.
Enforce → Block merges on type errors in CI.

Compatibility

Laravel Feature	Psalm Support	Workaround
Service Container	High (static analysis)	Stub `Illuminate\Container\Container`.
Eloquent Models	Medium (dynamic queries)	Stub `Illuminate\Database\Eloquent\Model`.
Blade Templates	Low (ignored by default)	Exclude via `exclude_patterns`.
Facades	Medium (e.g., `Route::get()`)	Stub `Illuminate\Support\Facades\Route`.
Magic Methods	High (e.g., `__call`, `__get`)	No action needed.
Traits	High	Fully supported.

Critical Compatibility Checks:

Run ./vendor/bin/psalm --init to auto-generate a baseline psalm.json.
Test with ./vendor/bin/psalm --no-cache --stats to validate coverage.
Use ./vendor/bin/psalm --shepherd to benchmark against similar Laravel projects.

Sequencing

Pre-requisites:
- Upgrade to PHP 8.0+ (if possible) to reduce docblock noise.
- Ensure Composer dependencies are resolved (composer install).
Initial Setup:
- Install Psalm: composer require vimeo/psalm --dev.
- Generate config: ./vendor/bin/psalm --init.
Configuration:
- Add Laravel stubs (e.g., vimeo/psalm-plugin-laravel).
- Exclude Blade files: "exclude_patterns": ["resources/views/**"].
Pilot Run:
- Run on a small module: ./vendor/bin/psalm app/Http/Controllers.
- Review top 10 errors for false positives.

CI Integration:

Add to .github/workflows/psalm.yml:

- name: Psalm
  run: vendor/bin/psalm --diff --threads=4

**Grad

Psalm Laravel Package