November 2, 2026 by Daniil Gentili - 10 minute read
Cross-posted from Daniil Gentili's blog ».
Announcing the release of Psalm 7!
Featuring a simply enormous number of new features and bug fixes, such as:
php://input and uploaded file names, flows through closures, generators, traits and by-reference parameters, and ready-made stubs for Guzzle, PSR-7, Monolog, MongoDB and more.io, time, write-props...), with purity templates for classes, closures and automatically inferred annotations;@template TError of Throwable = RuntimeException) for classes, functions and methods: Result<int> just works, and libraries can add templates without breaking their users.dev-master.Psalm 7 runs on 64-bit PHP 8.2 to 8.6. Upgrading is simple for most projects: see Upgrading below.
Taints are now stored as a bitmask, and the taint graph is resolved over compact summaries of each function. This makes security analysis up to 10x faster.
Combined analysis (#11384) runs type checking, security analysis and dead code detection together in one run, so taint analysis is now on by default (#11399).
Taint issues are reported with a SECURITY severity, and with a rank in SARIF reports (#12068, #11383). The results no longer change between runs or with the thread count (#11946, #11952, #11953).
<?php
$run = function (string $c): void {
shell_exec($c);
};
$run((string) $_GET['cmd']); // TaintedShell, through the closure
$mongo = new MongoDB\Driver\Manager('mongodb://localhost');
$mongo->executeQuery('db.users', new MongoDB\Driver\Query(['name' => $_GET['name']])); // TaintedNosql
/** @return mixed */
function body() {
return json_decode((string) file_get_contents('php://input'), true);
}
eval((string) body()); // TaintedEval: php://input is a source
TaintedNosql (MongoDB sinks), TaintedLlmPrompt (prompt injection), and TaintedUrlComponent / TaintedUrlPath (query and path injection). curl options and CURLFile are reported by what they do: SSRF, header injection, file access, sleep or callables. Every taint type is now documented (#11944, #11746, #12097, #12099, #12468).php://input, STDIN, the client-sent entries of $_SERVER and $_FILES, getopt(), $argv, DNS answers, exception messages, and the files, paths and URLs builtins read (#11945, #12086, #12246, #12245, #12135, #12139).foreach by reference, global and static variables, trait method bodies, promoted constructor properties, __toString(), inherited methods and their overrides, exceptions, and builtin functions and objects (#12147, #12096, #12095, #12121, #12243, #12255, #12272, #12091, #12127, #12262, #12084, #12102).int has no html taint). Array keys are tracked much more precisely. Inferred-pure functions are specialized per call, and @psalm-cli-only marks code whose output isn't an HTML response (#12079, #12348, #12150, #12375, #12048, #12459).loadLibraryStubs, on by default) (#12460–#12467, #12481–#12484).@psalm-taint-sink ($mode is 0 ? null : 'html') $content (#12458);@psalm-taint-sink sql $params[*] (#12171);@psalm-taint-source input return['key'] (#12455);~(html|has_quotes) (#12300);@psalm-flow through callables (($compute()) -> return), the receiver (($this) -> return), $this properties, and keyed stores (($value) -> Store::$data[$key]) (#12299, #12302, #12456, #12312, #12327);@psalm-taint-property-bag (#12486);psalm.xml (#12330).Codebase::getTaintNode(), getTaintPropertyNode(), addTaintPath(), getReceiverTaintPath(), and the taint nodes of a call's return value, arguments and receiver (#12454, #12414, #12489, #12535).@psalm-pure, @psalm-mutation-free and @psalm-external-mutation-free are replaced by capabilities, modelled on Hack's contexts and capabilities. A function-like declares exactly which side effects it may have: read-props, write-this-props, write-props, read-globals, write-globals, write-refs, io and time, with pure and impure at the two ends (#11984):
<?php
/** @psalm-capabilities time */
function today(): string {
return date('Y-m-d'); // no issue
}
/** @psalm-pure */
function todayWrong(): string {
return date('Y-m-d'); // ImpureFunctionCall: ... requires time
}
<psalm suggestPurityAnnotations="true"> to get MissingPureAnnotation and MissingImmutableAnnotation (and their abstract and interface variants), and run --alter --issues=MissingPureAnnotation,MissingImmutableAnnotation to add the annotations. The --alter command works without the attribute. The suggestions are opt-in.clone, __toString(), __invoke(), ArrayAccess, destructors, new $class and parameter defaults are now checked too.@psalm-pure can be used on classes, and plugins can declare the capabilities of the methods they handle.The new Purity Model article explains the model in full.
Many functions are only as pure as what they are given: array_map() is pure when its callback is. Purity templates are template parameters whose values are capability sets instead of types, like Hack's [ctx $f] contexts. A function can now be both pure and higher-order, and each call costs only what its arguments do (#11984).
With Closure[_], a function takes its purity from the closure it is given:
<?php
/**
* @psalm-pure
* @param Closure[_](int): int $f
*/
function apply(Closure $f, int $x): int {
return $f($x);
}
/** @psalm-pure */
function double(int $x): int {
return apply(fn(int $y): int => $y * 2, $x); // no issue: the closure is pure
}
/** @psalm-pure */
function noisy(int $x): int {
return apply(function (int $y): int { echo $y; return $y; }, $x); // ImpureFunctionCall: The context is pure but function call on apply requires io
}
/** @psalm-pure */
function lengths(array $words): array {
return array_map(fn(string $w): int => strlen($w), $words); // no issue: builtins taking callbacks work the same way
}
On a class, a purity template lets each subclass decide what its methods may do:
<?php
/** @psalm-purity-template P */
abstract class Handler {
/**
* @psalm-pure
* @psalm-purity-from-template P
*/
abstract public function handle(string $input): string;
}
/** @extends Handler[pure] */
final class Upper extends Handler {
/** @psalm-pure */
#[Override]
public function handle(string $input): string {
return strtoupper($input);
}
}
/** @extends Handler[io] */
final class Printer extends Handler {
/** @psalm-capabilities io */
#[Override]
public function handle(string $input): string {
echo $input;
return $input;
}
}
/** @psalm-pure */
function viaUpper(Upper $handler): string {
return $handler->handle('a'); // no issue: Upper binds P to pure
}
/** @psalm-pure */
function viaPrinter(Printer $handler): string {
return $handler->handle('a'); // ImpureMethodCall: The context is pure but method Printer::handle requires io
}
Traversable, Iterator, IteratorAggregate and Generator have a purity template, for what iterating over them does. iterable has one too. A generator with a purity annotation binds it to what its body does:
<?php
/**
* @psalm-pure
* @param Traversable[pure]<int, int> $xs
*/
function sum(Traversable $xs): int {
$total = 0;
foreach ($xs as $x) { // no issue
$total += $x;
}
return $total;
}
/**
* @psalm-pure
* @param Traversable<int, int> $xs
*/
function sumAny(Traversable $xs): int {
$total = 0;
foreach ($xs as $x) { // ImpureMethodCall: The context is pure but iterating over Traversable<int, int> requires impure
$total += $x;
}
return $total;
}
/**
* @psalm-pure
* @return Generator<int, int>
*/
function numbers(): Generator {
yield 1;
yield 2;
}
/** @psalm-pure */
function total(): int {
return sum(numbers()); // no issue: numbers() returns a Generator[pure]
}
Closure[io](int): void, Handler[pure], Iterator[pure]<int, string>, Box[io]<int>. Named templates are declared with @psalm-purity-template P and used with @psalm-purity-from-template P.@psalm-purity-template write-this-props <= C(write-this-props) <= write-this-props|write-props|io. A method may use the lower bound unconditionally. Subclasses must stay within the bounds, and get the default when they don't bind the template.Closure[P] parameter or a conditional @return on __construct. For example, new ArrayObject([...]) is an ArrayObject[pure], so a pure function may fill an ArrayObject it created (#12116, #12179, #12190).--alter adds Closure[_] to the closure parameters a function calls (#12077, #12019).array_map, usort, preg_replace_callback, iterator_to_array, CallbackFilterIterator, Fiber and more (#12122).See Purity templates in the Purity Model article.
Unused code is now found on a graph of references (#11939). Code is used only if it can be reached from an entry point, so classes and methods referenced only by other unused code, cycles included, are reported. Exceptions that are created but never thrown are reported too (#12487):
<?php
final class Service {
public function run(int $id): void {
if ($id < 0) {
new InvalidArgumentException('negative id'); // UnusedMethodCall: ... never thrown or used
}
echo $id;
}
}
final class Ping { // UnusedClass
public static function ping(): void { Pong::pong(); }
}
final class Pong { // UnusedClass
public static function pong(): void { Ping::ping(); }
}
(new Service())->run(1);
--find-unused-psalm-suppress now also checks suppressions on classes and on Tainted* issues.
Template defaults: a template can declare a default type, @template T = Default or @template T of Bound = Default, on classes, interfaces, traits, functions and methods. Psalm uses it when the type argument is left out: in @extends/@implements/@use, in a generic type with only its first arguments (Result<int>), in new, and in calls that don't infer the template. Libraries can add a template without breaking every Foo<A> their users wrote, and those users no longer get MissingTemplateParam. See Template defaults.
<?php
/**
* @template TValue
* @template TError of Throwable = RuntimeException
*/
final class Result {
/** @var TError|null */
public ?Throwable $error = null;
}
/** @param Result<int> $result */
function handle(Result $result): void {
$error = $result->error; // RuntimeException|null (Psalm 6: MissingTemplateParam, Throwable|null)
}
/** @template T */
interface Option {
/**
* @template TResult = T
* @param (callable(T): TResult)|null $map
* @return Option<TResult>
*/
public function map(?callable $map = null): Option;
}
/** @param Option<int> $option */
function check(Option $option): void {
$same = $option->map(); // Option<int> (Psalm 6: Option<never>)
}
New types and syntax: decimal-int-string and non-decimal-int-string, global constant wildcards, conditional types on types that depend on a template, is not in conditional types, and exact intersections of scalar and conditional types.
Constructor @return types.
New IntMaskComparison issue for int-masks compared by value.
Psalm runs on PHP 8.6 and has a PHP 8.6 call map.
The PHP 8.5 pipe operator and PHP 8.6 partial function application are fully typed: Psalm infers the type of every pipeline stage and the signature of every partially applied closure, so a stage that doesn't fit the previous one is reported :
<?php
function slug(string $title): string {
return $title
|> trim(...)
|> strtolower(...)
|> str_replace(' ', '-', ?); // no issue: each stage is typed
}
function lowercaseWords(string $title): string {
return $title |> explode(' ', ?) |> strtolower(...); // InvalidArgument: Argument 1 of strtolower expects string, but non-empty-list<string> provided
}
function wrongLength(string $title): string {
return $title |> trim(...) |> strlen(...); // InvalidReturnStatement: 'int<0, max>' does not match 'string'
}
^0.4): Composer will then only install the plugin with a Psalm release whose plugin API it was written for.psalm/plugin-phpunit, plugin-mockery, plugin-symfony, plugin-laravel and plugin-sabre-event, and enables each one, plus the webmozart/assert plugin, when your composer.json uses the matching library (loadLibraryPlugins, on by default) (#12568, #12570, #12571).ERROR_LEVEL (#11735, #11736).--init-ci generates a GitHub Actions workflow that runs the official Docker image, pinned to the Psalm version in your composer.lock. The docs now cover the Psalm GitHub Action and the Psalm Security Scan action, which sends security analysis results to GitHub code scanning.ghcr.io/psalm/psalm.compact output format is renamed table, and a new, truly compact compact format is added.<unsuppressibleIssues> makes the issues it lists impossible to suppress.For most projects, upgrading is as simple as updating the Composer dependency:
composer require --dev vimeo/psalm:^7.0 -W
Everything else is in the upgrade guide.
Most projects will notice:
runTaintAnalysis="false" to opt out.<psalm suggestPurityAnnotations="true">, new MissingPureAnnotation/MissingImmutableAnnotation issues appear for code that can be annotated. Fix them with --alter --issues=MissingPureAnnotation,MissingImmutableAnnotation. The annotations Psalm adds improve both security analysis and type inference:
$a->get() !== null ? $a->get() : '' is a string. Without @psalm-immutable, the second call is still ?string.Thanks to everyone who contributed to Psalm 7, and to everyone who tested the betas and release candidates and reported issues!
Full Changelog: 6.20.3...7.0.0