PHPStan Blog

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

2026-10-06T00:00:00Z

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:

Version	Released	Turbo off (s)	Turbo on (s)	Note
2.1.33	December 5th 2025	60.51		Last release before this year’s performance improvements
2.1.34	January 19th 2026	46.51		Caching reflection objects and PHPDocs
2.1.38	January 30th 2026	44.55		Minor performance improvements
2.1.49	April 16th 2026	34.49		More performance improvements
2.2.6	July 26th 2026	32.02	24.68	First release with Turbo
2.2.10	August 30th 2026	29.94	22.20	Forking workers instead of spawning
2.2.13	September 3rd 2026	23.06	14.12	Always running with OPcache, stripping runtime checks
2.3.0	October 1st 2026	19.47	7.93	A lot more classes shadowed by Turbo

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):

Files	Detail	Share	Time (s)	Note
0	no change	0%	1.58	Nothing changed since the last run
10	0.1%	0.1%	2.84
1,124	10%	10.0%	6.21
2,771	25%	24.8%	9.89
5,574	50%	49.8%	16.10
7,204	64%	64.4%	19.03
8,956	80%	80.0%	21.14
11,194	cache cleared	100%	22.08	Result cache cleared

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:

Passed to a function

/** @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);
}

PHPStan infers that $ints is Collection<int> on line 9.

Line 11: Parameter #1 $strings of function takeStrings expects Collection<string>, Collection<int> given.

Precise scalars

/** @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);
}

PHPStan infers that $ids is Collection<int<1, max>> on line 6.

Line 8: Parameter #1 $item of method Collection<int<1, max>>::add() expects int<1, max>, -1 given.

Method calls

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

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

PHPStan infers that $items is Collection<int> on line 6.

Line 8: Parameter #1 $item of method Collection<int>::add() expects int, string given.

Inferred together

/**
 * @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);
}

PHPStan infers that $a is Box<1|'one'> on line 10, $b is Box<1|'one'> on line 11.

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:

variable.unused

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

Line 3: Variable $subject is never read. variable.unused

assign.unused

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

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

Line 6: Value assigned to variable $ttl is never read. assign.unused

assign.overwritten

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

	return $label;
}

Line 3: Value assigned to variable $label is never read before being overwritten. assign.overwritten

assign.unusedFlow

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

Line 3: Value assigned to variable $imported only flows into values that are never used. assign.unusedFlow
Line 6: Value assigned to variable $imported only flows into values that are never used. assign.unusedFlow

assign.redundant

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

	$user->setStatus($status);
}

Line 5: Variable $status is assigned value 'active' but it already has that value. assign.redundant

array.unusedOffset

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

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

Line 5: Offset 'total' of array assigned to variable $summary is never read. array.unusedOffset

array.offsetOverwritten

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

	return $options;
}

Line 4: Offset 'timeout' of array assigned to variable $options is never read before being overwritten. array.offsetOverwritten

array.unusedOffsetFlow

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'];
}

Line 3: Offset 'letters' of array assigned to variable $stats only flows into values that are never used. array.unusedOffsetFlow
Line 6: Value assigned to $stats['letters'] only flows into values that are never used. assign.unusedFlow

foreach.unusedValue

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

Line 3: Foreach value variable $user is never read. foreach.unusedValue

foreach.valueOverwritten

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

Line 3: Foreach value variable $line is never read before being overwritten. foreach.valueOverwritten

foreach.unusedValueFlow

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

Line 3: Foreach value variable $attempts only flows into values that are never used. foreach.unusedValueFlow
Line 7: Value assigned to variable $attempts only flows into values that are never used. assign.unusedFlow

foreach.unusedKey

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

	return $total;
}

Line 4: Foreach key variable $sku is never read. foreach.unusedKey

foreach.keyOverwritten

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

	return $labels;
}

Line 4: Foreach key variable $key is never read before being overwritten. foreach.keyOverwritten

foreach.unusedKeyFlow

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

Line 3: Foreach key variable $position only flows into values that are never used. foreach.unusedKeyFlow
Line 7: Value assigned to variable $position only flows into values that are never used. assign.unusedFlow

preInc.unused

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

	return $last + 1;
}

Line 6: Value of variable $next after ++ is never read. preInc.unused

preInc.overwritten

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

	return $page;
}

Line 5: Value of variable $page after ++ is never read before being overwritten. preInc.overwritten

preInc.unusedFlow

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

Line 3: Value assigned to variable $attempts only flows into values that are never used. assign.unusedFlow
Line 5: Value of variable $attempts after ++ only flows into values that are never used. preInc.unusedFlow

postInc.unused

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

	return $sql;
}

Line 5: Value of variable $i after ++ is never read. postInc.unused

postInc.overwritten

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

	return $line;
}

Line 4: Value of variable $line after ++ is never read before being overwritten. postInc.overwritten

postInc.unusedFlow

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

Line 3: Value assigned to variable $sent only flows into values that are never used. assign.unusedFlow
Line 6: Value of variable $sent after ++ only flows into values that are never used. postInc.unusedFlow

preDec.unused

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

	return $capacity - 1;
}

Line 6: Value of variable $left after – is never read. preDec.unused

preDec.overwritten

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

	return $from;
}

Line 3: Value of variable $from after – is never read before being overwritten. preDec.overwritten

preDec.unusedFlow

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

Line 3: Value assigned to variable $budget only flows into values that are never used. assign.unusedFlow
Line 6: Value of variable $budget after – only flows into values that are never used. preDec.unusedFlow

postDec.unused

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

	return count($items) - 1;
}

Line 5: Value of variable $index after – is never read. postDec.unused

postDec.overwritten

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

	return $retries;
}

Line 3: Value of variable $retries after – is never read before being overwritten. postDec.overwritten

postDec.unusedFlow

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

Line 3: Value assigned to variable $remaining only flows into values that are never used. assign.unusedFlow
Line 6: Value of variable $remaining after – only flows into values that are never used. postDec.unusedFlow

catch.unusedVariableFlow

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';
	}
}

Line 5: Catch variable $error only flows into values that are never used. catch.unusedVariableFlow
Line 8: Value assigned to variable $error only flows into values that are never used. assign.unusedFlow

closure.unusedUse

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

Line 3: Anonymous function has an unused use $logger. closure.unusedUse

closure.unusedUseFlow

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

Line 3: Anonymous function has a use $index that only flows into values that are never used. closure.unusedUseFlow
Line 6: Value assigned to variable $index only flows into values that are never used. assign.unusedFlow

function.unusedParameter

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

Line 1: Function welcomeMessage() has an unused parameter $locale. function.unusedParameter

function.unusedParameterFlow

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

	return $attempt * 100;
}

Line 1: Function retryDelay() has a parameter $delay that only flows into values that are never used. function.unusedParameterFlow
Line 4: Value assigned to variable $delay only flows into values that are never used. assign.unusedFlow

method.unusedParameter

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());
	}
}

Line 10: Method InvoiceMailer::body() has an unused parameter $email. method.unusedParameter

method.unusedParameterFlow

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);
	}
}

Line 8: Method CsvExport::write() has a parameter $bytes that only flows into values that are never used. method.unusedParameterFlow
Line 11: Value assigned to variable $bytes only flows into values that are never used. assign.unusedFlow

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:

From usages

/** @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');
}

PHPStan infers that $id is 'n/a'|int on line 7, $title is 'Order #42' on line 9, $labels is list<non-falsy-string> on line 10, $fallback is 'Order #n/a' on line 11.

Passed as a callback

/** @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);
}

PHPStan infers that $event is Order|Refund on line 10.

Line 11: Call to an undefined method Order|Refund::getEmail().

By-reference variables

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

PHPStan infers that $messages is array{}|array{'Started'} on line 5, $messages is array{'Finished'} on line 11.

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:

Static variable

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

	return $cache;
}

PHPStan infers that $cache is ApcuCache|FileCache|null on line 3.

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!

So for about 18 years. ↩︎

PHPStan 2.2: Unsealed Array Shapes, Safer Array Keys, and More!

2026-05-28T00:00:00Z

It’s been almost a year and a half since we last bumped the minor version. Although we released many improvements in the 2.1.x series, grouped together in over 55 releases, we also cooked up some bigger changes people have been asking for for a long time.

Two of them have stood out ever since array shapes were first introduced seven years ago:

The ability to intersect an array shape with a general array: array<string, X>&array{a: Y} - meaning array{a: Y} plus the possibility of more string keys whose values are X.
The ability to intersect two distinct array shapes like array{a: X}&array{b: Y} to produce one combined shape array{a: X, b: Y}. The motivating use cases are composable type aliases, and modelling a function that returns its input array with an extra key added.

The problem with both of those is that they don’t make sense from the type system’s point of view. The type system is a mathematical system where hacks and workarounds lead to leaks and collapse quickly. Elements of an intersection type get normalized to the type that’s the smaller one out of a pair (the subtype). So mixed&int results in int and int&int<0, max> results in int<0, max>. With this definition array<string, X>&array{a: Y} gets normalized to array{a: Y}. And array<int, X>&array{a: Y} would be normalized to never type (the bottom type) because there’s no overlap (no intersection) between these two types.

The intersection of array{a: X} and array{b: Y} is equivalent to having this code:

// $x is X, $y is Y
$a = ['a' => $x];
$b = ['b' => $y];
if ($a === $b) {
    // here we'd have the intersection
    // but in reality these types are distinct and do not overlap
    // the condition is always false!
}

These reasons are why these operations didn’t work as expected. But I acknowledge the real need for them. In order to make them work, we’d have to introduce a new concept and new syntax.

Introducing unsealed array shapes #

The intersection array{a: X}&array{b: Y} would make sense if the array shapes allowed for extra keys. So this is the syntax:

array{foo: int, ...<string, int>} - constrain the extra keys’ key and value types
array{foo: int, ...<Bar>} - a single type inside ...<> is the value type (key is implied to be array-key which is a benevolent union of int|string)
list{X, Y, ...<Z>} - lists only allow a single value type after first two keys (the key is always int)
array{foo: int, ...} - bare ... means any extra keys (shorthand for ...<array-key, mixed>)

I consider this very intuitive because the part after ... works the same way in general arrays like array<string, int>. ^[1]

The great news is that this solves both problems. We can now describe array shapes with extra keys. We can also produce a combined shape by intersecting unsealed array shapes. When one or both sides allow for extra keys, the intersection suddenly makes sense!

array{a: int, ...}&array{b: string, ...} leads to array{a: int, b: string, ...}
array{a: int, b: string, ...}&array{a: int<0, max>, ...} leads to array{a: int<0, max>, b: string, ...}
array{a: int, ...}&array{a: string, ...} still leads to never - same known key with incompatible value types.

Sealed array shapes become truly sealed #

PHPStan’s modelling of array shapes has been flawed for the past seven years. They allow extra keys but they are inconsistent about it.

Let’s take a function:

/**
 * @param array{a: int} $a
 */
function doFoo(array $a): void { ... }

PHPStan doesn’t check whether the argument has extra keys, so calls with array{a: int, b: string} are accepted as well.

PHPStan even accepts a general array as long as we check that key a is present:

/**
 * @param array<int> $b
 */
function doBar(array $b): void {
    if (isset($b['a'])) {
        doFoo($b); // No errors!
    }
}

And that’s not okay, because the array shape contradicts itself the moment we start asking it questions:

/**
 * @param array{a: int} $a
 */
function doFoo(array $a): void {
    \PHPStan\dumpType(count($a)); // reports 1, but that's a lie
    echo $a['b'] ?? 'foo'; // PHPStan reports the offset doesn't exist - also a lie, b may well exist at runtime
    foreach ($a as $k => $v) {
        \PHPStan\dumpType($k); // Reports 'a', but the user might have passed more keys
        \PHPStan\dumpType($v); // Reports int, but should be mixed
    }
}

Array shapes look great on the surface - they let legacy applications describe the arrays flowing through their code. But under the hood they behave inconsistently and unsafely, leading to undetected runtime errors.

These mistakes are remedied in PHPStan 2.2 when you turn on bleeding edge. Array shapes like array{a: int} become truly sealed and report everything consistently. You can no longer pass general arrays to them and you can’t pass extra keys either.

For now it’s opt-in, and it will become the only behaviour in the next major PHPStan version. It’s a big disruption - real-world projects will typically see hundreds of new errors when they turn this on. These errors are valuable and important to fix, but we decided to gate it behind bleeding edge because of PHPStan’s backward compatibility promise.

When a sealed array shape rejects another array, the rejection comes with a reason, shown next to the error message (with a 💡 emoji prefix in the default table formatter).

These tips also appear on the online playground and in PHPStan Pro. Some examples:

Sealed array shape can only accept a constant array. Extra keys are not allowed.
Sealed array shape does not accept array with extra key ‘year’.
Sealed array shape does not accept unsealed array shape.

These messages will help users understand why their types are rejected.

Unsealed array shapes and related work have been commissioned and made possible by the Sovereign Tech Fund.

Safer array keys #

Changes to array shapes are not the only thing added to PHPStan 2.2.0, and not even the only thing related to arrays. We’re also trying to tackle a long-standing PHP quirk around string array keys. This has been extensively described in the recent article Why Array String Keys Are Not Type-Safe in PHP.

The TL;DR: you can’t rely on the key type in array<string, X>. Even if you only use strings as keys there, you might end up with an array that’s array<int|string, X>. Specifically, strings that contain decimal integers (like '123') get cast to integers.

PHPStan 2.2.0 offers several countermeasures to this problem. It introduces the non-decimal-int-string type which describes strings that don’t get cast to int when used as array keys. You can’t use an arbitrary string as a non-decimal-int-string, because it might be cast to int at runtime.

/** @param array<non-decimal-int-string, mixed> $data */
function processData(array $data): void { ... }

function doFoo(string $s)
{
    $a = [];
    $a[$s] = 1; // might produce an int key

    // Error:
    // Parameter #1 $data of function processData
    // expects array<non-decimal-int-string, mixed>, non-empty-array<string, 1> given.
    processData($a);
}

Use non-decimal-int-string for the array keys where type safety matters most, and PHPStan will enforce it. For completeness, we’re also introducing decimal-int-string which also no doubt has its uses.

Additionally, PHPStan 2.2.0 introduces a new configuration parameter reportUnsafeArrayStringKeyCasting with three possible values that change the interpretation of PHPDoc types:

null - Current behaviour. No additional checks. String keys that look like decimal integers are silently cast to int at runtime without any PHPStan errors.
'detect' - A typehinted array<string, mixed> accepts other array<string, mixed>, but when you get a key out of it (e.g. via foreach or array_keys), the key type will be int|non-decimal-int-string instead of string. This reveals potential issues without requiring you to change all your array type annotations.
'prevent' - A 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.

For now the default is null. Time and prolonged exposure to these options will tell whether we should change the default to one of the stricter behaviours. From my experience, both of them are brutal in their own ways and cause hundreds of new errors in real-world projects.

Checking constants passed as function arguments #

Try to spot an error in this code:

function (string $s): void {
    $json = json_decode($s, true, JSON_THROW_ON_ERROR);
};

Seems correct, doesn’t it? Except JSON_THROW_ON_ERROR is being passed as $depth, not $flags. So this code decodes the JSON with depth set to 4194304, but it still won’t throw on a syntax error.

In order to recognize these errors, we had to extract data from various places (mostly PHP documentation) about which constants are valid for which function parameters. The result is yet another multi-thousand-line map. The rule’s logic is simple: when it sees a call to a function or method in this map and one of its arguments is a built-in PHP constant, the constant is checked against the map entry.

Some examples of what is and isn’t reported:

// Error:
// Constant JSON_THROW_ON_ERROR is not allowed for parameter #3 $depth of function json_decode.
json_decode($s, true, JSON_THROW_ON_ERROR);

// Not an error: correct usage
json_decode($s, true, flags: JSON_THROW_ON_ERROR);

// Error:
// Constant SORT_NATURAL is not allowed for parameter $flags of function json_decode.
json_decode($s, true, flags: SORT_NATURAL);

// No errors: our constants, not built-in
json_decode($s, true, depth: self::DEPTH, flags: self::THROW);

The map also knows where bitmasks are allowed, and which combinations of flags are invalid within them:

// Error:
// Combining constants with | is not allowed for parameter #2 $component of function parse_url.
parse_url($s, PHP_URL_SCHEME | PHP_URL_HOST);

// No error - expected usage
flock($f, LOCK_SH | LOCK_NB);

// Error:
// Constants LOCK_SH, LOCK_EX cannot be combined for parameter #2 $operation of function flock.
flock($f, LOCK_SH | LOCK_EX);

This has historically been a blind spot in PHPStan. Not anymore. These easy-to-get-wrong code snippets are now reported in PHPStan 2.2.0!

Detecting named arguments with renamed parameters in subtypes #

Let’s take the following code:

interface Foo
{
	public function doFoo(int $order): void;
}

class FooImpl implements Foo
{
	public function doFoo(int $number): void { ... }
}

Nothing wrong with this code, right? And there isn’t, as long as you call it without named arguments:

function (Foo $foo) {
	$foo->doFoo(1); // OK
};

But if you use named arguments, you suddenly have a bug:

$cb = function (Foo $foo) {
	$foo->doFoo(order: 1); // correct parameter name for Foo::doFoo() method
};

// PHP: Fatal error: Uncaught Error: Unknown named parameter $order
$cb(new FooImpl());

For the longest time ^[2] I’ve resisted reporting the renamed parameter in an overridden method as a bug, I didn’t want to bother developers with that. After all, it isn’t a bug if you never use named arguments, they’re still a pretty rare occurrence in real-world code.

But if PHPStan 2.2.0 detects that you’re calling a method on an interface or non-final class with named arguments, and the parameter is renamed in an overriding method in a subclass, it’s certain you have a bug. You either need to drop the named argument (and pass it positionally), or sync the parameter names. You’ll see this error message:

Call to Foo::doFoo() uses named argument for parameter $order, but FooImpl renames it to $number.

Reducing false positives about constant conditions in traits #

PHPStan analyses traits in the context of each class that uses them. An unused trait is not analysed at all; a trait used in three classes is analysed three times. This approach benefits codebases that use traits heavily. Your code in traits can reference properties and methods declared only on the using classes, and as long as it lines up, PHPStan doesn’t report any false positives.

But there’s another downside to this approach. PHPStan still complained about things that only make sense to flag in code that isn’t reused.

In normal code it might make sense to ask about $this->getFoo() !== null if the return type is string|null. Totally valid.

But it’s different in a trait, when getFoo returns a non-nullable type in one of the using classes:

trait Foo
{
	public function getName(): string
	{
		$str = 'Hello';
		if ($this->getFoo() !== null) {
			$str .= ' World';
		}

		return $str;
	}
}

class Bar
{
	use Foo;

	public function getFoo(): string
	{
		return "Bar";
	}
}

class Zar
{
	use Foo;

	public function getFoo(): ?string
	{
		return rand(0, 1) ? 'foo' : null;
	}
}

Past PHPStan versions analysed each trait usage in isolation with no regard to other contexts. It’d report:

PHPStan: Strict comparison using !== between string and null will always evaluate to true. (in the context of class Bar)

In PHPStan 2.2.0 we updated a group of rules reporting “constant conditions” to defer these errors until the trait has been analysed in all contexts. If the reports differ across contexts, no error is reported.

If the condition is always true or always false in all contexts, it’s still reported. So code like this is still reported even when it lives in a trait:

$o = new stdClass();

// PHPStan: If condition is always true.
if ($o) {

}

Allowing custom rules to emit collector data #

The community has taken great advantage of collectors, implementing awesome extensions like dead-code-detector. Collectors work exactly like custom rules, but instead of reporting errors directly, they collect data for later evaluation. At the end of the analysis, developers can look at all the collected data from the entire codebase at once, and decide what errors should be reported.

In past PHPStan versions, you’d have to decide whether you’re writing a custom rule or a collector. What PHPStan 2.2.0 brings to the table is that a custom rule can easily become a collector too. It can report some errors directly, and defer others to later evaluation. All thanks to the CollectedDataEmitter interface, implemented by Scope.

Instead of the usual processNode signature:

public function processNode(Node $node, Scope $scope): array

You can also typehint with the new interface:

/**
 * @param Scope&CollectedDataEmitter $scope
 */
public function processNode(Node $node, Scope $scope): array

And emit collected data for an existing collector class:

$scope->emitCollectedData(MyCollector::class, ['some', 'data']);

This is what made the previous two features in this article possible in the first place!

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!

When writing this article, I went down the memory lane and tried to find the origin of this syntax. The whole concept was initially discussed on Psalm’s GitHub but my idea was more TypeScript-like: array{foo: Foo, [k: string]: Bar}. Then I found this issue from Vincent Langlet (now a major PHPStan contributor!) asking to officially support the syntax in PHPDocs (Matt Brown originally only used it in Psalm’s error messages). So I guess that’s where it started. ↩︎
Ever since PHP 8.0 was released. ↩︎

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.

And if you have a plain string that you want to narrow down to one of these types, PHPStan understands an int round-trip check:

if ((string) (int) $x === $x) {
    // $x is decimal-int-string
} else {
    // $x is non-decimal-int-string
}

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 Blog

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

Performance improvements #

Result cache improvements #

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

Detecting unused variables #

Inferring closure types from usages #

Inferring static variable types from assignments #

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

Update extensions today too! #

PHPStan 2.2: Unsealed Array Shapes, Safer Array Keys, and More!

Introducing unsealed array shapes #

Sealed array shapes become truly sealed #

Safer array keys #

Checking constants passed as function arguments #

Detecting named arguments with renamed parameters in subtypes #

Reducing false positives about constant conditions in traits #

Allowing custom rules to emit collector data #

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 #

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

`#[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 #