PHPStan 2.3: Leap in Performance, Generics Improvements, Detecting Unused Variables, and More!

October 6, 2026 · 12 min read

It’s been over four months and 16 patch releases since the last minor PHPStan release. Which means it’s about time for the next one! PHPStan 2.3.0 is here.

Performance improvements #

Since the beginning of this year we’ve been hard at work improving PHPStan’s performance and we’ve been very successful at it. Nothing shows it better than the following chart. On my computer (a 5-year-old MacBook Pro with an M1 Pro CPU), in December 2025 it used to take 60 seconds to analyse WordPress source code. And today it only takes 8 seconds:

The first data point is PHPStan 2.1.33 which is the last release before all the contemporary performance work took place. Since then we have been chopping away at work that PHPStan doesn’t have to do at all, doesn’t have to do repeatedly, or that can be done faster. You can see it in the blue line getting steadily lower.

But PHPStan 2.2.6 at the end of July brought something new into the mix: PHPStan Turbo, an optional extension that makes parts of PHPStan faster by reimplementing them in C++. It also enables other optimization techniques: forking child processes instead of spawning them, which normally isn’t possible when running from a PHAR file, and registering an OPcache optimizer pass that strips runtime type checks from PHPStan’s calls to itself. It deserves a separate article which I will publish later this week.

Optional means PHPStan still runs fine without the Turbo extension. The twist is that the majority of PHPStan users have it enabled automatically and thus are already running PHPStan at the highest speed, without having to manually manage the extension on their system. The extension’s .so/.dll files are bundled inside the phpstan/phpstan Composer package, PHPStan selects the correct one for the current PHP runtime, and restarts itself with the extension enabled through php -d command line options.

You can see the effect in the orange line: the initial release made PHPStan 23% faster against the blue baseline. But today Turbo makes PHPStan almost 60% faster.

To summarize: PHPStan today is up to 7.5× faster than PHPStan as of ten months ago!

Result cache improvements #

But that’s not even the whole story. That’s only about the “cold” runs when the result cache does not exist or is too old. PHPStan doesn’t always run analysis on all files in a project. Since March 2020 ^[1] it remembers what errors it reported in which files during previous runs. It checks which files have changed since then, and only reanalyses those, plus files dependent on the changed files.

The day-to-day experience of people running PHPStan isn’t waiting for the full run to finish every time. It depends on how many files were changed since the last run. The following chart shows runs with a warm result cache on Drupal, a much larger project (a full run takes 22 seconds, compared to 8 seconds for WordPress):

Re-running PHPStan without changing anything takes just 1.6 seconds to print the results. When PHPStan decides 10 files need to be reanalysed, it takes 2.8 seconds. When 10% of the project is reanalysed, it takes 6.2 seconds.

The recent result cache improvements are about making sure the whole result cache is invalidated and thrown away only when PHPStan is updated, or when the project’s PHPStan configuration changes. Previously, the project was fully reanalysed when any Composer dependency was updated, or when the Symfony DI container changed in any way. We’ve started tracking the dependencies between analysed files and installed packages so only the precise minimum is reanalysed.

We’re also introducing new extension interfaces and APIs that custom extensions can take advantage of to describe which files need to be invalidated and when, instead of throwing the entire result cache away when any minor detail changes.

The result cache now also behaves properly in monorepo setups that take advantage of "type": "path" repositories in composer.json, or scanDirectories & scanFiles of often-changed files.

Result cache is made to be saved and restored in CI for vastly faster pipelines. Make sure to configure that!

Generics: no more scalar generalization,
multi-pass inference for new Foo() from usages #

PHPStan has had generics support for almost seven years. We had to make a bunch of tough choices during development, and a few times we had to guess “how this should work” purely on gut feeling. Spoiler alert: some of those choices were wrong!

For instance, take the following function that returns the same type it accepts in its parameter:

/**
 * @template T
 * @param T $a
 * @return T
 */
function doFoo($a)
{
    // ...
}

What return type should be inferred when calling doFoo(1)? Is it int? Is it 1? There’s no correct answer; each comes with different trade-offs.

We opted for generalizing passed scalars so 1 becomes int. In hindsight, it was the wrong choice, and users reported many, many issues over the years because they wanted to preserve the precise scalar type.

But we couldn’t fix it without breaking one important use case.

Here’s another question for you: What’s the type of $c = new Collection([1, 2, 3])? If it’s Collection<1|2|3>, you can’t call $c->add(4) because it wouldn’t be accepted. If it’s Collection<int>, you can’t pass it to a parameter expecting Collection<positive-int>, even though that should be valid.

If we take an empty collection new Collection([]), the resolved type of @template T is the never type (the empty bottom type). Strictly speaking, you shouldn’t be able to add anything to it, because it’s supposed to be empty! Correct, but not really useful in the real world.

Yeah, tough choices.

Fortunately, Arnaud Le Blanc, who helped me tremendously with over 50 pull requests for the initial generics implementation back in 2019, came to the rescue again on March 8th 2022. He described a solution to this problem in an issue titled “Bidirectional type narrowing” so that’s what we’ve been calling the idea ever since.

It took me over four years to gather up courage and funding to implement it correctly and efficiently.

The solution is to analyse the code around new Collection(...) multiple times, observe how it’s used, where it’s passed to, and clamp the final inferred @template T type based on that information.

You can play with this interactive widget to understand what PHPStan does with different code snippets:

/** @param Collection<int> $ints */
function takeInts(Collection $ints): void {}

/** @param Collection<string> $strings */
function takeStrings(Collection $strings): void {}

function example(): void
{
	$ints = new Collection([]);
	takeInts($ints);
	takeStrings($ints);
}

/** @param Collection<positive-int> $ids */
function saveIds(Collection $ids): void {}

function example(): void
{
	$ids = new Collection([1, 2, 3]);
	$ids->add(4);
	$ids->add(-1);
	saveIds($ids);
}

/** @param Collection<int> $ints */
function takeInts(Collection $ints): void {}

function example(): void
{
	$items = new Collection();
	$items->add(1);
	$items->add('one');
	takeInts($items);
}

/**
 * @template T
 * @param Box<T> $a
 * @param Box<T> $b
 */
function swap(Box $a, Box $b): void {}

function example(): void
{
	$a = new Box(1);
	$b = new Box('one');
	swap($a, $b);
}

The first naive prototype made PHPStan around 30% slower. Going back to the drawing board made me realize PHPStan doesn’t have to reanalyse everything, only the lines directly impacted by the generic objects with unresolved template types. The performance impact of this feature is between 1 and 3%, depending on how heavily the analysed code uses generics, which is easily offset by the performance improvements made in the same release.

Thanks to this work, PHPStan no longer needs to generalize scalar types in the context of generics. The implementation closed 17 related issues, plus countless duplicates reported over the years.

Make sure to enable bleeding edge to take advantage of these improvements.

Bidirectional type narrowing and related work have been commissioned and made possible by the Sovereign Tech Fund.

Detecting unused variables #

Unused variables are a class of errors that has escaped PHPStan’s attention. Until now. They can be pretty severe: a value that has been assigned but not used later means someone made a typo or forgot to send the value somewhere. Like computing a TTL but never passing it to the Cache::save() method.

PHPStan distinguishes five scenarios of unused variables:

• Variable is assigned but never read: variable.unused.
• The assigned value is never read before the end of the function body (the variable may still be read earlier, above the assignment): assign.unused.
• The assigned value is overwritten by another assignment before being read: assign.overwritten.
• Variable is assigned the value it already has: assign.redundant.
• Variable is assigned and seemingly used, but the value doesn’t end up anywhere: assign.unusedFlow. Inspired by Psalm’s data-flow graph.

This list isn’t exhaustive. Besides plain assignments like $foo = ..., PHPStan also checks array keys that are never read or immediately overwritten, results of ++ and --, foreach keys and values, catch variables, closure use variables, and parameters of functions and private methods.

Explore all the different errors PHPStan can now report in this interactive widget:

function sendWelcomeEmail(Mailer $mailer, User $user): void
{
	$subject = 'Welcome to Acme!';
	$mailer->send($user->getEmail(), 'Welcome!', 'Glad to have you.');
}

function cacheReport(Cache $cache, Report $report): void
{
	$ttl = 3600;
	$cache->save($report->getId(), $report, $ttl);

	$ttl = 600;
	$cache->save($report->getId() . '-summary', $report->getSummary());
}

function formatPrice(float $amount, string $currency): string
{
	$label = number_format($amount, 2);
	$label = sprintf('%.2f %s', $amount, $currency);

	return $label;
}

function importRows(Importer $importer, array $rows): void
{
	$imported = 0;
	foreach ($rows as $row) {
		$importer->import($row);
		$imported = $imported + 1;
	}
}

function activate(User $user): void
{
	$status = 'active';
	if ($user->isVerified()) {
		$status = 'active';
	}

	$user->setStatus($status);
}

function orderSummary(Order $order): string
{
	$summary = [
		'id' => $order->getId(),
		'total' => $order->getTotal(),
	];

	return sprintf('Order #%d', $summary['id']);
}

function httpOptions(bool $slowNetwork): array
{
	$options = [
		'timeout' => 5,
		'retries' => 3,
	];
	$options['timeout'] = $slowNetwork ? 30 : 10;

	return $options;
}

function countWords(array $words): int
{
	$stats = ['words' => 0, 'letters' => 0];
	foreach ($words as $word) {
		$stats['words'] = $stats['words'] + 1;
		$stats['letters'] = $stats['letters'] + strlen($word);
	}

	return $stats['words'];
}

function notifyAll(Mailer $mailer, array $users, string $admin): void
{
	foreach ($users as $user) {
		$mailer->send($admin, 'New signup', 'Someone joined.');
	}
}

function printLines(array $lines): void
{
	foreach ($lines as $line) {
		$line = 'Line';
		echo $line, PHP_EOL;
	}
}

function retryFailed(Queue $queue, array $failedJobs): void
{
	foreach ($failedJobs as $job => $attempts) {
		$queue->push($job);
		while ($queue->isFull()) {
			$queue->flush();
			$attempts = $attempts + 1;
		}
	}
}

function totalPrice(array $prices): float
{
	$total = 0.0;
	foreach ($prices as $sku => $price) {
		$total += $price;
	}

	return $total;
}

function labels(array $options): array
{
	$labels = [];
	foreach ($options as $key => $label) {
		$key = strtolower($label);
		$labels[] = $key;
	}

	return $labels;
}

function enqueue(Queue $queue, array $jobs): void
{
	foreach ($jobs as $position => $job) {
		$queue->push($job);
		while ($queue->isFull()) {
			$queue->flush();
			$position = $position + 1;
		}
	}
}

function nextInvoiceNumber(int $last, Logger $logger): int
{
	$next = $last;
	++$next;
	$logger->info(sprintf('Issuing invoice %d', $next));
	++$next;

	return $last + 1;
}

function pageNumber(int $page, bool $reset): int
{
	++$page;
	$page = $reset ? 1 : $page;
	++$page;
	$page = 1;

	return $page;
}

function waitForJob(callable $isDone): void
{
	$attempts = 0;
	while (!$isDone()) {
		++$attempts;
		sleep(1);
	}
}

function placeholders(array $values): string
{
	$i = 0;
	$sql = sprintf('(%s)', implode(', ', array_fill(0, count($values), '?')));
	$i++;

	return $sql;
}

function rowNumber(array $rows): int
{
	$line = count($rows);
	$line++;
	$line = 1;

	return $line;
}

function sendAll(Mailer $mailer, array $users): void
{
	$sent = 0;
	foreach ($users as $user) {
		$mailer->send($user->getEmail(), 'News', 'Hello!');
		$sent++;
	}
}

function remainingSlots(int $capacity, Logger $logger): int
{
	$left = $capacity;
	--$left;
	$logger->info(sprintf('%d slots left', $left));
	--$left;

	return $capacity - 1;
}

function countdown(int $from): int
{
	--$from;
	$from = 10;

	return $from;
}

function drainQueue(SplQueue $queue): void
{
	$budget = 100;
	while (!$queue->isEmpty()) {
		$queue->dequeue();
		--$budget;
	}
}

function lastIndex(array $items): int
{
	$index = count($items);
	$index--;
	$index--;

	return count($items) - 1;
}

function retriesLeft(int $retries): int
{
	$retries--;
	$retries = 3;

	return $retries;
}

function consume(SplStack $stack): void
{
	$remaining = $stack->count();
	while (!$stack->isEmpty()) {
		$stack->pop();
		$remaining--;
	}
}

function fetchStatus(Http $http, Logger $logger, int $retries): string
{
	try {
		return $http->get('https://example.com/status');
	} catch (TransientException $error) {
		for ($i = 0; $i < $retries; $i++) {
			$logger->warning('Status check failed');
			$error = $i === $retries - 1 ? null : $error;
		}

		return 'unknown';
	}
}

function greeter(Logger $logger, string $greeting): Closure
{
	return function (string $name) use ($logger, $greeting): string {
		return $greeting . ', ' . $name;
	};
}

function eachWithIndex(callable $callback, int $index): Closure
{
	return function (array $items) use ($callback, $index): void {
		foreach ($items as $item) {
			$callback($item);
			$index = $index + 1;
		}
	};
}

function welcomeMessage(User $user, string $locale): string
{
	return sprintf('Welcome, %s!', $user->getName());
}

function retryDelay(int $attempt, int $delay): int
{
	for ($i = 0; $i < $attempt; $i++) {
		$delay = $delay * 2;
	}

	return $attempt * 100;
}

final class InvoiceMailer
{
	public function __construct(private Mailer $mailer) {}

	public function send(Order $order, string $email): void
	{
		$this->mailer->send($email, 'Invoice', $this->body($order, $email));
	}

	private function body(Order $order, string $email): string
	{
		return sprintf('Invoice for order #%d', $order->getId());
	}
}

final class CsvExport
{
	public function run(array $rows): int
	{
		return $this->write($rows, 0);
	}

	private function write(array $rows, int $bytes): int
	{
		foreach ($rows as $row) {
			$bytes = $bytes + strlen($row);
		}

		return count($rows);
	}
}

Make sure to enable bleeding edge to take advantage of these new rules.

Inferring closure types from usages #

This builds on the same engine that powers bidirectional type narrowing for generics. It lets PHPStan observe how a closure stored in a variable is used after it’s assigned, and feed that information back into the final analysis pass.

Closures never need to be annotated with @param and @return PHPDocs. Even without any typehints, PHPStan is able to precisely infer the involved types, including variables the closure takes by reference:

/** @return list<int> */
function findOrderIds(): array { return [1, 2, 3]; }

function printOrders(): void
{
	$format = function ($id) {
		return 'Order #' . $id;
	};
	$title = $format(42);
	$labels = array_map($format, findOrderIds());
	$fallback = $format('n/a');
}

/** @param callable(Order): void $listener */
function onOrderPlaced(callable $listener): void {}

/** @param callable(Refund): void $listener */
function onRefundIssued(callable $listener): void {}

function registerListeners(Mailer $mailer): void
{
	$notify = function ($event) use ($mailer): void {
		$mailer->send(
			$event->getEmail(),
			'Thank you',
			'We have received it.',
		);
	};
	onOrderPlaced($notify);
	onRefundIssued($notify);
}

function process(): void
{
	$messages = [];
	$log = function (string $message) use (&$messages): void {
		$messages[] = $message;
	};
	$log('Started');
	$log('Processing');
	$messages = [];
	$log('Finished');
	echo implode("\n", $messages);
}

Make sure to enable bleeding edge to take advantage of these improvements.

Inferring static variable types from assignments #

By now you’ve probably noticed the pattern 😅 Besides generic objects and closures, PHPStan can inspect assignments from the whole function body to infer types of static variables. Previously, they had to be annotated with @var, otherwise you’d end up with an implicit mixed type.

Switch the assignments off to see what happens:

function getCache(): Cache
{
	static $cache = null;
	if ($cache === null) {
		if (extension_loaded('apcu')) {
			$cache = new ApcuCache();
		} else {
			$cache = new FileCache('/tmp/cache');
		}
	}

	return $cache;
}

Again, you can enjoy this if you enable bleeding edge in your PHPStan config file.

Under the hood: single-pass inside-out engine rewrite #

This is the preliminary work that enabled all of these improvements. From the very beginning until 2.2.x, PHPStan had three “god” classes that each traversed the AST on their own:

• NodeScopeResolver::processNodes(): updates Scope based on assignments, entering classes, functions etc.
• MutatingScope::resolveType(Expr $expr): Type: resolves type of an expression by checking types of child expressions it consists of
• TypeSpecifier: narrows types of expressions, for example decides what happens to $foo after $foo instanceof Bar for both truthy and falsey contexts

The problem with this approach was that it could either be slow or imprecise. If an expression also contains an assignment or modifies Scope some other way, the type resolution in MutatingScope will not know about it, unless it processes the node again. PHPStan used to process some nodes repeatedly to get rid of a certain class of bugs. So you could say it was both slow and imprecise 😅

Take this code as an example:

$a = [
	$b = 1,
	$b + 1,
	$c = $b,
	$c + 2,
	$c++,
	$c,
];
\PHPStan\dumpType($a);

In PHPStan 2.2.x and before, the type of the array was inferred as array{1, (float|int), *ERROR*, (float|int), *ERROR*, *ERROR*}. PHPStan had no clue about the correct type of the array, because later array items referenced variables assigned or changed in the earlier ones.

In PHPStan 2.3.0 and onward, the type of the array from the code snippet above is correctly inferred as array{1, 2, 1, 3, 1, 2}.

The rewrite changes where and when expression types are inferred. Everything now happens when a node is processed in NodeScopeResolver. Once it’s finished, the returned result object contains everything: the updated Scope, the expression type, and how the expression narrows other nested expressions. We took extra care not to break any extension APIs, so $scope->getType($expr) continues to work as before.

Before the rewrite, some code, like deeply nested && / || expressions, could lead to real slowdowns because they’d be processed many times. It wouldn’t have been possible to introduce the awesome new features described in this article with the old internals because of the multiplicative nature of multiple passes needed for these features. You won’t notice going from 1 to 2 if 1 takes very little time, but you’d certainly notice if something was analysed 20 times instead of 10 (which was already pretty slow).

Update extensions today too! #

A bunch of official PHPStan extensions have new releases today related to changes and enhancements in PHPStan 2.3.0. So don’t forget to update them alongside PHPStan.

• phpstan-strict-rules 2.1.0 makes foreach.valueOverwrite less annoying and no longer reports it in harmless scenarios. More info »
• phpstan-symfony 2.1.0 no longer invalidates the entire result cache when the DI container changes. It uses new extensions and APIs to reanalyse only files referencing the changed parameters and services while keeping the rest of the result cache intact.
• phpstan-phpunit 2.1.0 makes DataProviderDataRule hook onto multiple node types at once using the new MultipleNodeTypesRule interface, mostly for performance reasons.

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!