MissingPureAnnotation
Emitted when the config flag suggestPurityAnnotations is set to true and a potentially pure function or method does not have a @psalm-pure or @psalm-capabilities declaration: the issue suggests the capabilities it was inferred to need.
A function-like explicitly marked @psalm-impure is left alone: for example a hook that overriding methods may implement freely.
No annotation is suggested for an unannotated method that is overridden, nor for the code calling it: the overrides may do more than its own body does, and the annotation would restrict them.
No annotation is suggested for a function-like whose parameter default values need capabilities the annotation would not give them (see parameter default values).
To automatically add pure annotations where needed, run Psalm with --alter --issues=MissingPureAnnotation (it does not need the config flag).
<?php
function couldBePure(int $a): int {
return $a+1;
}
A function or method (not a closure) is inferred without what the _ purity of its parameters (Closure[_], Traversable[_], see @psalm-purity-template) would charge to its callers: calling the closures and callables found in a parameter with the default purity, directly ($f()), in its elements ($fs[0](), foreach ($fs as $f) { $f(); }) or in what they return ($f()()); iterating over an iterable parameter; and calling a method whose purity depends on a purity argument of a parameter (Doer[_] for a Doer with a @psalm-purity-template). The issue then names the parameters, and --alter adds the _ where it stands, along with the purity annotation.
<?php
/**
* @param list<Closure(int): int> $fs
*/
function applyAll(array $fs, int $x): int {
foreach ($fs as $f) {
$x = $f($x); // with --alter, $fs becomes list<Closure[_](int): int> and applyAll @psalm-pure
}
return $x;
}
Only what the function-like's own body does counts, not what the closures it creates do: those may be returned or stored rather than called. The parameter must not be assigned in the body, and the _ must be writable where the parameter's type is written (not behind a @psalm-type alias, and not where another purity is written).
Why this is useful
The annotation documents what the function may do, and Psalm then enforces it: a later change that adds a side effect is reported as ImpureFunctionCall instead of silently making every caller impure.
It also helps taint analysis, which keeps the taint of the arguments of each call to a pure function apart. Psalm infers that for functions and for methods that cannot be overridden (private or final methods, and methods of final classes). For an overridable method or a constructor the annotation is the only way to say it: see specializing taints in functions.
See inferring annotations in the purity model for how purity is inferred.