PHPStan Blog

Using PHPStan to Extract Data About Your Codebase

2026-03-26T00:00:00Z

PHPStan is known for finding bugs in your code. But that’s not all it can do. When PHPStan analyses your codebase, it builds a detailed model of every class, method, property, type, and relationship. All of that knowledge is accessible through Scope and Reflection. It’d be a shame to only use it for error reporting.

In this article, I’m going to show you how to use PHPStan as a data extraction tool — to query your codebase and produce machine-readable output you can use for documentation, visualization, or any other purpose.

The general approach #

The idea relies on three PHPStan extension points working together:

Collectors gather data about your codebase during analysis. They visit AST nodes, query the Scope and Reflection, and return structured data.
A rule that processes CollectedDataNode — a special node that gives you access to all collected data after the analysis is complete. Instead of reporting actual errors, it packages the collected data as metadata attached to rule errors.
A custom error formatter that reads the metadata from these errors and outputs machine-readable data (like JSON) instead of the usual error table.

This is a bit of a creative hack — we’re using PHPStan’s error reporting pipeline as a data transport mechanism. The “errors” aren’t real errors at all, they’re just carriers for the data we extracted.

All of this is tied together with a configuration file that registers the collectors, the rule, and the error formatter, and points PHPStan at the code you want to analyse.

Let’s walk through a real-world example.

Example: Generating a call map #

stella-maris/callmap by Andreas Heigl is a PHPStan extension that maps every method call in your codebase — which method calls which other method, and in which class. The result is a JSON file you can feed into CallMap CLI to generate a call graph.

The Collector #

The collector visits every MethodCall node in the AST and records four things: the calling class, the calling method, the called class, and the called method.

use PhpParser\Node;
use PhpParser\Node\Expr\MethodCall;
use PHPStan\Analyser\Scope;
use PHPStan\Collectors\Collector;

/**
 * @implements Collector<MethodCall, array{callingClass?: string, callingMethod: string, calledClass: string, calledMethod: string}>
 */
class MethodCallCollector implements Collector
{
    public function getNodeType(): string
    {
        return MethodCall::class;
    }

    public function processNode(Node $node, Scope $scope)
    {
        $methodName = $node->name;
        if (!$methodName instanceof Node\Identifier) {
            return null;
        }

        // Find the class that declares the called method
        $type = $scope->getType($node->var);
        $methodReflection = $scope->getMethodReflection($type, $methodName->name);
        if ($methodReflection === null) {
            return null;
        }

        $calledClass = $methodReflection->getDeclaringClass()->getName();

        // Find the calling context
        $callingClass = '';
        if ($scope->isInClass()) {
            $callingClass = $scope->getClassReflection()->getName();
        }

        return [
            'callingClass' => $callingClass,
            'callingMethod' => $scope->getFunction()?->getName(),
            'calledClass' => $calledClass,
            'calledMethod' => $methodName->name,
        ];
    }
}

The key thing here is that we’re using $scope->getMethodReflection() to resolve the declaring class of the called method. This means if you call $user->save() and save() is declared on a parent Model class, the collector records Model as the called class, not the concrete type. This is the kind of insight that would be difficult to get from simple text-based analysis.

The Rule #

The rule processes CollectedDataNode and wraps each row of collected data as a rule error with metadata:

use PHPStan\Node\CollectedDataNode;
use PHPStan\Rules\RuleErrorBuilder;

/**
 * @implements \PHPStan\Rules\Rule<CollectedDataNode>
 */
class Rule implements \PHPStan\Rules\Rule
{
    public function getNodeType(): string
    {
        return CollectedDataNode::class;
    }

    public function processNode(Node $node, Scope $scope): array
    {
        $errors = [];

        foreach ($node->get(MethodCallCollector::class) as $rows) {
            foreach ($rows as $row) {
                $errors[] = RuleErrorBuilder::message('Metadata')
                    ->identifier('callmapFormatter.data')
                    ->metadata($row)
                    ->build();
            }
        }

        return $errors;
    }
}

The $node->get(MethodCallCollector::class) call retrieves all data collected by MethodCallCollector across the entire codebase. Each entry is wrapped as a RuleError with a specific identifier and the original data stashed in the metadata.

The Error Formatter #

The error formatter reads these metadata-carrying errors and outputs them as JSON:

use PHPStan\Command\AnalysisResult;
use PHPStan\Command\ErrorFormatter\ErrorFormatter;
use PHPStan\Command\ErrorFormatter\TableErrorFormatter;
use PHPStan\Command\Output;

class CallmapFormatter implements ErrorFormatter
{
    public function __construct(
        private TableErrorFormatter $tableErrorFormatter,
    ) {}

    public function formatErrors(
        AnalysisResult $analysisResult,
        Output $output,
    ): int
    {
        if ($analysisResult->hasInternalErrors()) {
            // fall back to table output
            return $this->tableErrorFormatter->formatErrors(
                $analysisResult,
                $output,
            );
        }

        $json = [];
        foreach ($analysisResult->getFileSpecificErrors() as $error) {
            if ($error->getIdentifier() !== 'callmapFormatter.data') {
                // An unexpected real error — fall back to table output
                return $this->tableErrorFormatter->formatErrors(
                    $analysisResult,
                    $output,
                );
            }

            $metadata = $error->getMetadata();
            $json[] = [
                'callingClass' => $metadata['callingClass'],
                'callingMethod' => $metadata['callingMethod'],
                'calledClass' => $metadata['calledClass'],
                'calledMethod' => $metadata['calledMethod'],
            ];
        }

        file_put_contents('callmap.json', json_encode(['data' => $json]));

        return 0;
    }
}

The formatter checks for the specific error identifier. If it encounters any unexpected errors (real PHPStan errors from the analysed code), it falls back to the standard table output. This is a good safety measure — you want to know if something went wrong during the analysis instead of silently producing incomplete data.

The Configuration #

All of this is tied together with a NEON configuration file:

parameters:
    errorFormat: callmap
    paths:
        - src

    # Makes PHPStan not require a `--level` for `analyse` command.
    # Our rule will be the only one that runs
    customRulesetUsed: true

rules:
    - StellaMaris\Callmap\Rule

services:
    errorFormatter.callmap:
        class: StellaMaris\Callmap\CallmapFormatter
    -
        class: StellaMaris\Callmap\MethodCallCollector
        tags:
            - phpstan.collector

You run it like any other PHPStan analysis:

vendor/bin/phpstan analyse -c callmap.neon

And the output is a callmap.json file with every method call in your codebase:

{
    "data": [
        {
            "callingClass": "App\\Service\\UserService",
            "callingMethod": "getUser",
            "calledClass": "App\\Repository\\UserRepository",
            "calledMethod": "find"
        }
    ]
}

A more complex example: Extracting error identifiers #

I use this same pattern myself to generate the error identifier documentation on this website. Every PHPStan error has a unique identifier like argument.type or deadCode.unreachable. The identifier extractor scans the PHPStan source code and all 1st-party extensions to find where these identifiers are defined.

It’s more complex than the callmap example because it uses four different collectors, each targeting a different code pattern:

RuleErrorBuilderCollector — finds calls to RuleErrorBuilder::message()->identifier('...')
ErrorWithIdentifierCollector — finds calls to Error::withIdentifier('...')
RestrictedUsageCollector — finds calls to RestrictedUsage::create()
RuleConstructorParameterCollector — maps rule-to-rule injection dependencies

The last one is interesting — some rules delegate error reporting to helper classes. The extractor traces these dependency chains to figure out which top-level rule ultimately emits a given identifier.

The output is a JSON file that gets merged from multiple repositories, transformed, and used to generate the “Rules that report this error” section you can see at the bottom of each error identifier detail page.

Build your own #

If you want to extract data from your codebase, the pattern is always the same:

Write one or more collectors that implement PHPStan\Collectors\Collector and gather the data you’re interested in.
Write a rule for CollectedDataNode that packages collected data as error metadata.
Write a custom error formatter that reads the metadata and produces the output you need.
Create a NEON configuration file with customRulesetUsed: true and your custom errorFormat.

The possibilities are endless. You could generate dependency graphs between namespaces, find all usages of a deprecated API, catalogue all database queries, or map out event listener registrations. Anything PHPStan can see through its type inference and reflection, you can extract.

Do you like PHPStan and use it every day? Consider supporting further development of PHPStan. I’d really appreciate it!

Why Array String Keys Are Not Type-Safe in PHP

2026-03-19T00:00:00Z

PHP silently casts array keys. This is one of the oldest and most well-known quirks in the language. But I don’t think its consequences for type safety have been fully appreciated — until now.

The casting rules #

The PHP manual lists the following automatic key casts:

Strings containing valid decimal integers are cast to int. The key "8" is stored as 8. But "08" stays as a string because it’s not a valid decimal integer.
Floats are truncated to int. The key 8.7 becomes 8. Deprecated since PHP 8.1.
Bools are cast to int. true becomes 1, false becomes 0.
Null becomes the empty string "". Deprecated since PHP 8.5.

The classic demonstration:

$array = [
    1    => 'a',
    '1'  => 'b',
    1.5  => 'c',
    true => 'd',
];

var_dump(count($array)); // int(1)

Four entries, four different literal types — but PHP treats them all as the same key 1. Only the last value survives.

This isn’t just a quirky language feature. It breaks type safety in ways that static analysis has historically been unable to catch.

The strict_types trap #

Consider this innocent-looking code:

<?php declare(strict_types = 1);

function processKey(string $key): void
{
    // ...
}

/** @param array<string, mixed> $data */
function processData(array $data): void
{
    foreach ($data as $key => $value) {
        processKey($key);
    }
}

PHPStan sees $data typed as array<string, mixed>, so $key must be string. No errors reported. The code looks perfectly safe.

But at runtime, if $data was built with a key like '123', PHP stored it as int(123). When the foreach reaches that entry, $key is int, not string. With strict_types enabled, processKey($key) throws a TypeError.

PHPStan told you everything was fine. PHP disagrees. The type annotation array<string, mixed> promises something that PHP arrays simply cannot guarantee.

array_merge re-indexes your “string” keys #

array_merge() has different behaviour for integer keys and string keys: integer keys get re-indexed starting from 0, while string keys are preserved. When your string keys get silently cast to integers, you get re-indexing you didn’t ask for:

$a = ['100' => 'foo'];  // Stored as [100 => 'foo']
$b = ['200' => 'bar'];  // Stored as [200 => 'bar']

$merged = array_merge($a, $b);
// Result: [0 => 'foo', 1 => 'bar']
// Not ['100' => 'foo', '200' => 'bar']

The developer wrote string keys. They got integer keys. And array_merge silently re-indexed them.

Strict key lookups fail #

If you use array_keys() and then search with strict comparison, you’ll be surprised:

$data = ['123' => 'value'];
$keys = array_keys($data);
// $keys is [123] — an integer!

in_array('123', $keys, true);  // false!
// Strict comparison: '123' !== 123

You put in '123' as a string key, you search for '123' as a string — and it’s not found. Because PHP silently changed the key’s type behind your back.

A real-world example #

Imagine working with postal codes:

/** @return array{'1234aa', '2345bb'} */
function getPostals()
{
    return ['1234aa', '2345bb'];
}

$pc4Set = [];
foreach (getPostals() as $postal) {
    $pc4Set[substr($postal, 0, 4)] = true;
}

$pc4 = array_keys($pc4Set);
\PHPStan\dumpType($pc4[0]); // 1234|2345 (int, not string!)

The developer extracted the first 4 characters of each postal code using substr() — a function that returns a string. But because those strings happen to be '1234' and '2345', PHP casts them to integers when they’re used as array keys. The resulting array_keys() returns integers, not strings.

What PHPStan already does #

I’ve been laying the groundwork for solving this problem.

The online playground already notifies you about key casts. When you write a literal array or access an array with a key that will be cast, PHPStan tells you:

Key ‘1234’ (string) will be cast to 1234 (int) in the array access.

See this example in the playground »

Additionally, the reportNonIntStringArrayKey option (available since PHPStan 2.1.39) can report when non-int/non-string types like booleans, floats, or null are used as array keys:

parameters:
    reportNonIntStringArrayKey: true

$array = [];
$array[true] = 'value';  // Reported: Invalid array key type true.
$array[4.5] = 'value';   // Reported: Invalid array key type float.
$array[null] = 'value';  // Reported: Invalid array key type null.

These features catch explicit misuses of non-int/non-string types as keys. But they don’t solve the fundamental problem: any string might be a decimal integer string, and once it’s used as an array key, it silently becomes an int. PHPStan couldn’t do anything about this — until now.

PHPStan 2.2.0: non-decimal-int-string #

PHPStan 2.2.0 introduces two new types: non-decimal-int-string and decimal-int-string.

A decimal integer string is a string that PHP considers a valid decimal integer and would cast to int when used as an array key — like '0', '123', or '42'.

A non-decimal-int-string is any string that is not one of these — like 'hello', '08', '+1', or '1.5'.

The key insight: if your array keys are non-decimal-int-string, PHP will never cast them. They will always remain strings. This means array<non-decimal-int-string, mixed> is genuinely type-safe:

<?php declare(strict_types = 1);

function processKey(string $key): void
{
    // ...
}

/** @param array<non-decimal-int-string, mixed> $data */
function processData(array $data): void
{
    foreach ($data as $key => $value) {
        processKey($key); // Always safe — $key is guaranteed to be string
    }
}

No more TypeError at runtime. No more surprise re-indexing by array_merge. No more failed strict key lookups. The type system finally tells the truth about what your array keys actually are.

You can start using non-decimal-int-string in your type annotations today. It makes sense anywhere you need array keys that are guaranteed to stay as strings.

reportUnsafeArrayStringKeyCasting #

But you shouldn’t have to rewrite all your array<string, mixed> annotations by hand. That’s where the new reportUnsafeArrayStringKeyCasting config parameter comes in. It has three values:

null (default) — behaviour as it is today. No additional checks. Playground example »

'detect' — typehinted array<string, mixed> accepts other array<string, mixed>, but when you get a key out of it, the key type will be int|non-decimal-int-string instead of string. This reveals the potential issues in your code without requiring you to change any type annotations. Playground example »

'prevent' — typehinted array<string, mixed> is essentially treated as array<non-decimal-int-string, mixed>. It will only accept another array with safe string keys. Additionally, any string being used as an array key is correctly narrowed to int|non-decimal-int-string. This is the strictest mode and gives you the most protection. Playground example »

parameters:
    reportUnsafeArrayStringKeyCasting: detect # or: prevent

I’d recommend starting with detect to see how your codebase is affected, and then moving to prevent once you’ve addressed the findings.

Please note this is highly experimental and things can change as I adjust and make the types more practical and useful.

Do you like PHPStan and use it every day? Consider supporting further development of PHPStan. I’d really appreciate it!

PHPStan fully supports PHP 8.5!

2026-02-13T00:00:00Z

PHP 8.5 has been out for a while now, and so has PHPStan’s support for it. PHPStan 2.1.32, released back in November 2025, shipped with over 17 PHP 8.5-related changes. It was a massive community effort with many contributors. But I haven’t had the chance to sit down and write about all the interesting implementation details until now. It’s bigger than how it might seem on the first sight.

`#[NoDiscard]` attribute #

This is the feature I’m most excited about. It feels like it was made for static analysis, even though it’s really a runtime feature.

#[NoDiscard] lets you mark functions where ignoring the return value is a likely bug. Call such a function without doing anything with the result and PHP gives you a warning.

#[\NoDiscard]
function createDatabaseBackup(): string
{
    // ...
    return $backupPath;
}

// You probably wanted to do something with the path!
createDatabaseBackup();

PHPStan reports: Call to function createDatabaseBackup() on a separate line discards return value.

This is great for API design. Think about immutable objects where methods like withHeader() or withStatus() return a new instance — calling them without using the result is always a mistake. I’ve seen this bug in real codebases way more times than I’d like to admit.

The #[NoDiscard] errors are non-ignorable in PHPStan. The attribute is something you put in your code on purpose, so it doesn’t really make sense to then ignore the errors it produces. If you don’t want the errors, just remove the attribute.

The `(void)` cast #

PHP 8.5 also introduces a (void) cast to explicitly say “I know this returns something, and I don’t care”:

(void) createDatabaseBackup(); // No warning

But here’s a gotcha: you can’t use (void) inside other expressions:

$a = (void) someFunction(); // Error!
var_dump((void) someFunction()); // Error!

PHPStan reports: The (void) cast cannot be used within an expression.

PHPStan goes a step further #

PHPStan doesn’t just warn about discarding #[NoDiscard] return values — it also reports unnecessary (void) casts:

function canDiscard(): int
{
    return 1;
}

(void) canDiscard(); // PHPStan reports this!

PHPStan reports: Call to function canDiscard() in (void) cast but function allows discarding return value.

I always try to clamp new language features from both sides — if you forget to use the return value, that’s an error. But if you use (void) where there’s nothing to suppress, that’s also an error. This way you can’t go wrong either way.

Interaction with the pipe operator #

The NoDiscard rules also handle pipe operator expressions. When they encounter a Node\Expr\BinaryOp\Pipe, they unwrap the right-hand side to get at the actual function being called:

5 |> withSideEffects(...); // Error: return value discarded

Big thanks to Daniel Scherzer for the initial #[NoDiscard] implementation!

Pipe operator #

The pipe operator |> passes the left-hand side as the sole argument to a callable on the right-hand side:

$result = "Hello World"
    |> trim(...)
    |> strtolower(...)
    |> strlen(...);

// Instead of: strlen(strtolower(trim("Hello World")))

What’s interesting is that most of PHPStan doesn’t actually see the pipe operator at all. The AST gets rewritten on-the-fly to traditional function calls. This is pretty neat because it means all existing rules — type checking, argument validation, return type inference — just work with pipe expressions for free. No need to go and teach every single rule about a new syntax. The transformation handles FuncCall, MethodCall, and StaticCall with first-class callables, so $x |> $obj->method(...) simply becomes $obj->method($x).

The only rule that actually operates on the Pipe node directly is PipeOperatorRule, which checks that the callable on the right side doesn’t accept its parameter by reference:

// PHPStan reports:
// Parameter #1 $value of callable on the right side of pipe operator
// is passed by reference.
$x |> sort(...);

One syntax gotcha: arrow functions need parentheses when used in a pipe chain.

// This doesn't work:
5 |> fn ($x) => $x * 2;

// You need parentheses:
5 |> (fn ($x) => $x * 2);

Clone with #

We’ve all been writing withFoo() methods on immutable value objects for years. The new clone() with property overrides makes this pattern way cleaner:

readonly class Response
{
    public function __construct(
        public int $statusCode,
        public string $body,
    ) {}
}

$response = new Response(200, 'OK');
$error = clone($response, [
    'statusCode' => 500,
    'body' => 'Internal Server Error',
]);

PHPStan enforces the same rules for property assignments during cloning as it does for regular assignments — you can’t set private properties from outside the class, you can’t assign 'wrong' to an int property, and readonly properties can only be set from the appropriate scope.

It also infers types from clone expressions. If you clone a generic object and pass property overrides, PHPStan knows the result has those properties:

function doBar(object $object): void
{
    $cloned = clone($object, [
        'foo' => 1,
        'bar' => 2,
    ]);
    // PHPStan knows: object&hasProperty(bar)&hasProperty(foo)
}

New functions: `array_first()` and `array_last()` #

Finally, PHP gets proper functions for getting the first and last element of an array. Unlike reset() and end(), these don’t mess with the array’s internal pointer, so they’re truly pure functions.

PHPStan’s ArrayFirstLastDynamicReturnTypeExtension (#4499, thanks @canvural!) understands them precisely:

/** @param non-empty-array<int, string> $nonEmpty */
function doFoo(array $strings, array $nonEmpty): void
{
    array_first($strings);  // string|null
    array_first($nonEmpty);  // string (no null - guaranteed non-empty!)

    array_first([1 => 'a', 0 => 'b', 2 => 'c']); // 'a'|'b'|'c'
}

Notice how PHPStan narrows the return type based on whether the array can be empty — pass a non-empty-array and you’ll never get null back. We liked these functions so much we started using array_last() inside PHPStan itself right away (#4504, thanks @staabm!).

Deprecated casts #

PHP 8.5 deprecates the non-canonical cast names:

(integer) $m; // Deprecated! Use (int)
(boolean) $m; // Deprecated! Use (bool)
(double) $m;  // Deprecated! Use (float)
(binary) $m;  // Deprecated! Use (string)

The DeprecatedCastRule reports these so you can clean them up before upgrading.

Deprecated backtick operator #

The backtick operator for shell_exec() is deprecated in PHP 8.5:

$output = `ls -la`; // Deprecated!

Pssst, I have a secret for you. If you still have backticks in your source code, and PHPStan reports them as deprecated, try re-running your analysis but add --fix to the CLI options. You’ll be surprised what happens. I’ll have more to say about this later.

More PHP 8.5 goodies #

Here are some other notable changes PHPStan now supports:

#[Override] on properties — You can now use the #[Override] attribute on properties to assert that the property overrides a parent class property. There’s a new configuration option checkMissingOverridePropertyAttribute: true which can enforce them, similar to the one for methods.
Asymmetric visibility for static properties — Previously only instance properties supported different read/write visibility. Now static properties can too.
Closure::getCurrent() — Returns the current closure, enabling recursion without assigning to a variable first. PHPStan will know the correct signature of the closure if you fetch it with this method.
Closures and first-class callables in constant expressions — Static closures can now be used in constant expressions like property defaults, constants, and attribute parameters. They must be static and can’t capture variables.
Casts in constant expressions — You can now use type casts in constant initializers.
Support for deprecated traits — The #[Deprecated] attribute now works on traits.
FILTER_THROW_ON_FAILURE — New flag for filter_var() (#4495, thanks @canvural!).
Global constants support attributes — Constants can now have attributes.
PHP_BUILD_DATE type (#4468, thanks @staabm!).

Do you like PHPStan and use it every day? Consider supporting further development of PHPStan. I’d really appreciate it!

Restricted Usage Extensions - You Don't Always Need a Custom Rule

2025-04-27T00:00:00Z

Recently I’ve wanted to implement support for the @internal PHPDoc tag. The good news was there was already a similar set of rules in phpstan-deprecation-rules for the @deprecated tag. The bad news was the logic around @deprecated was hardcoded there, meaning I’d have to copy and adjust all the rules.

I thought there should be a better way because this is a very common use-case and not everyone should be forced to reinvent the same wheel. If people have a need for rules around attributes like #[NamespaceVisibility] or #[Friend], it should not be their job to figure out all the rules needed for a comprehensive coverage of these restrictions.

Take methods for example: Everyone would implement a rule for a traditional method call like $foo->doBar(1, 2, 3), but only a few would remember that first-class callables like $foo->doBar(...) should be covered as well.

Or class names. The new extension currently covers 26 locations where a class name can occur in PHP code or PHPDocs. The great advantage of the extension interface is that it’s future-proof and we can call it as new places with class names appear in the PHP language or as we add new PHPDoc features.

Besides taking advantage of the new extensions to implement the @internal tag rules, I went back to phpstan-deprecation-rules and refactored it with these new capabilities. It fixed small inconsistencies like missing class name check for static property fetch, wrong class names in some error messages, or reported line numbers in multi-line function signatures. With bleeding edge enabled, it will report deprecated class names in more places.

The Restricted Usage Extensions were released in PHPStan 2.1.13. Head over to the developer guide to learn how to use them!

Do you like PHPStan and use it every day? Consider supporting further development of PHPStan. I’d really appreciate it!

PHPStan 2.1: Support For PHP 8.4's Property Hooks, and More!

2024-12-31T00:00:00Z

This release is a culmination of the last four months of my work. Beginning in September, I branched 2.0.x off of 1.12.x. In order to support PHP 8.4 syntax, I had to upgrade to PHP-Parser v5. In order to upgrade to PHP-Parser v5, I had to release PHPStan 2.0. Which I did on November 11th, alongside the cute and also long-awaited PHPStan elephpant. PHPStan’s fans ordered 750 of those! They will be manufactured in China and sent on a ship to Europe which is going to take some time. I hope they’re going to find themselves in the hands of their happy owners in May-June 2025, as promised in the order confirmation emails.

Today’s PHPStan 2.1 brings full understanding of flagship PHP 8.4 features like property hooks, asymmetric visibility, and the #[Deprecated] attribute. As usual I’m going to describe what considerations went into supporting these language features in PHPStan.

Property hooks #

This is a massive and complex new language feature which is obvious just by looking at the length of the RFC. After reading it I wrote down about 70-80 todos about what should be done in PHPStan’s codebase in order to properly support it 😅 Out of those there are still around 32 todos left. They are not necessary enough to be included in this initial release, but it’d be nice to have them.

In short, property hooks let you intercept reading and writing properties with your own code. They also allow properties to be declared on interfaces for the first time in PHP. You can have virtual properties without a backing value stored in the object. And last but not least, hook bodies can be written with either long or short syntax.

Property hooks are very similar to class methods, but they are also their own thing. Which means I had to adjust or replicate a lot of existing rules around methods:

Additionally, there are new special rules for property hooks:

Backing value of non-virtual property must be read in get hook
Backing value of non-virtual property must be always assigned in set hook

Set hook parameter type can be wider than the actual property type so PHPStan also has to be aware of the types it allows to assign to properties in and out of hooks:

class Foo
{
	public int $i {
		get {
			return $this->i - 10;
		}
		set (int|string $value) {
			$this->i = $value; // string not allowed
		}
	}
}

$f = new Foo();
$f->i = rand(0,1) ? '10' : 'foo'; // string allowed

Property hooks also bring properties that can only be read, or can only be written, to the language:

interface Foo
{
	public int $i { get; }
	public int $j { set; }
}

function (Foo $f): void {
	$f->i = 42; // invalid
	echo $f->j; // invalid	
};

And my final remark is that access to properties can now be expected to throw any exception:

interface Foo
{
	public int $i { get; }
}

function (Foo $f): void {
	try {
		echo $f->i;
	} catch (MyCustomException) { // dead catch on PHP 8.3-, but not on 8.4+
		
	}
};

Even non-hooked properties are subject to this, because they can be overwritten in a subclass with a hook. If you want to persuade PHPStan that access to your properties cannot throw exceptions, make them private or final.

Hooks can be documented with @throws PHPDoc tag which improves analysis of try-catch blocks, same as with functions and methods.

I also posted a community update which goes into depth what you should do if you want to support property hooks in your custom rules.

A huge thanks to Jarda Hanslík for initial property hooks support in BetterReflection, and for many many subsequent fixes for bugs I found 😅

And also a huge thanks to Nikita Popov, not just for his work on PHP-Parser in general, but also for merging a couple of fixes I made, and also for fixing a couple of other issues I reported.

Asymmetric visibility #

PHP now allows for different properties visibility when reading then and when assigning them. So property can for example be publicly readable, but only privately writable.

This feature is much easier to grasp than property hooks, but also comes with a few gotchas.

Property that’s public-readable or protected-readable, but only privately writable, is implicitly final and cannot be overridden.
Acquiring reference to a property follows write visibility, not read visibility, so I added a new rule for that.

Similarly to property hooks, I also have a few nice-to-have todos left for later.

`#[Deprecated]` attribute #

This attribute allows the PHP engine trigger deprecated warnings.

I suspect it’s not that useful in practice because it’s allowed only above functions, methods, and class constants. Most notably, it can’t be used to mark entire classes deprecated. It also does not work for properties. This is something that PHP could address in the future.

Nevertheless, you can use it in PHPStan 2.1 in tandem with phpstan-deprecation-rules to mark deprecated code and have it reported when used.

Do you like PHPStan and use it every day? Consider sponsoring further development of PHPStan on GitHub Sponsors and also subscribe to PHPStan Pro! I’d really appreciate it!

Upgrading from PHPStan 1.x to 2.0

2024-11-11T00:00:00Z

This is the upgrading guide for PHPStan 2.0.

PHP version requirements #

PHPStan now requires PHP 7.4 or newer to run.

Upgrading guide for end users #

The best way to get ready for upgrade to PHPStan 2.0 is to update to the latest PHPStan 1.12 release and enable Bleeding Edge. This will enable the new rules and behaviours that 2.0 turns on for all users.

Also make sure to install and enable phpstan/phpstan-deprecation-rules.

Once you get to a green build with no deprecations showed on latest PHPStan 1.12.x with Bleeding Edge enabled, you can update all your related PHPStan dependencies to 2.0 in composer.json:

"require-dev": {
    "phpstan/phpstan": "^2.0",
    "phpstan/phpstan-deprecation-rules": "^2.0",
    "phpstan/phpstan-doctrine": "^2.0",
    "phpstan/phpstan-nette": "^2.0",
    "phpstan/phpstan-phpunit": "^2.0",
    "phpstan/phpstan-strict-rules": "^2.0",
    "phpstan/phpstan-symfony": "^2.0",
    "phpstan/phpstan-webmozart-assert": "^2.0",
    ...
}

Don’t forget to update 3rd party PHPStan extensions as well.

After changing your composer.json, run composer update 'phpstan/*' -W.

It’s up to you whether you go through the new reported errors or if you just put them all to the baseline ;) Everyone who’s on PHPStan 1.12 should be able to upgrade to PHPStan 2.0.

Noteworthy changes to code analysis #

Enhancements in handling parameters passed by reference
Validate inline PHPDoc @var tag type
List type enforced
Always true conditions always reported: previously reported only with phpstan-strict-rules, this is now always reported.

Removed option `checkMissingIterableValueType` #

It’s strongly recommended to add the missing array typehints.

If you want to continue ignoring missing typehints from arrays, add missingType.iterableValue error identifier to your ignoreErrors:

parameters:
	ignoreErrors:
		-
			identifier: missingType.iterableValue

Removed option `checkGenericClassInNonGenericObjectType` #

It’s strongly recommended to add the missing generic typehints.

If you want to continue ignoring missing typehints from generics, add missingType.generics error identifier to your ignoreErrors:

parameters:
	ignoreErrors:
		-
			identifier: missingType.generics

Removed `checkAlwaysTrue*` options #

These options have been removed because PHPStan now always behaves as if these were set to true:

checkAlwaysTrueCheckTypeFunctionCall
checkAlwaysTrueInstanceof
checkAlwaysTrueStrictComparison
checkAlwaysTrueLooseComparison

Removed option `excludes_analyse` #

It has been replaced with excludePaths.

Paths in `excludePaths` and `ignoreErrors` have to be a valid file path or a fnmatch pattern #

If you are excluding a file path that might not exist but you still want to have it in excludePaths, append (?):

parameters:
	excludePaths:
		- tests/*/data/*
		- src/broken
		- node_modules (?) # optional path, might not exist

If you have the same situation in ignoreErrors (ignoring an error in a path that might not exist), use reportUnmatchedIgnoredErrors: false.

parameters:
	reportUnmatchedIgnoredErrors: false

Appending (?) in ignoreErrors is not supported.

Changes in 1st party PHPStan extensions #

phpstan-doctrine
- Removed config parameter searchOtherMethodsForQueryBuilderBeginning (extension now behaves as when this was set to true)
- Removed config parameter queryBuilderFastAlgorithm (extension now behaves as when this was set to false)
phpstan-symfony
- Removed legacy options with _ in the name
- container_xml_path -> use containerXmlPath
- constant_hassers -> use constantHassers
- console_application_loader -> use consoleApplicationLoader

Minor backward compatibility breaks #

Removed unused config parameter cache.nodesByFileCountMax
Removed unused config parameter memoryLimitFile
Removed unused feature toggle disableRuntimeReflectionProvider
Removed unused config parameter staticReflectionClassNamePatterns
Remove fixerTmpDir config parameter, use pro.tmpDir instead
Remove tempResultCachePath config parameter, use resultCachePath instead
additionalConfigFiles config parameter must be a list

Upgrading guide for extension developers #

Please switch to PHPStan 2.0 in a new major version of your extension. It’s not feasible to try to support both PHPStan 1.x and PHPStan 2.x with the same extension code.

You can definitely get closer to supporting PHPStan 2.0 without increasing major version by solving reported deprecations and other issues by analysing your extension code with PHPStan & phpstan-deprecation-rules & Bleeding Edge, but the final leap and solving backward incompatibilities should be done by requiring "phpstan/phpstan": "^2.0" in your composer.json, and releasing a new major version.

PHPStan now uses nikic/php-parser v5 #

See UPGRADING guide for PHP-Parser.

The most notable change is how throw statement is represented. Previously, throw statements like throw $e; were represented using the Stmt\Throw_ class, while uses inside other expressions (such as $x ?? throw $e) used the Expr\Throw_ class.

Now, throw $e; is represented as a Stmt\Expression that contains an Expr\Throw_. The Stmt\Throw_ class has been removed.

PHPStan now uses phpstan/phpdoc-parser v2 #

See UPGRADING guide for phpstan/phpdoc-parser.

Returning plain strings as errors no longer supported, use RuleErrorBuilder #

Identifiers are also required in custom rules.

Learn more: Using RuleErrorBuilder to enrich reported errors in custom rules

Before:

return ['My error'];

After:

return [
    RuleErrorBuilder::message('My error')
        ->identifier('my.error')
        ->build(),
];

Deprecate various `instanceof *Type` in favour of new methods on `Type` interface #

Learn more: Why Is instanceof *Type Wrong and Getting Deprecated?

Removed deprecated `ParametersAcceptorSelector::selectSingle()` #

Use ParametersAcceptorSelector::selectFromArgs() instead. It should be used in most places where selectSingle() was previously used, like dynamic return type extensions.

Before:

$defaultReturnType = ParametersAcceptorSelector::selectSingle($functionReflection->getVariants())->getReturnType();

After:

$defaultReturnType = ParametersAcceptorSelector::selectFromArgs(
    $scope,
    $functionCall->getArgs(),
    $functionReflection->getVariants()
)->getReturnType();

If you’re analysing function or method body itself and you’re using one of the following methods, ask for getParameters() and getReturnType() directly on the reflection object:

Before:

$function = $node->getFunctionReflection();
$returnType = ParametersAcceptorSelector::selectSingle($function->getVariants())->getReturnType();

After:

$returnType = $node->getFunctionReflection()->getReturnType();

Changed `TypeSpecifier::create()` and `SpecifiedTypes` constructor parameters #

PHPStan\Analyser\TypeSpecifier::create() now accepts (all parameters are required):

Expr $expr
Type $type
TypeSpecifierContext $context
Scope $scope

If you want to change $overwrite or $rootExpr (previous parameters also used to be accepted by this method), call setAlwaysOverwriteTypes() and setRootExpr() on SpecifiedTypes (object returned by TypeSpecifier::create()). These methods return a new object (SpecifiedTypes is immutable).

SpecifiedTypes constructor now accepts:

array $sureTypes
array $sureNotTypes

If you want to change $overwrite or $rootExpr (previous parameters also used to be accepted by the constructor), call setAlwaysOverwriteTypes() and setRootExpr(). These methods return a new object (SpecifiedTypes is immutable).

`ConstantArrayType` no longer extends `ArrayType` #

Type::getArrays() now returns list<ArrayType|ConstantArrayType>.

Using $type instanceof ArrayType is being deprecated anyway so the impact of this change should be minimal.

Changed `TypeSpecifier::specifyTypesInCondition()` #

This method now longer accepts Expr $rootExpr. If you want to change it, call setRootExpr() on SpecifiedTypes (object returned by TypeSpecifier::specifyTypesInCondition()). setRootExpr() method returns a new object (SpecifiedTypes is immutable).

Node attributes `parent`, `previous`, `next` are no longer available #

Learn more: Preprocessing AST for custom rules

Removed config parameter `scopeClass` #

As a replacement you can implement PHPStan\Type\ExpressionTypeResolverExtension interface instead and register it as a service.

Removed `PHPStan\Broker\Broker` #

Use PHPStan\Reflection\ReflectionProvider instead.

BrokerAwareExtension was also removed. Ask for ReflectionProvider in the extension constructor instead.

Instead of PHPStanTestCase::createBroker(), call PHPStanTestCase::createReflectionProvider().

List type is enabled for everyone #

Removed static methods from AccessoryArrayListType class:

isListTypeEnabled()
setListTypeEnabled()
intersectWith()

Instead of AccessoryArrayListType::intersectWith($type), do TypeCombinator::intersect($type, new AccessoryArrayListType()).

Minor backward compatibility breaks #

Classes that were previously @final were made final
Parameter $callableParameters of MutatingScope::enterAnonymousFunction() and enterArrowFunction() made required
Parameter StatementContext $context of NodeScopeResolver::processStmtNodes() made required
ClassPropertiesNode - remove $extensions parameter from getUninitializedProperties()
Type::getSmallerType(), Type::getSmallerOrEqualType(), Type::getGreaterType(), Type::getGreaterOrEqualType(), Type::isSmallerThan(), Type::isSmallerThanOrEqual() now require PhpVersion as argument.
CompoundType::isGreaterThan(), CompoundType::isGreaterThanOrEqual() now require PhpVersion as argument.
Removed ReflectionProvider::supportsAnonymousClasses() (all reflection providers support anonymous classes)
Remove ArrayType::generalizeKeys()
Remove ArrayType::count(), use Type::getArraySize() instead
Remove ArrayType::castToArrayKeyType(), Type::toArrayKey() instead
Remove UnionType::pickTypes(), use pickFromTypes() instead
Remove RegexArrayShapeMatcher::matchType(), use matchExpr() instead
Remove unused PHPStanTestCase::$useStaticReflectionProvider
Remove PHPStanTestCase::getReflectors(), use getReflector() instead
Remove ClassReflection::getFileNameWithPhpDocs(), use getFileName() instead
Remove AnalysisResult::getInternalErrors(), use getInternalErrorObjects() instead
Remove ConstantReflection::getValue(), use getValueExpr() instead. To get Type from Expr, use Scope::getType() or InitializerExprTypeResolver::getType()
Remove PropertyTag::getType(), use getReadableType() / getWritableType() instead
Remove GenericTypeVariableResolver, use Type::getTemplateType() instead
Rename Type::isClassStringType() to Type::isClassString()
Remove Scope::isSpecified(), use hasExpressionType() instead
Remove ConstantArrayType::isEmpty(), use isIterableAtLeastOnce()->no() instead
Remove ConstantArrayType::getNextAutoIndex()
Removed methods from ConstantArrayType - getFirst*Type and getLast*Type
- Use getFirstIterable*Type and getLastIterable*Type instead
Remove ConstantArrayType::generalizeToArray()
Remove ConstantArrayType::findTypeAndMethodName(), use findTypeAndMethodNames() instead
Remove ConstantArrayType::removeLast(), use Type::popArray() instead
Remove ConstantArrayType::removeFirst(), use Type::shiftArray() instead
Remove ConstantArrayType::reverse(), use Type::reverseArray() instead
Remove ConstantArrayType::chunk(), use Type::chunkArray() instead
Remove ConstantArrayType::slice(), use Type::sliceArray() instead
Made TypeUtils thinner by removing methods:
- Remove TypeUtils::getArrays() and getAnyArrays(), use Type::getArrays() instead
- Remove TypeUtils::getConstantArrays() and getOldConstantArrays(), use Type::getConstantArrays() instead
- Remove TypeUtils::getConstantStrings(), use Type::getConstantStrings() instead
- Remove TypeUtils::getConstantTypes() and getAnyConstantTypes(), use Type::isConstantValue() or Type::generalize()
- Remove TypeUtils::generalizeType(), use Type::generalize() instead
- Remove TypeUtils::getDirectClassNames(), use Type::getObjectClassNames() instead
- Remove TypeUtils::getConstantScalars(), use Type::isConstantScalarValue() or Type::getConstantScalarTypes() instead
- Remove TypeUtils::getEnumCaseObjects(), use Type::getEnumCases() instead
- Remove TypeUtils::containsCallable(), use Type::isCallable() instead
Removed Scope::doNotTreatPhpDocTypesAsCertain(), use getNativeType() instead
Parameter $isList in ConstantArrayType constructor can only be TrinaryLogic, no longer bool
Parameter $nextAutoIndexes in ConstantArrayType constructor can only be non-empty-list<int>, no longer int
Remove ConstantType interface, use Type::isConstantValue() instead
acceptsNamedArguments() in FunctionReflection, ExtendedMethodReflection and CallableParametersAcceptor interfaces returns TrinaryLogic instead of bool
Remove FunctionReflection::isFinal()
Type::getProperty() now returns ExtendedPropertyReflection
Remove __set_state() on objects that should not be serialized in cache
Parameter $selfClass of TypehintHelper::decideTypeFromReflection() no longer accepts string
LevelsTestCase::dataTopics() data provider made static
PHPStan\Node\Printer\Printer no longer autowired as PhpParser\PrettyPrinter\Standard, use PHPStan\Node\Printer\Printer in the typehint
Remove Type::acceptsWithReason(), Type:accepts() return type changed from TrinaryLogic to AcceptsResult
Remove CompoundType::isAcceptedWithReasonBy(), CompoundType::isAcceptedBy() return type changed from TrinaryLogic to AcceptsResult
Remove Type::isSuperTypeOfWithReason(), Type:isSuperTypeOf() return type changed from TrinaryLogic to IsSuperTypeOfResult
Remove CompoundType::isSubTypeOfWithReasonBy(), CompoundType::isSubTypeOf() return type changed from TrinaryLogic to IsSuperTypeOfResult
Remove TemplateType::isValidVarianceWithReason(), changed TemplateType::isValidVariance() return type to IsSuperTypeOfResult
RuleLevelHelper::accepts() return type changed from bool to RuleLevelHelperAcceptsResult
Changes around ClassConstantReflection
- Class ClassConstantReflection removed from BC promise, renamed to RealClassConstantReflection
- Interface ConstantReflection renamed to ClassConstantReflection
- Added more methods around PHPDoc types and native types to the (new) ClassConstantReflection
- Interface GlobalConstantReflection renamed to ConstantReflection
Renamed interfaces and classes from *WithPhpDocs to Extended*
- ParametersAcceptorWithPhpDocs -> ExtendedParametersAcceptor
- ParameterReflectionWithPhpDocs -> ExtendedParameterReflection
- FunctionVariantWithPhpDocs -> ExtendedFunctionVariant
ClassPropertyNode::getNativeType() return type changed from AST node to Type|null
Class PHPStan\Node\ClassMethod (accessible from ClassMethodsNode) is no longer an AST node
- Call PHPStan\Node\ClassMethod::getNode() to access the original AST node

PHPStan 2.0 Released With Level 10 and Elephpants!

2024-11-11T00:00:00Z

PHPStan 1.0 was released a little over three years ago. I’m happy to report the project is thriving! We did about 176 new releases since then, implementing new features, fixing bugs, and laying the groundwork for 2.0. Yeah, we didn’t catch a break and we didn’t rest on our laurels.

I’ve been looking forward to 2.0 for a long time. Everyone will finally be able to enjoy new features we’ve been working on. Some of them have already been enjoyed by early adopters for more than two years.

But code and analysis changes are not the only things being released today! PHPStan joins the family of elephpants with its own take on the legendary PHP mascot.

You can also order PHPStan T-shirts again, in both blue and white, and straight/fitted cut:

We’re accepting orders for the next four weeks (until Sunday, December 8th), so don’t miss the opportunity and order the elephpant and T-shirt today! I can’t wait to see them in the wild.

And now to the code part. The comprehensive release notes are massive, consisting of over 180 items. That’s why, for the first time ever, PHPStan 2.0 also comes with easy-to-follow upgrading guide, for both end users and extension developers.

It’s really hard to pick and choose my favourite features and changes from 2.0, but I’ll try. Here we go:

Level 10 #

New challenge for the level max enthusiasts! Previously added level 9 acknowledges using mixed in your code isn’t actually safe at all, and that you should really do something about it. But it has some blind spots and still lets some errors through. Internally it’s named checkExplicitMixed. Meaning it will report errors for explicitly-typed mixed values in your code.

Level 6 forces you to add missing types. If you manage to skip that with the help of ~~cheating~~, ahem, the baseline, or if you call a third party code that doesn’t use a lot of return types, unknown types may be present in your code during analysis. These are implicitly-typed mixed, and they will be picked up by level 10

List type #

PHP arrays are really powerful, but they represent several computer science concepts in a single data structure, and sometimes it’s difficult to work with that. That’s why it’s useful to narrow it down when we’re sure we only want a single concept like a list.

List in PHPStan is an array with sequential integer keys starting at 0 and with no gaps. It joins many other advanced types expressible in PHPDocs:

/** @param list<int> $listOfIntegers */
public function doFoo(array $listOfIntegers): void
{
}

Lower memory consumption leads to faster performance #

PHPStan used to be a really hungry beast. To the point of being killed by CI runners because it consumed not just all the memory up to the memory_limit in php.ini, but also all the memory assigned to the runner hardware.

Now it’s a less hungry beast. How did I make it happen? It’s useful to realize what’s going on inside a running program. It’s fine to consume memory as useful things are being achieved, but in order to consume less memory in total, it has to be freed afterwards so that it can be used again by different data needed when analysing the next file in line.

To debug memory leaks, I use the php-meminfo extension. I quickly realized that most of the memory is occupied by AST nodes. PHP frees the memory occupied by an object when there are no more references to it ^[1]. It didn’t work in case of AST nodes because they kept pointing at each other:

Getting rid of parent/previous/next node attributes is a backward compatibility break for custom rules that read them. I’ve written an article on how to make these rules work again even without those memory-consuming references.

The object graph is now obviously cleaner and with no reference cycles:

In my testing PHPStan now consumes around 50–70 % less memory on huge projects with thousands of files. Analysing PrestaShop 8.0 codebase now takes 3 minutes instead of 9 minutes in GitHub Actions with 2 CPU cores.

Validate inline PHPDoc `@var` tag type #

There are multiple problems with inline @var PHPDoc tag. PHP developers use it for two main reasons:

To fix wrong 3rd party PHPDocs. A dependency ^[2] might have @return string in a PHPDoc but in reality can return null as well.
To narrow down the returned type. When a function returns string|null but we know that in this case it can only return string.

/** @var Something $a */
$a = makeSomething();

By looking at the analysed code we can’t really tell which scenario it is. That’s why PHPStan always trusted the type in @var and didn’t report any possible mistakes. Obviously that’s dangerous because the type in @var can get out of sync and be wrong really easily. But I came up with an idea what we could report without any false positives, keeping existing use-cases in mind.

PHPStan 2.0 validates the inline @var tag type against the native type of the assigned expression. It finds the lies spread around in @var tags:

function doFoo(): string
{
    // ...
}

/** @var string|null $a */
$a = doFoo();

// PHPDoc tag @var with type string|null is not subtype of native type string.

It doesn’t make sense to allow string|null, because the type can never be null. PHPStan says “string|null is not subtype of native type string”, implying that only subtypes are allowed. Subtype is the same type or narrower, meaning that string or non-empty-string would be okay.

By default PHPStan isn’t going to report anything about the following code:

/** @return string */
function doFoo()
{
    // ...
}

/** @var string|null $a */
$a = doFoo();

Because the @return PHPDoc might be wrong and that’s what the @var tag might be trying to fix. If you want this scenario to be reported too, enable reportWrongPhpDocTypeInVarTag, or install phpstan-strict-rules.

I’d like the PHP community to use inline @var tags less and less over time. There are many great alternatives that promote good practices and code deduplication: Conditional return types, @phpstan-assert, generics, stub files for overriding 3rd party PHPDocs, or dynamic return type extensions.

Checking truthiness of `@phpstan-pure` with impure points #

Pure functions always return the same value for the same input (arguments and current object state). They also don’t have any side effects like depending on current time, random number generator, or IO like reading file contents or accessing resources over the network.

It’s useful to mark functions and methods with @phpstan-pure if their logic should be pure. PHPStan 2.0 now enforces this annotation, meaning it will report any impure code inside as an error.

We achieved that with the help of impure points. For every statement and expression type PHP supports PHPStan decides if it’s pure or not.

Knowing impure points for any code also helps PHPStan to report more dead code. There’s no point in calling a pure method on a separate line without using its result. If it does not have any side effect, and we’re not using the returned value, then we can safely delete this line:

// Call to method Foo::pureMethod() on a separate line has no effect.
$this->pureMethod();

Also: if a void method does not have any impure points, it doesn’t have to exist:

// Method Foo::add() returns void but does not have any side effects.
private function add(int $a, int $b): void
{
    $c = $a + $b;
}

Less caching, disk space cleanup #

Getting rid of a cache without slowing down the analysis is a clear win. Less stuff to invalidate, less stuff to worry about, less disk space to occupy.

PHPStan used to cache information whether a function is variadic because of func_get_args() call or similar in its body. I realized we have this information freshly available in each run anyway, so we don’t need to cache it. This saves literally tens of thousands of files that PHPStan previously needed to save to disk and then read.

PHPStan now solely relies on the result cache to speed up the analysis.

We took this opportunity to clean up old cache items on disk, so on the first PHPStan 2.0 run you might see some previously occupied disk space free up. On a proprietary project I test PHPStan on it freed up about 1 GB of space.

The future #

I said it three years ago, and I’m saying it again. PHPStan’s future is bright. It’s my full-time job thanks to PHPStan Pro and GitHub Sponsors, splitting the revenue roughly 50-50 between them.

I love my job, I love PHP and I don’t plan to stop. Contributors are very active and indispensable. PHPStan has a thriving ecosystem of extensions as well.

I have a lot of ambitious and even crazy ideas I’d like to try out. But the first thing I will address once the dust settles on 2.0 is adding support for PHP 8.4. You can expect it to be added before the end of 2024.

Do you like PHPStan and use it every day? Consider sponsoring further development of PHPStan on GitHub Sponsors and also subscribe to PHPStan Pro! I’d really appreciate it!

That’s called reference counting. ↩︎
That probably doesn’t use static analysis. ↩︎

PHPStan 1.12: Road to PHPStan 2.0

2024-08-27T00:00:00Z

After three years since the initial PHPStan 1.0 release, we’re getting closer to PHPStan 2.0. After sifting through my list of ideas for the new major version, I realized I can move some of them forward and release them in 1.x series and hide them behind the Bleeding Edge config toggle, so they can be enjoyed by PHPStan users sooner.

This isn’t true just for PHPStan 1.12 but ever since 1.0. If you enable Bleeding Edge, you basically live in the future. You get new rules and behavior changes that will be enabled for everyone in the next major version. That’s your reward as an early adopter.

Here’s an equation:

PHPStan 2.0 = PHPStan 1.12 + Bleeding Edge + BC breaks

When you upgrade to PHPStan 1.12 and enable Bleeding Edge, you can get mostly ready for PHPStan 2.0 today.

But enough about the future. Here’s what’s new in today’s 1.12 release.

General availability of precise type inference for regular expressions #

This is a rare example of a feature that began its life in Bleeding Edge but got out of it sooner than the next major version. Because of its complexity we needed a staged rollout to weed out the bugs.

First introduced in 1.11.6, and improved by dozens of pull requests since then, this feature is about figuring out the precise type for $matches by-ref argument coming from preg_match() and other related functions:

if (preg_match('/Price: (?<currency>£|€)\d+/', $s, $matches, PREG_UNMATCHED_AS_NULL)) {
	// array{0: string, currency: non-empty-string, 1: non-empty-string}
	\PHPStan\dumpType($matches);
}

Markus Staab and Jordi Boggiano of Composer fame worked really hard on this. It brings a whole new level of precision to PHPStan’s type inference.

From what I gathered, this ability is pretty unique and not many programming languages offer it. And now we have it in PHP!

PHPStan performs four categories of sanity checks on types in PHPDocs:

Missing types: performed on level 6 and up, it enforces specifying array value types, generic types, and optionally also callable signatures.
Existing classes: looks for nonexistent classes and also trait references
Unresolvable types: looks for never bottom type that resulted from impossible intersections like string&int, referencing undefined constants like Foo::BAR, etc.
Generics type checks: checks sanity of generic types. Compares the number of type variables in a type against the number of @template above the class declaration, checks the subtyping of bounds, etc.

These type checks weren’t performed consistently for all supported PHPDocs tags. We were missing most or all of these checks for these tags:

@param-out
@param-closure-this
@param-immediately-invoked-callable and @param-later-invoked-callable
@phpstan-self-out
@mixin
@property
@method
@extends, @implements, @use

PHPStan 1.12 fixes that. Wrong and corrupted types are checked consistently across the board. Because these are essentially new rules which would cause new errors reported for most codebases, they were added only to Bleeding Edge, and will be enabled for everyone in PHPStan 2.0.

Too wide private property type #

Another addition to Bleeding Edge checks if a type could be removed from a private property union type, without affecting anything.

// if string is never assigned to `$this->a`, we can remove it from the type
private int|string $a;

PHPStan already had this rule for function and method return types, and now we can enjoy it for properties too.

PHP 8.4 runtime support #

Implementing support for new PHP version in PHPStan comes in four phases:

Make sure PHPStan runs on the new PHP version and all tests pass.
Understand added functions and changed signatures of existing functions in the new PHP version.
Understand new syntax and features. This removes false errors when analysing code written against the new PHP version.
Implement new rules specific to new syntax and features. Discover which parts of the new PHP features are tricky and need to be checked with new static analysis rules.

PHPStan 1.12 implements the first two phases. It runs on PHP 8.4 without any deprecation notices, and new functions like array_find() are already known.

Because of new syntax, the rest is dependent on upgrading to nikic/PHP-Parser v5 which has to be done in a major version.

My plan for the upcoming months is straightforward: finish and release PHPStan 2.0, and then work on PHP 8.4-specific features.

Me and PHPStan contributors put a lot of hard work into this release. I hope that you’ll really enjoy it and take advantage of these new features! We’re going to be waiting for everyone’s feedback on GitHub.

Do you like PHPStan and use it every day? Consider sponsoring further development of PHPStan on GitHub Sponsors and also subscribe to PHPStan Pro! I’d really appreciate it!

PHPStan Reports Different Errors Locally & in CI. What Should I Do?

2024-08-20T00:00:00Z

If you find that PHPStan reports different code on your machine and in continuous integration build system, here are the steps to follow to get rid of this problem.

Is it analysing the same code? #

Make sure you’re looking at the results of the same Git commit in CI as you have checked out locally, and that you have committed all the files in your working directory.

Run git rev-parse HEAD or look at git log to get the Git commit hash. CI systems usually print the current Git commit hash somewhere early in the build log.

Run git status to make sure there are no uncommitted changes you’re running the analysis against.

Is it running the same PHP version? #

Make sure to check that you’re running the same PHP version locally and in CI. You can check that with php -v.

Require PHPStan in your Composer project #

Do not run PHPStan installed somewhere globally in your operating system, nor locally, neither in CI. Install PHPStan in composer.json with your project dependencies with this command:

composer require --dev phpstan/phpstan

This way you will make sure everyone and everything is on the same PHPStan version - your machine, your teammates and most importantly, CI.

Make sure your `composer.lock` is committed in the Git repository #

Commit and version your composer.lock file in Git to make sure your dependencies are locked and always the same until you update them.

Run `composer install`, not `composer update` #

Even with composer.lock committed, make sure you run composer install to install dependencies in CI. Running composer update discards the contents of your composer.lock file and updates all dependencies. Which is something we don’t want.

Run PHPStan’s `diagnose` command to compare the environments #

Since release 1.11.8 PHPStan ships with a diagnose command. It prints useful information about its configuration and more. Do not forget to pass the correct configuration file and rule level when running the command.

The output looks like this:

PHP runtime version: 8.3.1
PHP version for analysis: 8.3.99 (from config.platform.php in composer.json)

PHPStan version: 1.11.11
PHPStan running from:
/var/www/project/vendor/phpstan/phpstan

Extension installer:
composer/pcre: 3.2.0
phpstan/phpstan-deprecation-rules: 1.2.0
phpstan/phpstan-doctrine: 1.4.8
phpstan/phpstan-nette: 1.3.5
phpstan/phpstan-phpunit: 1.4.0
phpstan/phpstan-strict-rules: 1.6.0
phpstan/phpstan-symfony: 1.4.6
phpstan/phpstan-webmozart-assert: 1.2.7
shipmonk/phpstan-rules: 3.1.0

Discovered Composer project root:
/var/www/project

Doctrine's objectManagerLoader: In use
Installed Doctrine packages:
doctrine/dbal: 3.8.6
doctrine/orm: 2.19.6
doctrine/common: 3.4.4
doctrine/collections: 2.2.2
doctrine/persistence: 3.3.3

Symfony's consoleApplicationLoader: No

Compare the output between your local machine and CI to find possible differences.

Check the config file path #

Make sure you’re running PHPStan analyse command with the same configuration file. If you’re passing a custom path with -c, make sure it’s the same one as locally.

If you’re letting PHPStan autodiscover phpstan.neon or phpstan.neon.dist file in the current working directory, it outputs this note at the beginning of the analysis:

Note: Using configuration file /var/www/project/phpstan.neon.

Make sure your local machine uses the same file as the CI environment.

Get rid of duplicate symbols #

If you have two or more different class or function definitions with the exact same name, PHPStan does not guarantee which one it’s going to give priority to. Your local machine might discover one definition first and your CI might discover a different definition first, leading to different analysis results.

Rename your classes and functions so that they are always unique to get rid of this problem.

Fix your custom non-deterministic autoloader #

Sometimes the difference in results comes down to the order of files during the analysis. Because the CI environment might have a different number of CPU cores, the files are going to be analysed in different groups and in different order than on your local machine.

If the difference is about what classes are known and unknown to PHPStan, it’s possible you’re using a custom autoloader to discover them.

A following scenario can occur:

You’re referencing a class name in your code with wrong case. For example. Your class name is AdminUser but you have adminUser somewhere in your code when referencing the same class.
On your local machine the first file that’s analysed refers to the class with the correct name - AdminUser. That makes other occurrences even with the wrong case let the class to be successfully found by PHPStan.
In CI the first file that’s analysed refers to the class with an incorrect name - adminUser. Your custom autoloader should still find the class successfully but maybe has a bug. This makes PHPStan report “unknown class” error and it also makes it memoize that this class does not exist.
When the second file that’s analysed in CI refers correctly to AdminUser, it still makes PHPStan report an error about unknown class which is a different behaviour than you’re experiencing locally.

To fix this problem, make your autoloader discover classes even with wrong case.

Open a discussion on PHPStan’s GitHub #

If none of the steps above helped you to get consistent results between running PHPStan locally and in CI, please open a discussion on GitHub, so we can help you figure out this problem.

Do you like PHPStan and use it every day? Consider sponsoring further development of PHPStan on GitHub Sponsors and also subscribe to PHPStan Pro! I’d really appreciate it!

Debugging PHPStan Performance: Identify Slow Files

2024-07-05T00:00:00Z

If you feel like PHPStan could be faster when analysing your project, you can debug what’s actually making it slow. Usually the cause of slow analysis can be pinpointed to a single file or a handful of files in a project that make PHPStan’s analysis crawl to a halt.

Before you start debugging, try enabling Bleeding Edge. It makes analysis in huge codebases run much faster. It comes with a slight backward compatibility break with the advantage of breaking bidirectional memory references, making the job of garbage collector easier.

If that didn’t help, run PHPStan again but add -vvv --debug command line options. PHPStan will run in a single thread instead of in multiple processes at once, and it will print the elapsed time and consumed memory during the analysis of each file:

/var/www/src/Database/Eloquent/Relations/MorphToMany.php
--- consumed 6 MB, total 200 MB, took 0.11 s
/var/www/src/Database/Eloquent/Relations/HasOneThrough.php
--- consumed 0 B, total 200 MB, took 0.06 s
/var/www/src/Database/Eloquent/Relations/MorphPivot.php
--- consumed 0 B, total 200 MB, took 0.06 s
/var/www/src/Database/Eloquent/Relations/Pivot.php
--- consumed 2 MB, total 202 MB, took 0.09 s
/var/www/src/Database/Eloquent/Relations/HasOneOrMany.php
--- consumed 0 B, total 202 MB, took 0.15 s
/var/www/src/Database/Eloquent/Relations/BelongsTo.php
--- consumed 0 B, total 202 MB, took 0.15 s

You can either watch this log go by in realtime with your own eyes and spot files that took too much time or memory. Or you can redirect the output to a file:

vendor/bin/phpstan -vvv --debug > phpstan.log

And parse this file with a simple script by Ruud Kamphuis that sorts the file list and puts the files that took the most time on top:

<?php declare(strict_types=1);

$log = new SplFileObject("phpstan.log");

$logs = [];
$file = null;
while (!$log->eof()) {
    $line = trim($log->fgets());
    if ($line === '') {
        continue;
    }
    if ($file === null) {
        $file = $line;
        continue;
    }
    if (preg_match('/took (?<seconds>[\d.]+) s/', $line, $matches) !== 1) {
        continue;
    }

    $logs[] = [(float) $matches['seconds'], $file];
    $file = null;
}

usort($logs, fn(array $left, array $right) => $right[0] <=> $left[0]);
$logs = array_slice($logs, 0, 20);

echo "Slowest files" . PHP_EOL;
foreach ($logs as $log) {
    echo sprintf("%.2f seconds: %s", $log[0], $log[1]) . PHP_EOL;
}

Save this file into parse.php in the same directory where phpstan.log is and run it:

php parse.php

It will output 20 files that took the most time:

Slowest files
4.46 seconds: /var/www/src/Collections/LazyCollection.php
2.71 seconds: /var/www/src/Support/Str.php
2.56 seconds: /var/www/src/Console/Command.php
2.45 seconds: /var/www/src/Validation/Validator.php
2.44 seconds: /var/www/src/Database/Query/Builder.php
2.41 seconds: /var/www/src/Collections/Collection.php
2.12 seconds: /var/www/src/Database/Eloquent/Builder.php
2.10 seconds: /var/www/src/Foundation/Testing/TestCase.php
2.01 seconds: /var/www/src/Database/Eloquent/Model.php
...

What to do with this list? It’s up to you to decide. Maybe the slowest file is really large and maybe even auto-generated. Analysing it with PHPStan doesn’t probably bring too much value, so you can exclude it from the analysis and make PHPStan immediately faster.

But if the slowest file isn’t that large, you’ve just found a real bottleneck which is an opportunity to make PHPStan faster. Take this file and open a new bug report in PHPStan’s GitHub repository so we can take a look and use it to make PHPStan faster.

Happy debugging!

Do you like PHPStan and use it every day? Consider sponsoring further development of PHPStan on GitHub Sponsors and also subscribe to PHPStan Pro! I’d really appreciate it!

PHPStan Blog

Using PHPStan to Extract Data About Your Codebase

The general approach #

Example: Generating a call map #

The Collector #

The Rule #

The Error Formatter #

The Configuration #

A more complex example: Extracting error identifiers #

Build your own #

Why Array String Keys Are Not Type-Safe in PHP

The casting rules #

The strict_types trap #

array_merge re-indexes your “string” keys #

Strict key lookups fail #

A real-world example #

What PHPStan already does #

PHPStan 2.2.0: non-decimal-int-string #

reportUnsafeArrayStringKeyCasting #

PHPStan fully supports PHP 8.5!

#[NoDiscard] attribute #

The (void) cast #

PHPStan goes a step further #

Interaction with the pipe operator #

Pipe operator #

Clone with #

New functions: array_first() and array_last() #

Deprecated casts #

Deprecated backtick operator #

More PHP 8.5 goodies #

Restricted Usage Extensions - You Don't Always Need a Custom Rule

PHPStan 2.1: Support For PHP 8.4's Property Hooks, and More!

Property hooks #

Asymmetric visibility #

#[Deprecated] attribute #

Upgrading from PHPStan 1.x to 2.0

PHP version requirements #

Upgrading guide for end users #

Noteworthy changes to code analysis #

Removed option checkMissingIterableValueType #

Removed option checkGenericClassInNonGenericObjectType #

Removed checkAlwaysTrue* options #

Removed option excludes_analyse #

Paths in excludePaths and ignoreErrors have to be a valid file path or a fnmatch pattern #

Changes in 1st party PHPStan extensions #

Minor backward compatibility breaks #

Upgrading guide for extension developers #

PHPStan now uses nikic/php-parser v5 #

PHPStan now uses phpstan/phpdoc-parser v2 #

Returning plain strings as errors no longer supported, use RuleErrorBuilder #

Deprecate various instanceof *Type in favour of new methods on Type interface #

Removed deprecated ParametersAcceptorSelector::selectSingle() #

Changed TypeSpecifier::create() and SpecifiedTypes constructor parameters #

ConstantArrayType no longer extends ArrayType #

Changed TypeSpecifier::specifyTypesInCondition() #

Node attributes parent, previous, next are no longer available #

Removed config parameter scopeClass #

Removed PHPStan\Broker\Broker #

List type is enabled for everyone #

Minor backward compatibility breaks #

PHPStan 2.0 Released With Level 10 and Elephpants!

Level 10 #

List type #

Lower memory consumption leads to faster performance #

Validate inline PHPDoc @var tag type #

Checking truthiness of @phpstan-pure with impure points #

Less caching, disk space cleanup #

The future #

PHPStan 1.12: Road to PHPStan 2.0

General availability of precise type inference for regular expressions #

Fix blind spots in PHPDoc tags type checks #

Too wide private property type #

PHP 8.4 runtime support #

PHPStan Reports Different Errors Locally & in CI. What Should I Do?

Is it analysing the same code? #

Is it running the same PHP version? #

Require PHPStan in your Composer project #

Make sure your composer.lock is committed in the Git repository #

Run composer install, not composer update #

Run PHPStan’s diagnose command to compare the environments #

`#[NoDiscard]` attribute #

The `(void)` cast #

New functions: `array_first()` and `array_last()` #

`#[Deprecated]` attribute #

Removed option `checkMissingIterableValueType` #

Removed option `checkGenericClassInNonGenericObjectType` #

Removed `checkAlwaysTrue*` options #

Removed option `excludes_analyse` #

Paths in `excludePaths` and `ignoreErrors` have to be a valid file path or a fnmatch pattern #

Deprecate various `instanceof *Type` in favour of new methods on `Type` interface #

Removed deprecated `ParametersAcceptorSelector::selectSingle()` #

Changed `TypeSpecifier::create()` and `SpecifiedTypes` constructor parameters #

`ConstantArrayType` no longer extends `ArrayType` #

Changed `TypeSpecifier::specifyTypesInCondition()` #

Node attributes `parent`, `previous`, `next` are no longer available #

Removed config parameter `scopeClass` #

Removed `PHPStan\Broker\Broker` #

Validate inline PHPDoc `@var` tag type #

Checking truthiness of `@phpstan-pure` with impure points #

Make sure your `composer.lock` is committed in the Git repository #

Run `composer install`, not `composer update` #

Run PHPStan’s `diagnose` command to compare the environments #