PHPStan: Static Analysis for PHP – Catch Bugs Before Runtime

You've just deployed a new feature. Hours later, your monitoring alerts spike with a 500 error. The culprit? A function expected an array but got null. This is the classic 'undefined array key' or 'call to a member function on null' that haunts PHP developers. While PHP's dynamic nature is flexible, it's also a breeding ground for runtime surprises.

Enter PHPStan: a static analysis tool that inspects your code without executing it. It's like having a senior developer review every line of your codebase, catching type errors, missing return types, and dead code before you even run a test. PHPStan operates on levels 0 to 9, where 0 is the most lenient and 9 is the strictest. You can start at a low level and gradually increase as your code improves.

In this tutorial, you'll learn how to install PHPStan, configure it for your project, and integrate it into your development workflow. We'll cover real-world scenarios like handling legacy code with baselines, custom rules, and debugging production incidents. By the end, you'll have a robust static analysis setup that prevents bugs from reaching users.

PHPStan is not just a linter; it's a powerful tool that understands PHP's type system, including generics (via PHPDoc), union types, and even frameworks like Laravel. It can detect issues like accessing undefined array keys, calling methods on nullable objects, and mismatched type hints. This proactive approach saves countless hours of debugging and improves code quality across your team.

Installing PHPStan

PHPStan is installed via Composer. You can install it globally or per-project. For most projects, per-project installation is recommended to avoid version conflicts.

Run the following command in your project root:

``bash composer require --dev phpstan/phpstan ``

This installs the latest stable version. If you need bleeding-edge features, you can use phpstan/phpstan:dev-master, but be cautious.

After installation, verify it works:

``bash vendor/bin/phpstan --version ``

You should see output like PHPStan - PHP Static Analysis Tool 1.12.x. Now you're ready to analyse your code.

<?php
// No code needed for installation, but here's a simple script to test:
echo "PHPStan installed successfully!";

Running Your First Analysis

Let's run PHPStan on a simple PHP file. Create a file test.php with a deliberate type error:

```php <?php

function add(int $a, int $b): int { return $a + $b; }

echo add('hello', 5); // Error: string passed instead of int ```

Now run PHPStan:

``bash vendor/bin/phpstan analyse test.php --level=0 ``

You'll see an error like:

`` ------ ------------------------------------------------------- Line test.php ------ ------------------------------------------------------- 7 Parameter #1 $a of function add expects int, string given. ------ ------------------------------------------------------- ``

PHPStan caught the type mismatch without executing the code. The --level flag sets the strictness. Level 0 is the most basic; level 9 is the strictest. Start low and increase gradually.

<?php

function add(int $a, int $b): int {
    return $a + $b;
}

echo add('hello', 5);

Configuring PHPStan with phpstan.neon

For real projects, you'll want a configuration file. Create phpstan.neon in your project root:

``neon parameters: level: 6 paths: - src excludePaths: - src/Legacy checkMissingIterableValueType: true checkGenericClassInNonGenericObjectType: true ``

Then run:

``bash vendor/bin/phpstan analyse ``

PHPStan automatically reads phpstan.neon. You can also specify a custom config with -c.

You can also define stub files for classes that PHPStan can't autoload (e.g., C extensions).

parameters:
    level: 6
    paths:
        - src
    excludePaths:
        - src/Legacy
    checkMissingIterableValueType: true
    checkGenericClassInNonGenericObjectType: true

Working with Baselines

When introducing PHPStan to an existing codebase, you'll likely have hundreds of errors. Instead of fixing them all at once, generate a baseline:

``bash vendor/bin/phpstan analyse --generate-baseline ``

This creates a phpstan-baseline.neon file listing all current errors. PHPStan will ignore them in future runs, so you can focus on new errors. Over time, fix baseline errors and regenerate the baseline to keep it clean.

To use the baseline, include it in your config:

``neon includes: - phpstan-baseline.neon ``

Now, when you run PHPStan, only new errors will be reported. This is essential for gradual adoption.

parameters:
    ignoreErrors:
        -
            message: '#^Call to an undefined method .+::oldMethod\(\)\.$#'
            path: src/Legacy/OldClass.php
        -
            message: '#^Parameter \#1 \$x of function expects int, string given\.$#'
            path: src/Legacy/AnotherClass.php

Custom Rules and Extensions

PHPStan supports custom rules via extensions. You can create your own rule by implementing the PHPStan\Rules\Rule interface. For example, a rule that forbids using var_dump in production code:

```php <?php

use PhpParser\Node; use PHPStan\Analyser\Scope; use PHPStan\Rules\Rule; use PHPStan\Rules\RuleErrorBuilder;

class NoVarDumpRule implements Rule { public function getNodeType(): string { return Node\Expr\FuncCall::class; }

public function processNode(Node $node, Scope $scope): array { if ($node->name instanceof Node\Name && $node->name->toString() === 'var_dump') { return [ RuleErrorBuilder::message('Do not use var_dump in production code.') ->line($node->getLine()) ->build(), ]; } return []; } } ```

Register the rule in your config:

``neon services: - class: NoVarDumpRule tags: - phpstan.rules.rule ``

Now PHPStan will flag any var_dump calls.

<?php

use PhpParser\Node;
use PHPStan\Analyser\Scope;
use PHPStan\Rules\Rule;
use PHPStan\Rules\RuleErrorBuilder;

class NoVarDumpRule implements Rule
{
    public function getNodeType(): string
    {
        return Node\Expr\FuncCall::class;
    }

    public function processNode(Node $node, Scope $scope): array
    {
        if ($node->name instanceof Node\Name && $node->name->toString() === 'var_dump') {
            return [
                RuleErrorBuilder::message('Do not use var_dump in production code.')
                    ->line($node->getLine())
                    ->build(),
            ];
        }
        return [];
    }
}

Integrating PHPStan into CI/CD

To prevent bugs from reaching production, run PHPStan in your CI pipeline. Here's an example for GitHub Actions:

```yaml name: PHPStan

on: [push, pull_request]

jobs: phpstan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: shivammathur/setup-php@v2 with: php-version: '8.2' tools: composer - run: composer install --no-progress - run: vendor/bin/phpstan analyse --no-progress --error-format=github ```

This will fail the build if PHPStan finds errors. Use --error-format=github for annotations in pull requests.

For GitLab CI:

``yaml phpstan: stage: test script: - composer install - vendor/bin/phpstan analyse --no-progress ``

Always use --no-progress in CI to avoid log clutter.

name: PHPStan

on: [push, pull_request]

jobs:
  phpstan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          tools: composer
      - run: composer install --no-progress
      - run: vendor/bin/phpstan analyse --no-progress --error-format=github