Leveling Up with Static Analysis: PHPStan vs. Psalm

When transitioning from legacy script-writing to advanced enterprise architecture, continuous automated testing alone is no longer enough. While runtime unit tests are reactive—only catching scenarios you explicitly thought to test—static analysis is completely proactive. It evaluates source code without execution to identify data flow bugs, structural mismatches, and architectural boundary violations before your application serves a single request.

Modern PHP engineering relies heavily on strict static analysis engines like PHPStan and Psalm to guarantee ironclad code predictability and unlock engine-level performance optimization.

Architectural Philosophies: PHPStan vs. Psalm

While both tools ingest standard PHPDoc annotations and enforce rigorous type boundaries, they approach compilation safety with unique underlying philosophies:

1. PHPStan: Type Correctness and Framework Deep-Dives

PHPStan targets semantic validity and strict type hierarchies. It is structured progressively through 11 rule levels (from 0 up to 10). PHPStan’s ultimate differentiator is its massive, community-driven extension framework. With specialized tools like Larastan (for Laravel) and specialized Symfony packages, PHPStan doesn't just analyze PHP syntax; it actively understands the magic, dynamic return behaviors, and magic macros of major frameworks.

2. Psalm: Explict Vulnerability and Security Taint Analysis

Psalm, originally open-sourced by Vimeo, treats type checking with a deeply conservative lens, often throwing explicit flags on uncertain mixed references where PHPStan might assume lenient bounds unless cranked to the absolute limit. Psalm’s true superpower is its built-in Taint Analysis. By treating input arrays ($_GET, $_POST) as contaminated sources and tracking them along the entire execution path down to hazardous sinks (PDO::query(), shell_exec, echo), Psalm acts as a Static Application Security Testing (SAST) tool natively.

Operational Metric	PHPStan	Psalm
Highest Strictness Setting	Level 10 (as of v2.0)	Level 1
Security Tracking	Extension dependent	Native Taint Analysis (`--taint-analysis`)
Configuration Format	Lightweight NEON (`phpstan.neon`)	Verbose XML (`psalm.xml`)
Framework Deep-Dives	Robust Ecosystem (e.g., Larastan)	Moderate (Plugins available)

Operating at 'Level Max'

Reaching the absolute pinnacle of strict analysis requires eliminating the wildcard mixed type. When types are left implicit or unchecked, the compiler engine must dynamically perform expensive runtime checks.

PHPStan Level 10: Enforces explicit checking on variables typing. Under Level 9, PHPStan reports errors for explicitly defined mixed types. Level 10 scales this aggressively by searching for implicitly-typed mixed allocations—such as un-annotated legacy third-party parameters or array payloads—and forces developers to map out type safety parameters. It also strictly validates purity across @phpstan-pure annotations, throwing compilation blockades if an impure point (like internal time mapping or I/O) is hit inside a pure method.
Psalm Level 1: Enforces total absence of type guessing, disallows expression assumptions, and mandates complete type-safety across all documentation block structures.

The Code Impact: From Loose Arrays to Strict Value Objects

Consider a common enterprise scenario: an e-commerce checkout route tracking input billing metadata.

php

1// The Legacy Antipattern: Loose Arrays and Blind Assumptions
2class CheckoutService {
3    public function processOrder(array $payload): void {
4        // High risk of Runtime Type Errors: Is 'amount' a string? An int? Is it even set?
5        $total = $payload['amount'] * 100;
6        $this->gateway->charge($total);
7    }
8}

Under Level Max analysis, both tools will aggressively reject this code because $payload has no declared schema shape, implicitly evaluating its items as mixed.

Here is the refactored, type-safe enterprise approach optimized natively for PHP 8.4+ execution engines, combining Constructor Property Promotion, Asymmetric Visibility, and complex Array Shape declarations:

php

 1declare(strict_types=1);
 2 
 3namespace App\Domain\Billing;
 4 
 5/**
 6 * @psalm-type InvoicePayload = array{
 7 * order_id: string,
 8 * amount_cents: int,
 9 * currency: string
10 * }
11 */
12final class InvoiceValueObject
13{
14    // PHP 8.4 Native Asymmetric Visibility protects state natively in the engine
15    public private(set) string $orderId;
16    public private(set) int $amountCents;
17 
18    /**
19     * @param string $orderId
20     * @param int $amountCents
21     */
22    public function __construct(string $orderId, int $amountCents)
23    {
24        if ($amountCents <= 0) {
25            throw new \InvalidArgumentException("Financial totals must exceed zero.");
26        }
27        $this->orderId = $orderId;
28        $this->amountCents = $amountCents;
29    }
30 
31    /**
32     * Factory pattern evaluating statically checked payload matrices
33     * @param array<string, mixed> $data
34     * @phpstan-param InvoicePayload $data
35     */
36    public static function fromPayload(array $data): self
37    {
38        return new self(
39            $data['order_id'],
40            $data['amount_cents']
41        );
42    }
43}

Step-by-Step Integration Guide

1. Setting Up Your Core Configuration

For PHPStan, manage configuration through a phpstan.neon file situated in your working root directory.

yaml-frontmatter

1# phpstan.neon
2parameters:
3    level: max
4    paths:
5        - src
6        - tests
7    checkMissingIterableValueType: true
8    checkMissingOverrideMethodAttribute: true
9    checkStrictPrintfPlaceholderTypes: true

For Psalm, run vendor/bin/psalm --init to generate a structured psalm.xml root file:

xml

 1<?xml version="1.0" encoding="UTF-8"?>
 2<psalm
 3    errorLevel="1"
 4    resolveFromConfigFile="true"
 5    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 6    xmlns="https://getpsalm.org/schema/config"
 7    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
 8>
 9    <projectFiles>
10        <directory name="src" />
11        <ignoreFiles>
12            <directory name="vendor" />
13        </ignoreFiles>
14    </projectFiles>
15</psalm>

2. Tackling Legacy Code: The Baseline Strategy

If you drop Level Max into an existing codebase, you will likely be hit with hundreds of errors instantly. You do not need to pause product delivery to refactor everything. Use a Baseline file. This records all existing type violations into an isolated configuration layer, instructing the parser to completely ignore past syntax anomalies while ensuring all new or modified code meets strict Level Max guidelines.

To lock in your baseline architecture, run:

shell

1# For PHPStan
2vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.neon
3 
4# For Psalm
5vendor/bin/psalm --set-baseline=psalm-baseline.xml

Include these baselines within your primary configurations (includes: [phpstan-baseline.neon]) to begin isolating future code shifts immediately.

DevSecOps: Automated CI/CD Execution Pipeline

To enforce zero-tolerance compilation rules, static analyzers must run automatically during every code change via continuous integration engines. Here is a high-throughput GitHub Actions deployment workflow showing how to configure parallel compilation jobs, capture dependency states via actions/cache, and halt the build if type verification drops below strict thresholds:

yaml-frontmatter

 1name: DevSecOps Quality Gate
 2
 3on:
 4  push:
 5    branches: [ main, develop ]
 6  pull_request:
 7    branches: [ main ]
 8
 9jobs:
10  static-analysis:
11    name: PHPStan & Psalm Level Max Gate
12    runs-on: ubuntu-latest
13    strategy:
14      fail-fast: false
15      matrix:
16        tool: ['phpstan', 'psalm']
17
18    steps:
19      - name: Checkout Code Repository
20        uses: actions/checkout@v4
21
22      - name: Setup PHP Environment Core
23        uses: shivammathur/setup-php@v2
24        with:
25          php-version: '8.4'
26          extensions: mbstring, intl, pdo_mysql, opcache
27          coverage: none
28
29      - name: Cache Persistent Composer Dependencies
30        uses: actions/cache@v3
31        with:
32          path: ~/.composer/cache/files
33          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
34          restore-keys: |
35            ${{ runner.os }}-composer-
36
37      - name: Install Runtime Optimization Dependency Graphs
38        run: composer install --no-interaction --no-progress --prefer-dist --optimize-autoloader
39
40      - name: Execute PHPStan Engine Verification
41        if: matrix.tool == 'phpstan'
42        run: vendor/bin/phpstan analyse --no-progress --error-format=github
43
44      - name: Execute Psalm Security Vulnerability Verification
45        if: matrix.tool == 'psalm'
46        run: vendor/bin/psalm --threads=2 --show-info=false

External Sources & Technical Documentation

PHPStan Official Engineering Portal & Core Command Manual: Explaining progressive validation structures, level management mechanics, and plugin integrations ( phpstan.org/user-guide ).
Psalm Engine Documentation Hub: Guide covering type-inferencing matrices and standard --taint-analysis secure payload tracking ( psalm.dev/docs ).
GitHub Actions Workflow Orchestration Reference: Best practices on pipeline isolation levels and handling secure production automations ( docs.github.com/en/actions/deployment ).
Composer Dependency Guide: Advanced insights regarding optimization rules like --optimize-autoloader and --classmap-authoritative flags ( getcomposer.org/doc ).