`
- `$pdo->exec("select * from users where name='" . $name . "'")`
## Taint Types
Psalm recognises a number of taint types by default, defined in the [Psalm\Type\TaintKind](https://github.com/vimeo/psalm/blob/master/src/Psalm/Type/TaintKind.php) class:
- `sql` - used for strings that could contain SQL
- `ldap` - used for strings that could contain a ldap DN or filter
- `html` - used for strings that could contain angle brackets or unquoted strings
- `has_quotes` - used for strings that could contain unquoted strings
- `shell` - used for strings that could contain shell commands
- `callable` - used for callable strings that could be user-controlled
- `unserialize` - used for strings that could contain a serialized string
- `include` - used for strings that could contain a path being included
- `eval` - used for strings that could contain code
- `ssrf` - used for strings that could contain text passed to Curl or similar
- `url_component` - used for strings that could contain URL syntax (`/`, `?`, `&`, `#`...) placed in the path, query or fragment of a URL
- `url_path` - used for strings that could be a `.` or `..` segment of the path of a URL, even URL-encoded
- `file` - used for strings that could contain a path
- `cookie` - used for strings that could contain a http cookie
- `header` - used for strings that could contain a http header
- `user_secret` - used for strings that could contain user-supplied secrets
- `system_secret` - used for strings that could contain system secrets
You're also free to define your own taint types when defining custom taint sources – they're just strings.
## Taint Sources
Psalm defines the following default taint sources:
- the `$_GET`, `$_POST`, `$_COOKIE` and `$_REQUEST` server variables;
- the entries of `$_SERVER` the client sends: the request headers (`HTTP_*`), the URI and what is taken from it (`REQUEST_URI`, `QUERY_STRING`, `PATH_INFO`, `PHP_SELF`, `argv`, ...), `REQUEST_METHOD`, `CONTENT_TYPE` and the HTTP authentication credentials, the same entries of a redirected request (`REDIRECT_*`), and any entry read with a key that is not a literal;
- the names, types and full paths of the uploaded files in `$_FILES`;
- reading from the input stream: `fopen()`, `file_get_contents()` and `file()` called with a literal `php://input` or `php://stdin` path, and the stream reading functions (`fgets()`, `fread()`, `stream_get_contents()`, ...) applied to such a handle;
- the predefined `STDIN` constant (the `php://stdin` stream).
- reading from the network: `socket_read()`, the data `socket_recv()`, `socket_recvfrom()` and `socket_recvmsg()` write to their by-reference parameter, `stream_socket_recvfrom()`, `curl_exec()` and `curl_multi_getcontent()`, and the streams opened with `fsockopen()`, `pfsockopen()`, `stream_socket_client()`, `stream_socket_accept()` and `socket_export_stream()` (so reading from them with `fgets()`, `fread()`, ... is a source too).
- DNS answers, which whoever runs the name servers of a domain chooses: `dns_get_record()`, the hosts `getmxrr()` writes to its by-reference parameter, and `gethostbyaddr()`.
- the command-line options `getopt()` returns, which whoever runs the script chooses.
- exceptions, since the analysis does not follow them from where they are thrown to where they are caught: their message (`getMessage()`), their trace (`getTraceAsString()`) and their string form, and the variable of a `catch` block, so dumping a caught exception (`print_r()`, `var_export()`) is a source too.
You can also [define your own taint sources](custom_taint_sources.md).
## Taint Sinks
Psalm currently defines a number of different sinks for builtin functions and methods, including `echo`, `include`, `header`.
What is written to a stream opened on a literal `php://output` path, which is the response, or `php://stdout`, which is the response under the CGI SAPI, is a sink as what `echo` outputs is: `file_put_contents()` to such a path, and `fwrite()`, `fputs()`, `fputcsv()`, `fprintf()`, `vfprintf()`, `stream_copy_to_stream()` and the `fwrite()` and `fputcsv()` methods of `SplFileObject` on a stream opened with `fopen()` or `new SplFileObject()` on such a path in the same function, and held by its variables.
You can also [define your own taint sinks](custom_taint_sinks.md).
## Avoiding False-Positives
Nobody likes to wade through a ton of false-positives – [here’s a guide to avoiding them](avoiding_false_positives.md).
## Limitations
Taint Analysis relies on not making any mistakes when escaping values, e.g.
```php
$sql = 'SELECT * FROM users WHERE id = ' . $mysqli->real_escape_string((string) $_GET['id']);
$html = "
 $_GET['img']) . )
Link 1
Line 2";
// Details:
// $id = 'id' - Missing quotes
// $img = '/ onerror=alert(1)' - Missing quotes
// $a1 = 'javascript:alert(1)' - Normal inline JavaScript
// $a2 = '/' onerror='alert(1)' - Pre PHP 8.1, single quotes are not escaped by default
// Test:
// /?id=id&img=%2F+onerror%3Dalert%281%29&a1=javascript%3Aalert%281%29&a2=%2F%27+onerror%3D%27alert%281%29
```
To avoid these issues, use Parameterised Queries for SQL and Commands (e.g. `exec`); and a context-aware templating engine for HTML. Then use the [literal-string](https://psalm.dev/docs/annotating_code/type_syntax/scalar_types/#literal-string) type to ensure sensitive strings are defined in your application (i.e. have been written by a developer).
## Security Issues
The issues of security analysis (`TaintedHtml`, `TaintedSql`, ...) flag potential vulnerabilities rather than type errors or code-quality problems. To tell them apart, Psalm's human-readable reports (`console`, `compact`, `table`, `by-issue-level` and `phpstorm`) show them under a `SECURITY` header instead of `ERROR`:
```
SECURITY: TaintedHtml - src/index.php:2:1 - Detected tainted HTML
```
A security issue configured with `errorLevel="info"` is still shown as `INFO`. Machine-readable reports (JSON, checkstyle, SARIF, ...) keep their usual severities; the JSON and XML reports also include an `is_security` field.
Plugins can mark their own issues the same way by implementing the `Psalm\Issue\SecurityIssue` interface.
## Using Baseline With Taint Analysis
Since taint analysis is performed separately from other static code analysis, it makes sense to use a separate baseline for it.
You can use --use-baseline=PATH option to set a different baseline for taint analysis.
## Viewing Results in a User Interface
Psalm supports the [SARIF](http://docs.oasis-open.org/sarif/sarif/v2.0/csprd01/sarif-v2.0-csprd01.html) standard for exchanging static analysis results. This enables you to view the results in any SARIF compatible software, including the taint flow.
### GitHub Code Scanning
[GitHub code scanning](https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/about-code-scanning) can be set up by using the [Psalm GitHub Action](https://github.com/marketplace/actions/psalm-static-analysis-for-php).
Alternatively, the generated SARIF file can be manually uploaded as described in [the GitHub documentation](https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/uploading-a-sarif-file-to-github).
The results will then be available in the "Security" tab of your repository.
### Other SARIF compatible software
To generate a SARIF report run Psalm with the `--report` flag and a `.sarif` extension. For example:
```bash
psalm --report=results.sarif
```
## Debugging the taint graph
Psalm can output the taint graph using the DOT language. This is useful when expected taints are not detected. To generate a DOT graph run Psalm with the `--dump-taint-graph` flag. For example:
```bash
psalm --taint-analysis --dump-taint-graph=taints.dot
dot -Tsvg -o taints.svg taints.dot
```
---
### Annotating Code Adding Assertions (`docs/annotating_code/adding_assertions.md`)
# Adding assertions
Psalm has five docblock annotations that allow you to specify that a function verifies facts about variables and properties:
- `@psalm-assert` (used when throwing an exception)
- `@psalm-assert-if-true`/`@psalm-assert-if-false` (used when returning a `bool`)
- `@psalm-if-this-is`/`@psalm-this-out` (used when calling a method)
A list of acceptable assertions [can be found here](assertion_syntax.md).
## Examples
If you have a class that verified its input is an array of strings, you can make that clear to Psalm:
```php
isValid();
}
/**
* @psalm-assert-if-false B $a
*/
function isInvalidB(A $a) : bool {
return !$a instanceof B || !$a->isValid();
}
function takesA(A $a) : void {
if (isValidB($a)) {
$a->bar();
}
if (isInvalidB($a)) {
// do something
} else {
$a->bar();
}
$a->bar(); //error
}
```
As well as getting Psalm to understand that the given data must be a certain type, you can also show that a variable must be not null:
```php
exception
* @psalm-assert-if-true Exception $this->getException()
*/
public function hasException(): bool {
return $this->exception !== null;
}
public function getException(): ?Exception {
return $this->exception;
}
public function foo(): void {
if( $this->hasException() ) {
// Psalm now knows that $this->exception is an instance of Exception
echo $this->exception->getMessage();
}
}
}
$result = new Result;
if( $result->hasException() ) {
// Psalm now knows that $result->getException() will return an instance of Exception
echo $result->getException()->getMessage();
}
```
Please note that the example above only works if you enable [method call memoization](https://psalm.dev/docs/running_psalm/configuration/#memoizemethodcallresults)
in the config file or annotate the class as [immutable](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-immutable).
You can use `@psalm-this-out` to change the template arguments of a method after a method call, to reflect changes to the object's internal state.
You can also make assertions on the object's template arguments using `@psalm-if-this-is`.
```php
*/
private array $data;
/**
* @param T $data
*/
public function __construct($data) {
$this->data = [$data];
}
/**
* @template NewT
*
* @param NewT $data
*
* @psalm-this-out self
*
* @return void
*/
public function addData($data) {
/** @var self $this */
$this->data []= $data;
}
/**
* @template NewT
*
* @param NewT $data
*
* @psalm-this-out self
*
* @return void
*/
public function setData($data) {
/** @var self $this */
$this->data = [$data];
}
/**
* @psalm-if-this-is a
*/
public function test(): void {
}
}
$i = new a(123);
// OK - $i is a<123>
$i->test();
$i->addData(321);
// OK - $i is a<123|321>
$i->test();
$i->setData("test");
// IfThisIsMismatch - Class is not a as required by psalm-if-this-is
$i->test();
```
`@psalm-this-out` (and its aliases `@psalm-self-out`, `@phpstan-self-out` and `@phpstan-this-out`) also accepts a conditional type keyed off one of the method's parameters, e.g. `@phpstan-this-out ($key is null ? static : $this)`. The branch is resolved from the argument passed at each call site, so a call that omits `$key` (or passes `null`) infers a different resulting type than one that passes a concrete value. `@psalm-if-this-is` does not support this form, since its condition must be known before the call's arguments are analyzed.
---
### Annotating Code Assertion Syntax (`docs/annotating_code/assertion_syntax.md`)
# Assertion syntax
Psalm’s [assertion annotation](adding_assertions.md) supports a number of different assertions.
Psalm assertions are of the form
`@psalm-assert(-if-true|-if-false)? (Assertion) (Variable or Property)`
`Assertion` here can have many forms:
## Regular assertions
### is_xxx assertions
Most `is_xxx` PHP functions have companion assertions e.g. `int` for `is_int`. Here's the full list:
- `int`
- `float`
- `string`
- `bool`
- `scalar`
- `callable`
- `countable`
- `array`
- `iterable`
- `numeric`
- `resource`
- `object`
- `null`
So a custom version `is_int` could be annotated in Psalm as
```php
$foo`
## Negated assertions
Any assertion above can be negated:
This asserts that `$foo` is not an `int`:
```php
n++`
needs `read-props|write-this-props`, and code that writes both `$this` and other objects needs
`write-this-props|write-props`. `write-props` does not include `write-this-props`, and
`write-globals` does not include `read-globals`. A plain assignment only needs the write
capability: `$this->n = 0` needs `write-this-props`, `Counter::$count = 0` needs `write-globals`.
Using `$this` at all needs `read-props` or `write-this-props`, so a setter returning `$this` may be
`write-this-props`.
```php
n;
}
/** @psalm-capabilities write-this-props */
public function nextWrong(): int {
return ++$this->n; // ImpurePropertyFetch: The context is write-this-props but accessing a property on a mutable object requires read-props
}
}
/** @psalm-capabilities read-globals */
function total(): int {
return Counter::$count;
}
/** @psalm-capabilities read-globals */
function resetTotal(): int {
Counter::$count = 0; // ImpureStaticProperty: The context is read-globals but writing a static property requires write-globals
return 0;
}
```
### Global state
Values reached from global state stay bound to it. An object read from a static property, a
superglobal or a `global` variable, returned by a function that may read globals, or fetched from
such an object, can only have its properties written, its mutating methods called, or be passed
to a function that may write properties, by code that has `write-globals`. This makes
`read-globals` a read-only view of global state, like Hack's `readonly` values:
```php
env = "dev"; // ImpurePropertyAssignment: The context is write-props|read-globals but property assignment to Config::$env on an object reached from global state requires write-props|write-globals
}
}
```
A new object the caller created (see [Method calls](#method-calls)) is not global state itself,
even when its constructor read global state, or when it is a clone of an object reached from
global state: writing its own properties is free. What it holds may be global state, so writing
another object through it, or calling a method that does, costs `write-globals` too.
## Annotations
Every purity annotation is a name for a capability set:
| Annotation | Used on | Capabilities |
|---------------------------------|----------------------------------|----------------------------------------------------|
| `@psalm-pure` | function, method, class | `pure`; on a class, properties can't be used at all |
| `@psalm-capabilities ` | function, method, closure, class | `` |
| `@psalm-impure` | function, method | `impure`, written out |
| `@psalm-immutable` | class | `read-props` for every method, and every property is readonly |
| `@psalm-mutable` | class | `impure`, written out |
| `@psalm-mutation-free` | function, method, class | `read-props` (legacy) |
| `@psalm-external-mutation-free` | function, method, class | `read-props\|write-this-props\|write-refs` (legacy) |
| none | | `impure` |
`@pure`, `@phpstan-pure`, `#[Psalm\Pure]` and `#[JetBrains\PhpStorm\Pure]` mean the same as
`@psalm-pure`; `#[Psalm\Immutable]` and `#[JetBrains\PhpStorm\Immutable]` the same as
`@psalm-immutable`; `#[Psalm\ExternalMutationFree]` the same as `@psalm-external-mutation-free`.
### Capability aliases
A capability set can be named once with a type alias and used in `@psalm-capabilities`, in
closure types and as a purity argument, like Hack's context constants. Aliases of other classes
are imported with `@psalm-import-type`:
```php
save();
$after();
}
}
```
### Conditional capabilities
What a call requires may depend on its arguments, like a conditional return type. Each call
requires the branch its arguments select. Where the arguments may go either way, or there is no
call (a callable taken from the function), it requires both. The body may do what either branch
allows.
```php
$numbers
*/
function sum(array $numbers): int {
$total = 0;
$add = function (int $value) use (&$total): void { $total += $value; };
foreach ($numbers as $number) {
$add($number); // fine: $total belongs to sum()
}
return $total;
}
/**
* @psalm-pure
* @param Closure[pure](int): void $callback
*/
function callWithOne(Closure $callback): int {
$callback(1);
return 1;
}
/** @psalm-pure */
function leak(): int {
$total = 0;
return callWithOne(function (int $value) use (&$total): void { $total += $value; }); // ArgumentTypeCoercion: Argument 1 of callWithOne expects Closure[pure](int):void, but parent type Closure[read-props|write-this-props](int):void provided
}
```
Likewise, an object the enclosing scope created and the closure captures, by value or by
reference, is state of the closure, as an object a class instance creates is its own. So are the
objects in a captured array the enclosing scope created, and the state of a closure that a closure
created in it captures. Writing that state, or calling a method that writes it, needs
`write-this-props`, and the enclosing scope may call the closure freely. An object the enclosing
scope did not create, like a parameter, belongs to someone else: writing it needs `write-props`.
## Class-level contracts
`@psalm-capabilities` on a class or interface is a contract for the class and for everything that
extends or implements it. Every method of the class gets those capabilities, and may declare fewer
but not more:
```php
n++;
}
public function incTwice(): void {
$this->inc(); // fine: costs write-this-props
$this->inc();
}
public function get(): int {
return $this->n;
}
}
/** @psalm-pure */
function countTwice(): int {
$counter = new Counter();
$counter->inc(); // fine: $counter was created here
$counter->inc();
return $counter->get();
}
/** @psalm-capabilities read-props */
function bump(Counter $counter): int {
$counter->inc(); // ImpureMethodCall: The context is read-props but method Counter::inc requires write-props
return $counter->get();
}
```
Reading or unsetting a property gets the same waiver: it is free on an object the caller created
with `new`, from a class whose contract needs at most `read-props|write-this-props|write-refs`, as
nobody else can change it. Reading a property of any other mutable object, including `$this`, a
parameter or an object held in a property, costs `read-props`, whatever the class's contract:
```php
n++;
}
}
/** @psalm-pure */
function tallyTwice(): int {
$tally = new Tally();
$tally->inc();
$tally->inc();
return $tally->n; // fine: $tally was created here
}
/** @psalm-pure */
function currentTally(Tally $tally): int {
return $tally->n; // ImpurePropertyFetch: The context is pure but accessing a property on a mutable object requires read-props
}
```
Without a class-level contract, calling a method on an object the caller created with `new`, and
reading or writing its properties, is still free, as long as the constructor can't keep a reference
to the new object anywhere. Only
three things can hand `$this` to someone else: writing another object (`write-props`), global state
(`write-globals`) or a by-reference parameter (`write-refs`). So a constructor that needs none of
these qualifies, and so does a class without a constructor:
```php
*/
private array $words = [];
/** @psalm-capabilities read-props */
public function __construct(string $first) {
$this->words[] = $first;
}
/** @psalm-capabilities read-props|write-this-props */
public function add(string $word): void {
$this->words[] = $word;
}
/** @psalm-capabilities read-props */
public function text(): string {
return implode(" ", $this->words);
}
}
/** @psalm-pure */
function hello(): string {
$greeting = new Greeting("hello");
$greeting->add("world"); // fine: the constructor can't hand $greeting to anyone
return $greeting->text();
}
```
A constructor without a purity annotation qualifies too when it is trivial: it does nothing, or only
assigns its parameters (or constant values) to properties its class declares, promoted ones included.
Such a constructor needs `write-this-props` without being annotated (nothing at all if it is empty), so
neither `new` nor its class needs an annotation for the waiver. Any other statement makes it non-trivial:
a call (`parent::__construct()` included), a by-reference parameter, a default value that creates an
object or calls something, a property with hooks or one the class doesn't declare before the
constructor, or `$this` stored anywhere. A non-trivial constructor without an annotation may do
anything, as any unannotated method. So may a trivial constructor run for a class that redeclares one
of the properties it assigns with a hook (PHP 8.4), or by `new static()` / `new $class()` where the
class may be extended: the hook may do anything.
```php
z = 1; // fine: Point's constructor is trivial
return $point;
}
```
A constructor that may store `$this` somewhere loses the waiver. Here the constructor registers
every new object in a static property, so calling a method on the new object costs what it would
on any other one. The object is also reached from global state now, which adds `write-globals`:
```php
*/
public static array $all = [];
public int $uses = 0;
/** @psalm-capabilities read-globals|write-globals */
public function __construct() {
self::$all[] = $this;
}
/** @psalm-capabilities read-props|write-this-props */
public function use(): void {
$this->uses++;
}
}
/** @psalm-capabilities read-globals|write-globals */
function register(): Registered {
$registered = new Registered();
$registered->use(); // ImpureMethodCall: The context is read-globals|write-globals but method Registered::use requires write-props|write-globals
return $registered;
}
```
A constructor that writes another object, such as linking the new object to a parent passed to
it, or that writes a by-reference parameter, loses it the same way.
A `clone` is a new object too, by the same rule: the copy is free to mutate unless the class's
`__clone` needs `write-props`, `write-globals` or `write-refs`, and so may hand the copy to someone
else. A class-level contract keeps the waiver, for a clone as for a new object:
```php
*/
public static array $copies = [];
public int $uses = 0;
/** @psalm-capabilities read-props|read-globals|write-globals */
public function __clone() {
self::$copies[] = $this;
}
/** @psalm-capabilities read-props|write-this-props */
public function use(): void {
$this->uses++;
}
}
/** @psalm-capabilities read-props|read-globals|write-globals */
function copyTracked(Tracked $tracked): Tracked {
$copy = clone $tracked;
$copy->use(); // ImpureMethodCall: The context is read-props|read-globals|write-globals but method Tracked::use requires write-props
return $copy;
}
```
When the class isn't known exactly, there is no waiver: `new static()` in a class that may be
extended, and `new $class()`, may run the constructor of a subclass that keeps a reference:
```php
count++;
}
}
/** @psalm-capabilities read-props|write-this-props */
function makeItem(): Item {
$item = new Item();
$item->bump(); // fine: an Item, whose constructor can't keep $item
return $item;
}
/**
* @param class-string- $class
* @psalm-capabilities read-props|write-this-props
*/
function makeAny(string $class): Item {
$item = new $class();
$item->bump(); // ImpureMethodCall: The context is read-props|write-this-props but method Item::bump requires write-props
return $item;
}
```
This waiver covers calling methods, and writing and reading properties: reading a property of
such an object directly is free too, as calling a `read-props` method on it is. What the property
holds is another matter: reading a property of an object stored in it costs `read-props`, as that
object may be shared.
The `write-this-props` that a class purity template of the receiver is bound to
(`Doer[write-this-props]`, see [Purity templates](#purity-templates)) is charged the same way,
except that it is never waived for a new object. A receiver reached from
[global state](#global-state) also costs `write-globals`.
### Fluent calls
A method returns its receiver if it declares `@return $this`, or if no override can replace it
(it is private, final or in a final class) and each of its returns is `return $this;`. A call on
`$this` of such a method gives back `$this`, so a fluent chain on `$this` only mutates `$this`,
and so does writing a property of what the chain returns. `@return static` is not enough: the
method may return another instance of the class.
`@return $this` is a promise, checked like a return type: the method and every override of it may
only return `$this`, or a call on it of another method returning its receiver; any other return is
an [InvalidReturnStatement](../running_psalm/issues/InvalidReturnStatement.md).
```php
*/
private array $conditions = [];
/**
* @return $this
* @psalm-capabilities read-props|write-this-props
*/
public function where(string $condition): static {
$this->conditions[] = $condition;
return $this;
}
/** @psalm-capabilities read-props|write-this-props */
public function whereBetween(string $from, string $to): static {
return $this->where($from)->where($to); // fine: costs write-this-props
}
/** @psalm-capabilities read-props */
public function copy(): static {
return clone $this;
}
/** @psalm-capabilities read-props|write-this-props */
public function copyWhere(string $condition): static {
return $this->copy()->where($condition); // ImpureMethodCall: The context is read-props|write-this-props but method Query::where requires write-props
}
}
```
### By-reference arguments
A call to a function-like with `write-refs` does not cost `write-refs` itself. Each argument
passed by reference costs what writing it directly would cost: nothing for a local variable,
`write-refs` for one of the caller's own by-reference parameters, `write-this-props` for a property
of `$this`, `write-props` for another object's property, and `write-globals` for global state.
The callee itself still only has `write-refs`. This includes builtins such as `sort()`, so a pure
function may sort a local array.
```php
`: the purity argument of a class with a purity template;
- `@extends Handler[pure]`, `@implements Iterator[pure]`: a subclass binding it.
The purity templates of a class come after its type templates, whatever the order of the
`@template` and `@psalm-purity-template` tags. A class with `@template T` and
`@psalm-purity-template P` is used as `Box[pure]`, as `Box` for its default purity, or
as `Box[pure]` for its default type arguments. Several purity arguments are separated by commas
(`Pair[pure, io]`), and each is a capability set (`write-props|io`) or a purity template.
An empty set is written `pure`; `Handler[]` is an array of `Handler`.
Purity templates are covariant: a `Handler[pure]` can be used where a `Handler[io]` is expected.
The bounds of type templates may use purity templates, which are then inferred with them: a
class with `@template TIterator as Traversable[P]` and `@psalm-purity-template P`,
constructed with a `Generator[pure]`, is a
`Foo[pure]>`.
### `@psalm-purity-from-template`
[`@psalm-purity-from-template P`](supported_annotations.md#psalm-purity-from-template) says that
each call needs the function-like's own capabilities plus whatever `P` is bound to at that call.
Inside the body, calling a closure whose purity is `P` is not an effect: each caller pays for it,
like with Hack's `[ctx $f]` contexts. It works for functions, methods, static methods and constructors. `P` may be a purity template of
the function-like or of its class, or a type template bound to a closure or callable type.
With a class-level template, subclasses decide the purity:
```php
handle('a'); // fine: Upper binds P to pure
}
/**
* @psalm-pure
* @param Handler[pure] $handler
*/
function viaPureHandler(Handler $handler): string {
return $handler->handle('a'); // fine
}
/**
* @psalm-pure
* @psalm-purity-template Q
* @param Handler[Q] $handler
* @psalm-purity-from-template Q
*/
function viaSomeHandler(Handler $handler): string {
return $handler->handle('a'); // fine: pure when given an Upper, io when given a Printer
}
/** @psalm-pure */
function viaAnyHandler(Handler $handler): string {
return $handler->handle('a'); // ImpureMethodCall: The context is pure but method Handler::handle requires impure
}
```
With a function-level template, the closures passed in decide the purity:
```php
$x + 1); // fine: the closure is pure
}
/** @psalm-capabilities io */
function useIo(): int {
return apply(function (int $x): int { echo $x; return $x; }); // fine: the call costs io
}
/** @psalm-pure */
function usePrinting(): int {
return apply(function (int $x): int { echo $x; return $x; }); // ImpureFunctionCall: The context is pure but function call on apply requires io
}
```
A type template bound to a closure type carries the closure's purity, so it works with
`@psalm-purity-from-template` too:
```php
callback = $callback;
}
/**
* @psalm-capabilities read-props
* @psalm-purity-from-template T
*/
public function run(): void {
($this->callback)();
}
}
/**
* @psalm-capabilities read-props
* @param Deferred $deferred
*/
function runPure(Deferred $deferred): void {
$deferred->run(); // fine: T is a pure closure
}
```
### The `_` shorthand
The common case, a function whose purity follows one closure parameter, needs no named template:
`Closure[_](...)` or `callable[_](...)` in a `@param` type declares one, and the function takes
its purity from that parameter, like Hack's `(function()[_]: T) $f`. This is the same `apply()` as
above:
```php
`,
`Traversable[_]`). Every `_` in one parameter's type stands for the same template,
which has no name of its own, so it never clashes with a template declared in the docblock. `_`
can only be used in `@param` types: in `@return`, `@param-out`, `@psalm-assert`, `@var`,
`@property` or `@template` bounds it has no parameter to stand for.
On a promoted constructor parameter, `_` makes `new` take the purity of the closure passed for
it, as for any other parameter. The property, though, outlives that call, so its type uses the
template's bound: here `$f` is an `impure-Closure(): int`, and calling it needs every capability,
whatever closure was passed.
```php
1)` is a `Holder[pure]`, whose `$f` is a pure closure.
The parameters of an `@method` may use `_` too. A call to such a method needs what `__call` (or
`__callStatic`) needs, plus the capabilities of the closures passed for its `_` parameters:
```php
run(fn(): int => 1); // fine: the closure is pure
}
```
### Defaults and bounds
The bounds of a purity template are written as a chain, `lower <= Name(default) <= upper`, where
every part but the name is optional:
- the upper bound is the most a value may need (`impure` when left out): `P <= write-props|io`;
- on a class, the lower bound is what every value needs, which the methods depending on the
template may then use unconditionally: `write-this-props <= C`;
- the default, in parentheses, applies to subclasses that don't bind the template: `C(pure)`.
Several templates can be declared in one tag, separated by commas (`P <= io, Q`). In a chain with
a single bound, the side that is a capability is the bound: `io <= C` is a lower bound and
`C <= io` an upper bound. A type alias used as a lower bound needs the upper bound written out
as well (`Alias <= C <= impure`). In Hack these are the bounds and default of a context
constant, with the keywords reversed as contexts are types:
`abstract const ctx C super [write_props, io] as [write_this_props] = [write_this_props]`.
A binding must include the lower bound itself: `Doer[io]` is rejected, write `Doer[write-this-props|io]`.
```php
runs++; // fine: every C includes write-this-props
return $this->runs;
}
}
/** @extends Doer[write-this-props|io] */
final class LoudDoer extends Doer {} // fine: between the bounds
/** @extends Doer[write-globals] */
final class GlobalDoer extends Doer {} // InvalidTemplateParam: Extended template param C expects type write-this-props|write-props|io, type write-globals given
/** @extends Doer[pure] */
final class PureDoer extends Doer {} // InvalidTemplateParam: Extended template param C must include at least write-this-props, pure given
final class DefaultDoer extends Doer {} // C is write-this-props
```
### Constructors
A constructor may take its purity from a class purity template. `new Sub()` then costs what `Sub`
binds the template to, or its default or upper bound when `Sub` doesn't bind it, and
`new static()` costs the template itself, as it may instantiate any class extending the class.
`new` can also bind a class purity template from what the constructor is given. A parameter
typed `Closure[P]` binds it from the purity of a closure. To bind it from the *kind* of argument
instead, give the constructor a `@return`: the type of the `new` expression, which is the class
itself with its template and purity arguments. Like any return type, it may be conditional.
`ArrayObject` and `ArrayIterator` are declared this way: their mutators only write the object
itself when it stores an array, but also write the object it wraps when given one. A class like
them can say so:
```php
|object $storage
* @return ($storage is array ? Store[pure] : Store[write-props])
* @psalm-pure
*/
public function __construct(array|object $storage = []) {}
/**
* @param TValue $value
* @psalm-purity-from-template TStorage
*/
public function add($value): void {
$this->writes++;
}
}
/** @psalm-pure */
function fromArray(): int {
$store = new Store([1]); // Store[pure]
$store->add(2); // fine: TStorage is pure, and $store was created here
return 1;
}
/** @psalm-pure */
function fromObject(stdClass $object): int {
$store = new Store($object); // Store[write-props]
$store->add(1); // ImpureMethodCall: The context is pure but method Store::add requires write-props
return 1;
}
```
An argument that may be either an array or an object gives the union of both types, so calling
`add()` on the result costs `write-props`. A `@return` without a condition binds type templates
the same way: with `@return Box` on its constructor, `new Box()` is a `Box`.
A condition can also be given to each purity argument, inside the brackets, and a branch may be a
purity template of the constructor, bound from the argument. With
`@param array|Container[PP] $param` and `@return self[$param is array ? pure : PP]`,
`new Wrapper($container)` takes the purity argument of `$container`, `io` for a
`Container[io]`. Such conditional purity arguments are resolved per call in the
`@return` of any function or method, also nested (`list>`), and in
`@psalm-self-out`.
The `@return` of a constructor may only name its own class (or `self` or `static`); anything else
is an `InvalidDocblock`. Since it names the class itself, a subclass inheriting the constructor,
and `new static()` in a class that isn't final, get the type `new` would give without it.
### Iterators and generators
`Traversable`, `Iterator`, `IteratorAggregate` and `Generator` have a purity template besides
their key and value templates, `TPurity`: what iterating over them may do.
`Iterator[pure]` can be iterated by a pure function, and
`Generator[io]` prints when consumed. It defaults to `impure`, so
`Iterator` still means an iterator about which nothing is known.
Iterating over a value known only by one of these types costs its `TPurity` and nothing else: a
pure function may consume any `Iterator[pure]` or
`Generator[pure]`, including one it was given (where a generator is
paused is internal engine state). Iterating over an object of an iterator class calls that
class's own methods (`rewind`, `valid`, `current`, `key`, `next`, or `getIterator()` and then the
methods of the iterator it returns, which counts as new), so it costs what they need like any
other [method call](#method-calls).
`iterable` has a purity too: `iterable[pure]` accepts arrays (iterating over an array
does nothing) and `Traversable[pure]`, and a pure function may iterate over it. A
plain `iterable` is `iterable[impure]`, since it may be any
`Traversable`. The purity of an `iterable` parameter may be a purity template
(`iterable[P]`), bound by each call to what iterating over the argument does.
A generator function-like with a purity annotation binds the `TPurity` of the `Generator` (or
`Iterator`, `Traversable`) it returns, or the purity of the `iterable` it returns, to its own
capabilities and purity templates, which every call resolves: consuming the generator costs what
running its body costs.
```php
*/
function map(Closure $f): Generator { yield $f(); return 0; }
/** @psalm-pure */
function sum(): int {
$total = 0;
foreach (map(fn(): int => 1) as $x) { // fine: a Generator[pure]
$total += $x;
}
return $total;
}
/**
* @psalm-pure
* @param Generator[io] $generator for example map(function (): int { echo "x"; return 1; })
*/
function printAll(Generator $generator): int {
foreach ($generator as $x) {} // ImpureMethodCall: The context is pure but iterating over Generator[io] requires io
return 0;
}
```
A class implementing `Iterator` or `IteratorAggregate` may bind `TPurity` in its `@implements`
(`@implements Iterator[pure]`); its iteration methods (or its `getIterator()` and
what that returns) must then fit the binding. A class that doesn't bind it gets it from those
methods, as whoever iterates over it sees them: a method writing the iterator's own properties
makes it `write-this-props|write-props`. So `MyIterator` is accepted where
`Iterator[pure]` is expected exactly when its iteration methods are pure.
The SPL iterators wrapping another one (`IteratorIterator`, `FilterIterator`,
`CallbackFilterIterator`, `LimitIterator`, `NoRewindIterator`, `InfiniteIterator`) have a
`TPurity` too, bound at construction to what iterating over the inner iterator (and calling the
callback of a `CallbackFilterIterator`) does: `new CallbackFilterIterator(gen(), fn(int $v): bool => $v > 0)`
is a `CallbackFilterIterator[pure]<...>` when `gen()` returns a `Generator[pure]<...>`. A subclass of
`FilterIterator` that doesn't bind `TPurity` iterates impurely, whatever its `accept()` does.
### Builtins taking callbacks
The builtins that call the closures they are given work the same way: `array_map`, `usort`,
`preg_replace_callback`, `ArrayObject::uasort`, `Ds\Vector::map`, … need what their callbacks
need and nothing else, and `iterator_to_array` and `iterator_count` what iterating over their
argument does. `Fiber` has a purity template for what its callback does, which starting or
resuming the fiber costs. `Closure::bind()` and `bindTo()` keep the type of the closure they
rebind, and `$closure->call($newThis, ...)` is a call of the closure that writes `$newThis`
where the closure writes `$this`.
## Overrides
An override may need fewer capabilities than the method it overrides, never more. This holds for
every capability, and for interface methods as well as parent class methods:
```php
side * $this->side;
}
}
/** @psalm-pure */
final class Unit implements Shape {
public function area(): float { // fine: pure needs less than read-props
return 1.0;
}
}
// both reported on the class name:
// ImmutableDependency: Shape is marked with @psalm-immutable, but LoggedUnit is not
// ImmutableDependency: Shape::area is read-props, but LoggedUnit::area additionally requires io
/** @psalm-capabilities io */
final class LoggedUnit implements Shape {
public function area(): float {
echo 'area';
return 1.0;
}
}
```
[ImmutableDependency](../running_psalm/issues/ImmutableDependency.md) is a level 1 issue, so it is
reported as info at the default level 2.
A subclass may bind a class purity template of its parent to one of its own
(`@psalm-purity-template P` with `@extends Filter[P]`), which each `new` then binds, possibly to
`pure`. So an override of a method with `@psalm-purity-from-template` may use the template only as
the parent does: what it needs unconditionally must fit what the parent's method needs
unconditionally, plus the template's lower bound. This is like overrides in Hack, which may only
use an abstract context constant through `this::C`.
## Property refinements after calls
By default Psalm remembers what it knows about object properties across calls. With
[`rememberPropertyAssignmentsAfterCall="false"`](../running_psalm/configuration.md#rememberpropertyassignmentsaftercall),
it forgets refinements after a call, but only those the call could invalidate:
| The callee may use | Psalm forgets refinements of |
|-----------------------------------|---------------------------------------------------|
| `write-this-props` or `write-props` | properties of mutable objects |
| `write-globals` | static properties and superglobals |
| none of these | nothing |
This applies to function calls, method calls, static calls and `new`. With
`rememberPropertyAssignmentsAfterCall="false"`, this code reports one issue:
```php
total = null;
}
function kept(Order $order): int {
if ($order->total === null) {
return 0;
}
currencyIsSet();
return $order->total; // fine: currencyIsSet() can't write properties
}
function forgotten(Order $order, Order $other): int {
if ($order->total === null) {
return 0;
}
clear($other);
return $order->total; // NullableReturnStatement: clear() may have written $order->total
}
```
## Inferring annotations
Psalm infers the capabilities of unannotated code from its body and the callees it uses. It does
so as a fixpoint over the call graph, after the whole codebase has been analysed: a function-like
that only calls pure function-likes, annotated or inferred, is pure itself, whatever the order in
which they are declared, and mutual recursion, recursive closures and closures assigned to a
variable are handled. It reports code that could be annotated:
- [MissingPureAnnotation](../running_psalm/issues/MissingPureAnnotation.md): a function or method
that could have `@psalm-pure` or `@psalm-capabilities`;
- [MissingImmutableAnnotation](../running_psalm/issues/MissingImmutableAnnotation.md): a class
that could have `@psalm-pure`, `@psalm-immutable` or `@psalm-capabilities`;
- [MissingAbstractPureAnnotation](../running_psalm/issues/MissingAbstractPureAnnotation.md): an
abstract method with no annotation;
- [MissingInterfaceImmutableAnnotation](../running_psalm/issues/MissingInterfaceImmutableAnnotation.md):
an interface with no annotation.
The first two can be fixed automatically:
```bash
vendor/bin/psalm --alter --issues=MissingPureAnnotation,MissingImmutableAnnotation
```
Given this code:
```php
items++;
}
public function count(): int {
return $this->items;
}
}
```
`--alter` adds `@psalm-pure` to `slug()`, and `@psalm-capabilities read-props|write-this-props|write-refs`
to `Cart` and `addItem()`. Suggestions use the four named levels only: `pure`, `read-props`,
`read-props|write-this-props|write-refs` and `impure` (`@psalm-immutable` for a class at
`read-props`). Write a narrower set by hand if you want one.
A [class-level contract](#class-level-contracts) binds every subclass too, so the one suggested
for a class is the smallest of these levels that allows:
- what the class's own methods need;
- the contract of its parent class;
- what each known subclass needs, or what its contract allows if it has one;
- for a class but not an interface, the upper bounds of its [purity templates](#defaults-and-bounds), up to which
subclasses may bind them.
So an abstract base class whose subclasses do more, or a class with a purity template whose upper
bound is left as `impure`, gets no class-level suggestion. A subclass without an annotation is
suggested a contract on the next run, once its parent has one.
```php
count++;
}
}
```
Psalm doesn't suggest an annotation for an unannotated method that is overridden somewhere, nor
for the code calling it, since the annotation would restrict its overrides. Annotate it yourself
when you want a contract. It doesn't suggest one either when the function-like's
[parameter default values](#parameter-default-values) need capabilities the annotation wouldn't
give them. A function-like marked `@psalm-impure` is never reported.
These issues are always reported as errors. To turn them off, or to adopt them gradually, use
`issueHandlers`:
```xml
```
## Migrating from Psalm 6
Existing annotations keep their meaning:
- `@psalm-pure` and `@psalm-immutable` are unchanged.
- `@psalm-mutation-free` means `@psalm-capabilities read-props`.
- `@psalm-external-mutation-free` means `@psalm-capabilities read-props|write-this-props|write-refs`.
It no longer allows static properties or `static` variables: use `read-globals` or
`write-globals` for those.
`@psalm-mutation-free` and `@psalm-external-mutation-free` are still accepted but no longer
documented or suggested. `mutation-free` and `external-mutation-free` are not capability names,
so `@psalm-capabilities mutation-free` is an `InvalidDocblock`.
What changes for your code:
- **Calls on objects of the same class are no longer free.** In Psalm 6, a method could call a
mutating method on any object of its own class, and a `@psalm-mutation-free` method could call
one on `$this`. Now a call on `$this` costs `write-this-props` and a call on any other object
costs `write-props` (see [Method calls](#method-calls)).
- **Overrides are checked at every level.** Psalm 6 only reported impure overrides of
`@psalm-external-mutation-free` methods. Now any override that needs more capabilities is
reported, as `ImmutableDependency`.
- **`MissingImmutableAnnotation` has a new meaning.** In Psalm 6 it reported a mutable class
inheriting from an immutable one; that is now `ImmutableDependency`. `MissingImmutableAnnotation`
now reports a class that *could* be annotated. Review existing suppressions of it.
- **New issues are reported by default:** `MissingPureAnnotation`, `MissingImmutableAnnotation`,
`MissingAbstractPureAnnotation` and `MissingInterfaceImmutableAnnotation`. Run `--alter` once,
or suppress them (see [Inferring annotations](#inferring-annotations)).
- **More is checked.** Implicit calls (`__toString`, `__clone`, `__invoke`, `ArrayAccess`,
destructors), `throw new`, `new $className` and `call_user_func` are now checked for purity.
Builtins with side effects need specific capabilities: `io` for I/O and random numbers,
`time` for reading the clock, `write-globals` for process-wide state such as `mt_rand()` or `ini_set()`.
- **Iteration has a purity.** `foreach` over an object costs the iterator's methods, or the
`TPurity` of `Traversable`, `Iterator`, `Generator` and `iterable`, instead of always being
impure (see [Iterators and generators](#iterators-and-generators)).
- **Callable types:** `pure-callable` and `pure-Closure` still work, and any capability set can
now be written, as in `Closure[io](int): void`. The capability names (`pure`, `impure`,
`read-props`, …) are now reserved type names.
The full list of changes is in
[UPGRADING.md](https://github.com/vimeo/psalm/blob/master/UPGRADING.md).
---
### Annotating Code Supported Annotations (`docs/annotating_code/supported_annotations.md`)
# Supported docblock annotations
Psalm supports a wide range of docblock annotations.
## PHPDoc tags
Psalm uses the following PHPDoc tags to understand your code:
- [`@var`](https://docs.phpdoc.org/guide/references/phpdoc/tags/var.html)
Used for specifying the types of properties and variables
- [`@return`](https://docs.phpdoc.org/guide/references/phpdoc/tags/return.html)
Used for specifying the return types of functions, methods and closures. On a constructor, it
gives the type of the object `new` creates (see [Constructors](purity_model.md#constructors))
- [`@param`](https://docs.phpdoc.org/guide/references/phpdoc/tags/param.html)
Used for specifying types of parameters passed to functions, methods and closures
- [`@property`](https://docs.phpdoc.org/guide/references/phpdoc/tags/property.html)
Used to specify what properties can be accessed on an object that uses `__get` and `__set`
- [`@property-read`](https://docs.phpdoc.org/guide/references/phpdoc/tags/property.html)
Used to specify what properties can be read on object that uses `__get`
- [`@property-write`](https://docs.phpdoc.org/guide/references/phpdoc/tags/property.html)
Used to specify what properties can be written on object that uses `__set`
- [`@method`](https://docs.phpdoc.org/guide/references/phpdoc/tags/method.html)
Used to specify which magic methods are available on object that uses `__call`.
- [`@deprecated`](https://docs.phpdoc.org/guide/references/phpdoc/tags/deprecated.html)
Used to mark functions, methods, classes and interfaces as being deprecated
- [`@internal`](https://docs.phpdoc.org/guide/references/phpdoc/tags/internal.html)
Used to mark classes, functions and properties that are internal to an application or library.
- [`@mixin`](#mixins)
Used to tell Psalm that the current class proxies the methods and properties of the referenced class.
### Off-label usage of the `@var` tag
The `@var` tag is supposed to only be used for properties. Psalm, taking a lead from PHPStorm and other static analysis tools, allows its use inline in the form `@var Type [VariableReference]`.
If `VariableReference` is provided, it should be of the form `$variable` or `$variable->property`. If used above an assignment, Psalm checks whether the `VariableReference` matches the variable being assigned. If they differ, Psalm will assign the `Type` to `VariableReference` and use it in the expression below.
If no `VariableReference` is given, the annotation tells Psalm that the right-hand side of the expression, whether an assignment or a return, is of type `Type`.
```php
$name(...$arguments);
}
public function __get($name)
{
(new A())->$name;
}
}
$b = new B();
$b->doB();
$b->doA(); // works
echo $b->b;
echo $b->a; // works
```
Mixins are followed transitively: if `B` mixes in `A` and `C` mixes in `B`, members of `A` are also available on `C`.
Chains are only followed through non-generic mixins; a generic hop such as `@mixin Collection` is not traversed.
## Psalm-specific tags
There are a number of custom tags that determine how Psalm treats your code.
### `@psalm-consistent-constructor`
See [UnsafeInstantiation](../running_psalm/issues/UnsafeInstantiation.md)
### `@psalm-consistent-templates`
See [UnsafeGenericInstantiation](../running_psalm/issues/UnsafeGenericInstantiation.md)
### `@param-out`, `@psalm-param-out`
This is used to specify that a by-ref type is different from the one that entered. In the function below the first param can be null, but once the function has executed the by-ref value is not null.
```php
`), `$this`, `static`, `self`, `parent`, or a class-level template parameter.
```php
call($instance)
}
}
class Builder extends Macroable {
public int $value = 42;
}
Builder::macro('grab', function (): int {
// $this is Builder here, not the outer scope
return $this->value;
});
```
Inside the callback, class scope follows the bound type: `self::` refers to that class and `parent::` to its parent. Property types retain the bound class's generic arguments rather than using the caller's property types.
The tag is ignored when it cannot name one known class to bind to (a union such as `A|B`, or a class Psalm has not seen), and when the argument is a static closure, since PHP cannot rebind one.
### `@psalm-var`, `@psalm-param`, `@psalm-return`, `@psalm-property`, `@psalm-property-read`, `@psalm-property-write`, `@psalm-method`
When specifying types in a format not supported by phpDocumentor ([but supported by Psalm](#type-syntax)) you may wish to prepend `@psalm-` to the PHPDoc tag, so as to avoid confusing your IDE. If a `@psalm`-prefixed tag is given, Psalm will use it in place of its non-prefixed counterpart.
### `@psalm-ignore-var`
This annotation is used to ignore the `@var` annotation written in the same docblock. Some IDEs don't fully understand complex types like generics. To take advantage of such IDE's auto-completion, you may sometimes want to use explicit `@var` annotations even when psalm can infer the type just fine. This weakens the effectiveness of type checking in many cases since the explicit `@var` annotation overrides the types inferred by psalm. As psalm ignores the `@var` annotation which is co-located with `@psalm-ignore-var`, IDEs can use the type specified by the `@var` for auto-completion, while psalm can still use its own inferred type for type checking.
```php
$f */
function getTimes(int $n): iterable {
while ($n--) {
yield new \DateTime();
}
};
/**
* @var \Datetime[] $times
* @psalm-ignore-var
*/
$times = getTimes(3);
// this trace shows "iterable" instead of "array"
/** @psalm-trace $times */
foreach ($times as $time) {
echo $time->format('Y-m-d H:i:s.u') . PHP_EOL;
}
```
### `@psalm-suppress SomeIssueName`
This annotation is used to suppress issues. It can be used in function docblocks, class docblocks and also inline, applying to the following statement.
Function docblock example:
```php
1 ? new Foo() : null;
}
takesFoo(getFoo());
```
### `@psalm-ignore-falsable-return`
This provides the same, but for `false`. Psalm uses this internally for functions like `preg_replace`, which can return false if the given input has encoding errors, but where 99.9% of the time the function operates as expected.
### `@psalm-seal-properties`, `@psalm-no-seal-properties`, `@seal-properties`, `@no-seal-properties`
If you have a magic property getter/setter, you can use `@psalm-seal-properties` to instruct Psalm to disallow getting and setting any properties not contained in a list of `@property` (or `@property-read`/`@property-write`) annotations.
This is automatically enabled with the configuration option `sealAllProperties` and can be disabled for a class with `@psalm-no-seal-properties`
```php
bar = 5; // this call fails
```
### `@psalm-seal-methods`, `@psalm-no-seal-methods`, `@seal-methods`, `@no-seal-methods`
If you have a magic method caller, you can use `@psalm-seal-methods` to instruct Psalm to disallow calling any methods not contained in a list of `@method` annotations.
This is automatically enabled with the configuration option `sealAllMethods` and can be disabled for a class with `@psalm-no-seal-methods`
```php
bar(); // this call fails
```
### `@psalm-internal`
Used to mark a class, property or function as internal to a given namespace or class or even method.
Psalm treats this slightly differently to the PHPDoc `@internal` tag. For `@internal`,
an issue is raised if the calling code is in a namespace completely unrelated to the namespace of the calling code,
i.e. not sharing the first element of the namespace.
In contrast for `@psalm-internal`, the docblock line must specify a namespace. An issue is raised if the calling code
is not within the given namespace.
```php
s = $s;
}
}
$b = new B("hello");
echo $b->s;
$b->s = "boo"; // disallowed
```
### Purity and capabilities
Psalm tracks the side effects a function, method or closure may have as a set of capabilities:
`read-props`, `write-this-props`, `write-props`, `read-globals`, `write-globals`, `write-refs`, `io`
and `time`, with `pure` for none of them and `impure` for all of them. [The Purity Model](purity_model.md)
explains what each capability allows, how calls are charged and how purity templates work. The
annotations are listed below.
### `@psalm-pure` and `@psalm-impure`
`@psalm-pure` on a function or method gives it no capabilities: its result depends only on its
arguments. On a class, it applies to every method and bans the use of properties. `@psalm-impure`
on a function or method gives it every capability, the default for unannotated code, written out.
See [Annotations](purity_model.md#annotations).
### `@psalm-capabilities`
`@psalm-capabilities ` on a function, method or closure gives the capabilities it may use,
separated by `|` or commas, as in `@psalm-capabilities read-props|write-this-props`. The set may be
a [type alias](purity_model.md#capability-aliases). On a class or interface, it is a
[contract](purity_model.md#class-level-contracts) for every method of the class and of the classes
extending or implementing it. See [Capabilities](purity_model.md#capabilities).
### `@psalm-immutable`
Used to annotate a class where every property is treated by consumers as `@psalm-readonly` and every instance method is treated as `@psalm-capabilities read-props` (see [Annotations](purity_model.md#annotations)).
```php
baz = $baz;
}
public function bar(): int
{
return 0;
}
}
$anonymous = new /** @psalm-immutable */ class extends Foo
{
public string $baz = "B";
public function bar(): int
{
return 1;
}
};
```
### `@psalm-mutable`
Used to annotate a class where at least one property is mutable: this is the default behavior, but it can be explicitly marked for clarity.
### `@psalm-purity-template`
`@psalm-purity-template P` on a class, function or method declares a purity template: a template
parameter whose values are capability sets rather than types. It is used as the purity of a
callable (`Closure[P](int): int`) or as the purity argument of a class (`Box[P]`,
`@extends Box[pure]`). Bounds and a default are written as a chain,
`@psalm-purity-template lower <= P(default) <= upper`, and `Closure[_](...)` in a `@param` type
declares an unnamed one. See [Purity templates](purity_model.md#purity-templates).
### Iterators and generators
`Traversable`, `Iterator`, `IteratorAggregate`, `Generator` and `iterable` have a purity template,
`TPurity`: what iterating over them may do, as in `Iterator[pure]` or
`iterable[pure]` (`impure` by default). See
[Iterators and generators](purity_model.md#iterators-and-generators).
### `@psalm-purity-from-template`
`@psalm-purity-from-template P` on a function or method: each call needs the function-like's own
capabilities plus whatever `P`, a purity template or a type template bound to a closure type, is
bound to at that call. See
[`@psalm-purity-from-template`](purity_model.md#psalm-purity-from-template).
### `@psalm-allow-private-mutation`
Used to annotate readonly properties that can be mutated in a private context. With this, public properties can be read from another class but only be mutated within a method of its own class.
```php
count++;
}
}
$counter = new Counter();
echo $counter->count; // outputs 0
$counter->increment(); // Method can mutate property
echo $counter->count; // outputs 1
$counter->count = 5; // This will fail, as it's mutating a property directly
```
### `@psalm-readonly-allow-private-mutation`
This is a shorthand for the property annotations `@readonly` and `@psalm-allow-private-mutation`.
```php
count++;
}
}
$counter = new Counter();
echo $counter->count; // outputs 0
$counter->increment(); // Method can mutate property
echo $counter->count; // outputs 1
$counter->count = 5; // This will fail, as it's mutating a property directly
```
### `@psalm-trace`
You can use this annotation to trace inferred type (applied to the *next* statement).
```php
```
### `@psalm-check-type`
You can use this annotation to ensure the inferred type matches what you expect.
```php
"Nokia"];
}
}
```
### `@psalm-import-type`
You can use this annotation to import a type defined with [`@psalm-type`](#psalm-type) if it was defined somewhere else.
```php
toArray());
}
}
```
You can also alias a type when you import it:
```php
toArray());
}
}
```
### `@psalm-require-extends`
The `@psalm-require-extends` annotation allows you to define the requirements that a trait imposes on the using class.
Psalm also reads the `@phpstan-require-extends` spelling. When a docblock has both, `@psalm-require-extends` is used.
```php
` without `@no-named-arguments` but becomes `list` with it, because it excludes the case where the offset would be a string with the name of the parameter
### `@psalm-ignore-variable-property` and `@psalm-ignore-variable-method`
Instructs Psalm to ignore variable property fetch / variable method call when looking for dead code.
```php
class Foo
{
// this property can be deleted by Psalter,
// as potential reference in get() is ignored
public string $bar = 'bar';
public function get(string $name): mixed
{
/** @psalm-ignore-variable-property */
return $this->{$name};
}
}
```
When Psalm encounters variable property, it treats all properties in given class as potentially referenced.
With `@psalm-ignore-variable-property` annotation, this reference is ignored.
While `PossiblyUnusedProperty` would be emitted in both cases, using `@psalm-ignore-variable-property`
would allow [Psalter](../manipulating_code/fixing.md) to delete `Foo::$bar`.
`@psalm-ignore-variable-method` behaves the same way, but for variable method calls.
### `@psalm-yield`
Used to specify the type of value which will be sent back to a generator when an annotated object instance is yielded.
```php
*/
class Success implements Promise {
/**
* @psalm-param TValue $value
*/
public function __construct($value) {}
}
/**
* @return Promise
*/
function fetch(): Promise {
return new Success('{"data":[]}');
}
function (): Generator {
$data = yield fetch();
// this is fine, Psalm knows that $data is a string
return json_decode($data);
};
```
This annotation supports only generic types, meaning that e.g. `@psalm-yield string` would be ignored.
### `@api`, `@psalm-api`
Used to tell Psalm that a class or method is used, even if no references to it can be
found. Unused issues will be suppressed.
For example, in frameworks, controllers are often invoked "magically" without
any explicit references to them in your code. You should mark these classes with
`@psalm-api`.
```php
/**
* @psalm-api
*/
class UnreferencedClass {}
```
When an [`Unused*` issue](../running_psalm/issues.md) is reported, there are only
two correct fix paths:
* The symbol is genuinely **public surface** — consumed from outside the
analysed codebase, e.g. a library entry point, or a class instantiated only
by a framework, container or plugin loader. Mark it with `@api`/`@psalm-api`.
Use this *only* for real public surface.
* Otherwise the symbol is **dead code** — remove it, along with anything that
was only reachable through it.
For a reported method or property, `@api` may be placed either on that member or
on the whole class, but marking the **whole class** is almost always the right
choice: an externally-consumed member belongs to an externally-consumed class,
and one class-level annotation then covers its entire public API. Conversely, if
a member is reported as unused inside a class that is *not* marked `@api`, it is
almost always genuinely dead code — remove it rather than annotating the lone
member. Annotating an individual member is only correct in the uncommon case
where the class is not public API but that one member genuinely is.
A class that implements an interface (or extends a class) defined outside the
project is treated as public surface automatically, since it can be instantiated
and invoked through that external type: its overriding methods are considered
used without an explicit `@api`.
Do not reach for `@psalm-suppress UnusedClass` (or another `Unused*`
suppression) in place of `@api`: as noted above, a suppression only silences the
report, it does not mark the symbol as used, so symbols it references may still
be reported as unused.
### `@psalm-inheritors`
Used to tell Psalm that a class can only be extended by a certain subset of classes.
For example,
```php
value = $value;
}
public function getValue() {
return $this->value;
}
}
```
When Psalm handles the return type of `$my_container->getValue()` it doesn't know what it's getting out, because the value can be arbitrary.
Templated annotations provide us with a workaround - we can define a generic/templated param `T` that is a placeholder for the value inside `MyContainer`:
```php
value = $value;
}
/** @return T */
public function getValue() {
return $this->value;
}
}
```
Now we can substitute values for that templated param when we reference `MyContainer` in docblocks e.g. `@return MyContainer`. This tells Psalm to substitute `T` for `int` when evaluating that return type, effectively treating it as a class that looks like
```php
value = $value;
}
/** @return int */
public function getValue() {
return $this->value;
}
}
```
This pattern can be used in a large number of different situations like mocking, collections, iterators and loading arbitrary objects. Psalm has a large number of annotations to make it easy to use templated types in your codebase.
## `@template`, `@psalm-template`
The `@template`/`@psalm-template` tag allows classes and functions to declare a generic type parameter.
As a very simple example, this function returns whatever is passed in:
```php
$arr
* @param array $arr2
* @return array
*/
function array_combine(array $arr, array $arr2) {}
```
### Notes
- `@template` tag order matters for class docblocks, as they dictate the order in which those generic parameters are referenced in docblocks.
- The names of your templated types (e.g. `TKey`, `TValue`) don't matter outside the scope of the class or function in which they're declared.
## @param class-string<T>
Psalm also allows you to parameterize class types
```php
$class
* @return T
*/
function instantiator(string $class) {
return new $class();
}
class Foo {
public final function __construct() {}
}
class FooChild extends Foo {}
$r = instantiator(FooChild::class);
// Psalm knows $r is an object of type FooChild
```
## Template inheritance
Psalm allows you to extend templated classes with `@extends`/`@template-extends`:
```php
*/
class ChildClass extends ParentClass {}
```
similarly you can implement interfaces with `@implements`/`@template-implements`
```php
*/
class Foo implements IFoo {}
```
and import traits with `@use`/`@template-use`
```php
*/
use MyTrait;
}
```
You can also extend one templated class with another, e.g.
```php
*/
class ChildClass extends ParentClass {}
```
## Template constraints
You can use `@template of ` to restrict input. For example, to restrict to a given class you can use
```php
*/
function makeArray($t) {
return [$t];
}
$a = makeArray(new Foo()); // typed as array
$b = makeArray(new FooChild()); // typed as array
$c = makeArray(new stdClass()); // type error
```
Templated types aren't limited to key-value pairs, and you can re-use templates across multiple arguments of a template-supporting type:
```php
*/
abstract class Foo implements IteratorAggregate {
/**
* @var int
*/
protected $rand_min;
/**
* @var int
*/
protected $rand_max;
public function __construct(int $rand_min, int $rand_max) {
$this->rand_min = $rand_min;
$this->rand_max = $rand_max;
}
/**
* @return Generator
*/
public function getIterator() : Generator {
$j = random_int($this->rand_min, $this->rand_max);
for($i = $this->rand_min; $i <= $j; $i += 1) {
yield $this->getFuzzyType($i) => $i ** $i;
}
return $this->getFuzzyType($j);
}
/**
* @return T0
*/
abstract protected function getFuzzyType(int $i);
}
/**
* @template-extends Foo
*/
class Bar extends Foo {
protected function getFuzzyType(int $i) : int {
return $i;
}
}
/**
* @template-extends Foo
*/
class Baz extends Foo {
protected function getFuzzyType(int $i) : string {
return static::class . '[' . $i . ']';
}
}
```
## Template covariance
Imagine you have code like this:
```php
*/
public array $list;
/**
* @param array $list
*/
public function __construct(array $list) {
$this->list = $list;
}
/**
* @param T $t
*/
public function add($t) : void {
$this->list[] = $t;
}
}
/**
* @param Collection $collection
*/
function addAnimal(Collection $collection) : void {
$collection->add(new Cat());
}
/**
* @param Collection $dog_collection
*/
function takesDogList(Collection $dog_collection) : void {
addAnimal($dog_collection);
}
```
That last call `addAnimal($dog_collection)` breaks the type of the collection – suddenly a collection of dogs becomes a collection of dogs _or_ cats. That is bad.
To prevent this, Psalm emits an error when calling `addAnimal($dog_collection)` saying "addAnimal expects a `Collection`, but `Collection` was passed". If you haven't encountered this rule before it's probably confusing to you – any function that accepted an `Animal` would be happy to accept a subtype thereof. But as we see in the example above, doing so can lead to problems.
But there are also times where it's perfectly safe to pass template param subtypes:
```php
*/
public array $list = [];
}
/**
* @param Collection $collection
*/
function getNoises(Collection $collection) : void {
foreach ($collection->list as $animal) {
echo $animal->getNoise();
}
}
/**
* @param Collection $dog_collection
*/
function takesDogList(Collection $dog_collection) : void {
getNoises($dog_collection);
}
```
Here we're not doing anything bad – we're just iterating over an array of objects. But Psalm still gives that same basic error – "getNoises expects a `Collection`, but `Collection` was passed".
We can tell Psalm that it's safe to pass subtypes for the templated param `T` by using the annotation `@template-covariant T` (or `@psalm-template-covariant T`):
```php
*/
public array $list = [];
}
```
Doing this for the above example produces no errors: [https://psalm.dev/r/5254af7a8b](https://psalm.dev/r/5254af7a8b)
But `@template-covariant` doesn't get rid of _all_ errors – if you add it to the first example, you get a new error – [https://psalm.dev/r/0fcd699231](https://psalm.dev/r/0fcd699231) – complaining that you're attempting to use a covariant template parameter for function input. That’s no good, as it means you're likely altering the collection somehow (which is, again, a violation).
### But what about immutability?
Psalm has [comprehensive support for declaring functional immutability](https://psalm.dev/articles/immutability-and-beyond).
If we make sure that the class is immutable, we can declare a class with an `add` method that still takes a covariant param as input, but which does not modify the collection at all, instead returning a new one:
```php
*/
public array $list = [];
/**
* @param array $list
*/
public function __construct(array $list) {
$this->list = $list;
}
/**
* @param T $t
* @return Collection
*/
public function add($t) : Collection {
return new Collection(array_merge($this->list, [$t]));
}
}
```
This is perfectly valid, and Psalm won't complain.
## Builtin templated classes and interfaces
Psalm has support for a number of builtin classes and interfaces that you can extend/implement in your own code.
- `interface Traversable`
- `interface ArrayAccess`
- `interface IteratorAggregate extends Traversable`
- `interface Iterator extends Traversable`
- `interface SeekableIterator extends Iterator`
- `class Generator extends Traversable`
- `class ArrayObject implements IteratorAggregate, ArrayAccess`
- `class ArrayIterator implements SeekableIterator, ArrayAccess`
- `class DOMNodeList implements Traversable`
- `class SplDoublyLinkedList implements Iterator, ArrayAccess`
- `class SplQueue extends SplDoublyLinkedList`
- `abstract class FilterIterator`
---
### Annotating Code Type Variables (`docs/annotating_code/type_variables.md`)
# Type Variables
A type variable is a placeholder type — rendered internally as `` `_0 ``, `` `_1 ``, … —
that stands in for a class template parameter whose concrete type is not yet known. The
idea comes from the Hack typechecker's local inference: in Hack you can write
`new Vector<_>()` and let the checker solve for the type argument from how the object is
*used*. PHP has no constructor type arguments at all, so under this model **every**
templated construction site is effectively `new Foo<_>(...)`.
## How it works
When Psalm analyzes `new Foo(...)` and `Foo` has a template `T`, it mints a fresh type
variable and makes it the object's type parameter (`Foo<`_0>`). The variable starts life
with:
- **lower bounds** — whatever the constructor arguments already implied
(`new Box(1)` seeds `` `_0 >: 1 ``); empty if nothing bound it,
- **upper bounds** — the template's declared constraint (`@template T of int|string`
seeds `` `_0 <: int|string ``), and, when the constructor names the type exactly
through a `class-string`/`T::class` parameter, the named type as a pin
(`new ReflectionClass(Foo::class)` pins `` `_0 = Foo ``).
From then on the variable flows through the function body, and every use *records a
constraint instead of passing judgment*: passing a value into a `T`-typed parameter adds
a lower bound; returning the object against a declared `Foo` adds an equality
upper bound; arithmetic adds an `int|float` upper bound; concatenation and `echo` add
`array-key`; scalar assertions like `is_int($v)` add lower bounds. The comparator treats
a type variable as compatible with anything during these checks — the verdict is
deferred.
When the surrounding function-like (or the file's global scope) finishes analysis, all
accumulated bounds for each variable are reconciled with each other; any lower bound
that cannot satisfy an upper bound produces
[IncompatibleTypeParameters](../running_psalm/issues/IncompatibleTypeParameters.md),
reported at the position where the offending bound was recorded. The constraints
`T <: int|string, T >: int` can hold together; `T = string, T >: 1` cannot — that pair
is what makes this code report "Type 1 should be a subtype of string" *at the `new`*:
```php
t = $item;
}
}
/** @return Box */
function bad(): Box {
$box = new Box(1); // IncompatibleTypeParameters: Type 1 should be a subtype of string
$box->set("two");
return $box;
}
```
## How this differs from Psalm's previous approach
Psalm's previous model was **eager pinning**. At the construction site the template was
resolved once and frozen: to the most specific type the constructor arguments implied
(`new Box(1)` ⇒ `Box<1>`), or to its declared constraint when nothing bound it
(`new IntBox()` with `T of int` ⇒ `IntBox`). Every later use was then checked
against that frozen type, argument by argument.
The practical differences:
1. **Inference direction.** Eager pinning means the constructor is the *only* place `T`
can be learned; everything after is checking. With type variables, inference runs
through the whole function body — a later `$box->add(5)` on an unbound `Box`
genuinely informs what `T` is, and `$box->get()` resolves through those accumulated
bounds instead of falling back to the constraint.
2. **Widening is legal.** Under eager pinning, `new Box(1)` pins `T = 1`, so
`$box->set('two')` was `InvalidArgument` ("expects 1, but 'two' provided") even
though `'two'` satisfies `T of int|string`. Under type variables the set call just
widens `T` toward `1|'two'`, which the constraint accepts. `T` is only ever
*required* to be something by its declared constraint, a class-string pin, or a
context that names it (a declared return/param/property type) — not by whichever
value happened to reach the constructor first.
3. **Where and how errors are reported.** Eager pinning reported a separate per-call
mismatch at each offending argument, phrased against the frozen type. Reconciliation
reports the actual contradiction between bounds, once, at the bound that cannot hold —
so a `Box` return conflicting with the constructor argument points at
`$box = new Box(1);`, which is where the wrong value actually entered. The issue is
its own type (`IncompatibleTypeParameters`, level 1), shown as INFO at normal error
levels rather than a hard error.
4. **Comparisons become provisional.** Because a type variable "matches anything while
recording a bound," any code that used a successful containment check to make a
*decision* (negated `instanceof` narrowing, rewriting hinted closure params from an
expected callable) treats variable-involving containments as non-definitive — they
record evidence for reconciliation but prove nothing on their own.
## What stays the same
- Templates with a `mixed` constraint and templates with no public mutation channel
(named only in the constructor) are never turned into type variables — there is
nothing to check, and nothing later could constrain them — so plain `@template T`
classes behave exactly as before.
- `SplObjectStorage` keeps its `never` special case for unbound templates.
- A type variable renders through its bounds, so inferred types still display as
`Box<1>` or `Foo` rather than `` `_0 ``.
- Callables validate against the construction-site inference with ordinary
`InvalidArgument` messages, since a structural signature mismatch is clearer reported
in full than deferred to reconciliation.
---
### Annotating Code Typing In Psalm (`docs/annotating_code/typing_in_psalm.md`)
# Typing in Psalm
Psalm is able to interpret all PHPDoc type annotations, and use them to further understand the codebase.
Types are used to describe acceptable values for properties, variables, function parameters and `return $x`.
## Docblock Type Syntax
Psalm allows you to express a lot of complicated type information in docblocks.
All docblock types are either [atomic types](type_syntax/atomic_types.md), [union types](type_syntax/union_types.md) or [intersection types](type_syntax/intersection_types.md).
Additionally, Psalm supports PHPDoc’s [type syntax](https://docs.phpdoc.org/guide/guides/types.html#supported-types), and also the [proposed PHPDoc PSR type syntax](https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types).
## Property declaration types vs Assignment typehints
You can use the `/** @var Type */` docblock to annotate both [property declarations](http://php.net/manual/en/language.oop5.properties.php) and to help Psalm understand variable assignment.
### Property declaration types
You can specify a particular type for a class property declaration in Psalm by using the `@var` declaration:
```php
foo = $some_variable;`, Psalm will check to see whether `$some_variable` is either `string` or `null` and, if neither, emit an issue.
If you leave off the property type docblock, Psalm will emit a `MissingPropertyType` issue.
### Assignment typehints
Consider the following code:
```php
[
0 => 'bool',
'version1' => 'string',
'version2' => 'string',
'operator' => '\'!=\'|\'<\'|\'<=\'|\'<>\'|\'=\'|\'==\'|\'>\'|\'>=\'|\'eq\'|\'ge\'|\'gt\'|\'le\'|\'lt\'|\'ne\'|null',
],
'version_compare\'1' => [
0 => 'int',
'version1' => 'string',
'version2' => 'string',
],
]
```
**Note**: the above example doesn't provide almost any useful information for type inference;
in fact, the real logic for return type inference is contained in the `VersionCompareReturnTypeProvider`.
The callmap is mainly useful when treating functions and methods as *callable values*, for example:
```php
_delta.php`)
list changes that happened in the corresponding PHP version. There are
three section with self-explanatory names: `added` (for functions/methods that
were added in that PHP version), `removed` (for those that were removed) and
`changed`.
Entry format for `removed` and `added` section matches that of a full callmap,
while `changed` entries list `old` and `new` signatures.
## How Psalm uses delta files
When the current PHP version is set to something other than the latest PHP
version supported by Psalm, it needs to process delta files to arrive at a
version of callmap matching the one that is used during analysis. Psalm uses
the following process to do that:
1. Read `CallMap.php` (Note: it's the one having the latest signatures).
2. If it matches configured PHP version, use it.
3. If the callmap delta for previous PHP version exists, read that.
4. Take previous callmap delta and apply it in reverse order. That is, entries
in `removed` section are added, those in `added` section are removed and
`changed.new` signatures in the current callamp are replaced with
`changed.old`.
5. Goto 2
## Consistent histories
To make sure there are no mismatches in deltas and the callmap, CI validates
that all function/method entries have consistent histories. E.g. that the
signature in `changed.new` matches the one in `CallMap.php`, the `removed`
entries are actually absent from `CallMap.php` and so on.
## Typical changes
To put that into practical perspective, let's see how a couple of typical
callmap changes may look like.
### Adding a new function
Say, there's a function added in PHP 8.1, e.g. `array_is_list()`. Add it to the
`CallMap_81_delta.php` (as it was introduced in PHP 8.1), and `CallMap.php` (as
it exists in the latest PHP version). Here's [the PR that does it](https://github.com/vimeo/psalm/pull/6398/files).
### Correcting the function signature
Assume you found an incorrect signature, the one that was always different to what
we currently have in Psalm. This will need a change to `CallMap.php` (as the signature is
still valid). Here's [the PR that does it](https://github.com/vimeo/psalm/pull/6359/files).
If function signature is correct for an older version but has changed since you
will need to edit the delta for PHP version where signature changed and
`CallMap.php` (as this new signature is still valid). Here's
[the PR that does it (makes `timestamp` nullable)](https://github.com/vimeo/psalm/pull/6244/files).
---
### Contributing How Psalm Works (`docs/contributing/how_psalm_works.md`)
# How Psalm works
The entry point for all analysis is [`ProjectAnalyzer`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Analyzer/ProjectAnalyzer.php)
`ProjectAnalyzer` is in charge of two things: Scanning and Analysis
## Scanning
For any file or set of files, Psalm needs to determine all the possible dependencies and get their function signatures and constants, so that the analysis phase can be done multi-threaded.
Scanning happens in `Psalm\Internal\Codebase\Scanner`.
The first task is to convert a file into a set of [PHP Parser](https://github.com/nikic/PHP-Parser) statements. PHP Parser converts PHP code into an abstract syntax tree that Psalm uses for all its analysis.
### Deep scanning vs shallow scanning
Psalm then uses a custom PHP Parser `NodeVisitor` called [`ReflectorVisitor`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/PhpVisitor/ReflectorVisitor.php) which has two modes when scanning a given file: a shallow scan, where it just gets function signatures, return types, constants, and inheritance, or a deep scan, where it drills into every function statement to get those dependencies too (e.g. the class names instantiated by a function). It only does a deep scan on files that it knows will be analysed later (so the vast majority of the vendor directory, for example, just gets a shallow scan).
So, when analysing the `src` directory, Psalm will deep scan the following file:
src/A.php
```php
`src/FileName.php` mapping it uses reflection for project files and the Composer classmap for vendor files.
### Storing data from scanning
For each file that `ReflectorVisitor` visits, Psalm creates a [`FileStorage`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Storage/FileStorage.php) instance, along with [`ClassLikeStorage`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Storage/ClassLikeStorage.php) and [`FunctionLikeStorage`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Storage/FunctionLikeStorage.php) instances depending on the file contents.
Once we have a set of all files and their classes and function signatures, we calculate inheritance for everything in the [`Populator`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Codebase/Populator.php) class and then move onto analysis.
At the end of the scanning step we have populated all the necessary information in [`ClassLikes`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Codebase/ClassLikes.php), [`Functions`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Codebase/Functions.php) and [`Methods`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Codebase/Methods.php) classes, and created a complete list of `FileStorage` and `ClassLikeStorage` objects (in [`FileStorageProvider`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Provider/FileStorageProvider.php) and [`ClassLikeStorageProvider`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Provider/ClassLikeStorageProvider.php) respectively) for all classes and files used in our project.
## Analysis
We analyse files in [`FileAnalyzer`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Analyzer/FileAnalyzer.php)
The `FileAnalyzer` takes a given file and looks for a set of top-level components: classes, traits, interfaces, functions. It can look inside namespaces and extract the classes, interfaces, traits and functions in them as well.
It delegates the analysis of those components to [`ClassAnalyzer`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Analyzer/ClassAnalyzer.php), [`InterfaceAnalyzer`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Analyzer/InterfaceAnalyzer.php) and [`FunctionAnalyzer`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Analyzer/FunctionAnalyzer.php).
Because it’s the most basic use case for the line-by-line analysis (no class inheritance to worry about), let’s drill down into `FunctionAnalyzer`.
### Function Analysis
`FunctionAnalyzer::analyze` is defined in [`FunctionLikeAnalyzer`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Analyzer/FunctionLikeAnalyzer.php). That method first gets the `FunctionLikeStorage` object for the given function that we created in our scanning step. That `FunctionLikeStorage` object has information about function parameters, which we then feed into a [`Context`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Context.php) object. The `Context` contains all the type information we know about variables & properties (stored in `Context::$vars_in_scope`) and also a whole bunch of other information that can change depending on assignments and assertions.
Somewhere in `FunctionLikeAnalyzer::analyze` we create a new [`StatementsAnalyzer`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Internal/Analyzer/StatementsAnalyzer.php) and then call its `analyze()` method, passing in a set of PhpParser nodes. `StatementAnalyzer::analyze` passes off to a number of different checkers (`IfAnalyzer`, `ForeachAnalyzer`, `ExpressionAnalyzer` etc.) for more thorough analysis.
At each line the `Context` object may or may not be manipulated. At branching points (if statements, loops, ternary etc) the `Context` object is cloned and then, at the end of the branch, Psalm figures out how to resolve the changes and update the uncloned `Context` object.
The `NodeDataProvider` stores a type for each PhpParser node.
After all the statements have been analysed we gather up all the return types and compare them to the given return type.
### Type Reconciliation
While some updates to the `Context` object are straightforward, others are not. Updating the `Context` object in the light of new type information happens in [`Reconciler`](https://github.com/vimeo/psalm/blob/master/src/Psalm/Type/Reconciler.php), which takes an array assertions e.g. `[“$a” => “!null”]` and a list of existing type information e.g. `$a => string|null` and return a set of updated information e.g. `$a => string`
---
### Contributing Philosophy (`docs/contributing/philosophy.md`)
# Philosophy
This is about why Psalm is the way it is. This is a living document!
## Psalm is a tool for PHP written in PHP
### Advantages
- PHP is fast enough for most use-cases
- Writing the tool in PHP guarantees that PHP community members can contribute to it without too much difficulty
### Drawbacks
- Psalm is slow in very large monorepos (over 5 million lines of checked-in code).
- Psalm’s language server is more limited in what it can provide than comparable compiled-language tools. For example, it's infeasible to find/change all occurrences of a symbol, in all files that use it, as you type.
### Comparison to other languages & tools
Many languages have typecheckers/compilers written in the same language. Popular examples include Go, Rust, and TypeScript. Python is a special case where the semi-official typechecker [MyPy](https://github.com/python/mypy) (written in Python) can also [compile to a C Python extension](https://github.com/python/mypy/blame/master/mypyc/README.md#L6-L10), which runs 4x faster than the interpreted equivalent.
Some interpreted languages have unofficial open-source typecheckers written in faster compiled languages. In all cases a single mid-to-large company is behind each effort, with a small number of contributors not employed by that company:
- PHP
- [NoVerify](https://github.com/VKCOM/noverify) – written in Go. Runs much faster than Psalm (but does not support many modern PHP features)
- Ruby
- [Sorbet](https://sorbet.org/) - written in C
- Python
- [Pyre](https://github.com/facebook/pyre-check) - written in OCaml
- [Hack](https://github.com/facebook/hhvm) - the typechecker is written in OCaml and Rust
## Psalm's primary purpose is finding bugs
Psalm does a lot, but people mainly use it to find potential bugs in their code.
All other functionality – the language server, security analysis, manipulating/fixing code is a secondary concern.
## It's designed to be run on syntactically-correct code
Psalm is almost always run on PHP code that parses a lint check (`php -l `) – i.e. syntactically-correct code. Psalm is not a replacement for that syntax check.
Given Psalm is almost always used on syntactically-correct code it should use a parser built for that purpose, and `nikic/php-parser` is the gold-standard.
Where Psalm needs to run on syntactically-incorrect code (e.g. in language server mode) Psalm should still use the same parser (and work around any issues that it produces).
## Docblock annotations are better than type-providing plugins
Psalm offers a plugin API that allows you to tell it what about your program's property types, return types and parameter types.
Psalm aims to operate in a space with other static analysis tools. The more users rely on plugins, the less chance those other tools have to understand the user's intent.
Psalm should encourage developers to use docblock annotations rather than type-providing plugins. This was a driving force in the adoption of [Conditional Types](../annotating_code/type_syntax/conditional_types.md) which allowed Psalm to replace some of its own internal type-providing plugins.
The other benefit to docblock annotations is verifiability – for the most part Psalm is able to verify that docblock annotations are correct, but it cannot provide many assurances when plugins are used.
This doesn’t mean that plugins as a whole are bad, or that they can’t provide useful types. A great adjacent use of plugins is to provide stubs with Psalm type annotations for libraries that don’t have them. This helps the PHP ecosystem because those stubs may eventually make their way into the project currently being stubbed.
## Docblock annotations that can be verified are better than those that cannot
Psalm currently supports a number of function/class docblock annotations that it's unable to verify:
- `@psalm-assert`, `@psalm-assert-if-true`, `@psalm-assert-if-false`
- `@property`, `@method`, `@mixin`
Whenever new docblock annotations are added, effort should be made to allow Psalm to verify their correctness.
## In certain circumstances docblock annotations are better than PHP 8 attributes
For information that's just designed to be consumed by static analysis tools, docblocks are a better home than PHP 8 attributes.
A rationale is provided in [this article](https://psalm.dev/articles/php-8-attributes).
---
### Contributing What Makes Psalm Complicated (`docs/contributing/what_makes_psalm_complicated.md`)
# Things that make developing Psalm complicated
This is a somewhat informal list that might aid others.
## Type inference
Type inference is one of the big things Psalm does. It tries to figure out what different PHP elements (function calls, if/for/foreach statements etc.) mean for the data in your code.
Within type inference there are a number of tricky areas:
#### Loops
Loops are hard to reason about - break and continue are a pain. This analysis mainly takes place in `LoopAnalyzer`
#### Combining types
There are lots of edge-cases when combining types together, given the many types Psalm supports. Type combining occurs in `TypeCombiner`.
#### Logical assertions
What effect do different PHP elements have on user-asserted logic in if conditionals, ternarys etc. This logic is spread between a number of different classes.
#### Generics & Templated code
Figuring out how templated code should work (`@template` tags) and how much it should work like it does in other languages (Hack, TypeScript etc.) is tricky. Psalm also supports things like nested templates (`@template T1 of T2`) which makes things trickier
## Detecting dead code
Detecting unused variables requires some fun [data-flow analysis](https://psalm.dev/articles/better-unused-variable-detection).
Detecting unused classes and methods between different runs requires maintaining references to those classes in cache (see below).
## Supporting the community
- **Supporting formal PHPDoc annotations**
- **Supporting informal PHPDoc annotations**
e.g. `ArrayIterator|string[]` to denote an `ArrayIterator` over strings
- **non-Composer projects**
e.g. WordPress
## Making Psalm fast
#### Parser-based reflection
Requires scanning everything necessary for analysis
#### Forking processes** (non-windows)
Mostly handled by code borrowed from Phan, but can introduce subtle issues, also requires to think about how to make work happen in processes
#### Caching thing
see below
## Cache invalidation
#### Invalidating analysis results
Requires tracking what methods/properties are used in what other files, and invalidating those results when linked methods change
#### Partial parsing
Reparsing bits of files that have changed, which is hard
## Language Server Support
#### Handling temporary file changes
When files change Psalm figures out what's changed within them to avoid re-analysing things unnecessarily
#### Dealing with malformed PHP code
When people write code, it's not always pretty as they write it. A language server needs to deal with that bad code somehow
## Fixing code with Psalter
#### Adding/replacing code
Figuring out what changed, making edits that could have been made by a human
#### Minimal diffs
hard to change more than you need
---
### Manipulating Code Fixing (`docs/manipulating_code/fixing.md`)
# Fixing Code
Psalm is good at finding potential issues in large codebases, but once found, it can be something of a gargantuan task to fix all the issues.
It comes with a tool, called Psalter, that helps you fix code.
You can either run it via its binary
```
vendor/bin/psalter [args]
```
or via Psalm's binary:
```
vendor/bin/psalm --alter [args]
```
## Safety features
Updating code is inherently risky, doing so automatically is even more so. I've added a few features to make it a little more reassuring:
- To see what changes Psalter will make ahead of time, you can run it with `--dry-run`.
- You can target particular versions of PHP via `--php-version`, so that (for example) you don't add nullable typehints to PHP 7.0 code, or any typehints at all to PHP 5.6 code. `--php-version` defaults to your current version.
- it has a `--safe-types` mode that will only update PHP 7 return typehints with information Psalm has gathered from non-docblock sources of type information (e.g. typehinted params, `instanceof` checks, other return typehints etc.)
- using `--allow-backwards-incompatible-changes=false` you can make sure to not create backwards incompatible changes
## Plugins
You can pass in your own manipulation plugins e.g.
```bash
vendor/bin/psalter --plugin=vendor/vimeo/psalm/examples/plugins/ClassUnqualifier.php --dry-run
```
The above example plugin converts all unnecessarily qualified classnames in your code to shorter aliased versions.
## Supported fixes
This initial release provides support for the following alterations, corresponding to the names of issues Psalm finds.
To fix all of these at once, run `vendor/bin/psalter --issues=all`
### MissingReturnType
Running `vendor/bin/psalter --issues=MissingReturnType --php-version=7.0` on
```php
foo = 5;
} else {
$this->foo = "hello";
}
$this->bar = "baz";
}
public function setBaz() {
$this->baz = [1, 2, 3];
}
}
```
gives
```php
|null
* @psalm-var non-empty-list|null
*/
public $baz;
public function __construct()
{
if (rand(0, 1)) {
$this->foo = 5;
} else {
$this->foo = "hello";
}
$this->bar = "baz";
}
public function setBaz() {
$this->baz = [1, 2, 3];
}
}
```
### MismatchingDocblockParamType
Given
```php
```
## Using custom plugin
Plugins can register their own custom scanner and analyzer implementations for particular file extensions.
```php
addFileTypeScanner('phpt', TemplateScanner::class);
$fileExtensions->addFileTypeAnalyzer('phpt', TemplateAnalyzer::class);
}
}
```
---
### Running Psalm Command Line Usage (`docs/running_psalm/command_line_usage.md`)
# Running Psalm
Once you've set up your config file, you can run Psalm from your project's root directory with
```bash
./vendor/bin/psalm
```
and Psalm will scan all files in the project referenced by ``.
If you want to run on specific files, use
```bash
./vendor/bin/psalm file1.php [file2.php...]
```
## Command-line options
Run with `--help` to see a list of options that Psalm supports.
## Exit status
Psalm exits with status `0` when it successfully completed and found no issues,
`1` when there was a problem running Psalm and `2` when it completed
successfully but found some issues. Any exit status apart from those indicate
some internal problem.
## Shepherd
Psalm currently offers some GitHub integration with public projects.
Add `--shepherd` to send information about your build to https://shepherd.dev.
Currently, Shepherd tracks type coverage (the percentage of types Psalm can infer) on `master` branches.
## Running Psalm faster
To run Psalm up to 50% faster, use the [official docker image](https://psalm.dev/docs/running_psalm/installation/#docker-image).
Psalm also has a couple of command-line options that will result in faster builds:
- `--threads=[n]` to run Psalm’s analysis in a number of threads
- `--diff` which only checks files you’ve updated since the last run (and their dependents).
In Psalm 4 `--diff` is turned on by default (you can disable it with `--no-diff`).
Data from the last run is stored in the *cache directory*, which may be set in [configuration](./configuration.md).
If you are running Psalm on a build server, you may want to configure the server to ensure that the cache directory
is preserved between runs.
Running them together (e.g. `--threads=8 --diff`) will result in the fastest possible Psalm run.
## Reviewing issues in your IDE of choice
Psalm now offers a `psalm-review` tool which allows you to manually review issues one by one in your favorite IDE.
```bash
./vendor/bin/psalm-review report.json [code|phpstorm|code-server] [ inv|rev|[~-]IssueType1 ] [ [~-]IssueType2 ] ...
```
The tool may also be run using the main `psalm` entry point, useful for example when working with the phar:
```bash
./vendor/bin/psalm.phar --review report.json [code|phpstorm|code-server] [ inv|rev|[~-]IssueType1 ] [ [~-]IssueType2 ] ...
```
`psalm-review` parses the Psalm JSON report in report.json (generated using `vendor/bin/psalm --report=report.json`) and opens the specified IDE at the line and column of the issue, one by one for all issues; press enter to go to the next issue, `q` to quit.
The IDE argument is optional when running inside a supported IDE's integrated terminal — PhpStorm, VS Code, and code-server are auto-detected via environment variables. When running from an external terminal, the IDE must be specified explicitly.
The extra arguments may be used to filter only for issues of the specified types, or for all issues except the specified types (with the `~` or `-` inversion).
The `rev` or `inv` keywords may be used to start from the end of the report instead of at the beginning.
---
### Running Psalm Configuration (`docs/running_psalm/configuration.md`)
# Configuration
Psalm uses an XML config file (by default, `psalm.xml`). A barebones example looks like this:
```xml
```
Configuration file may be split into several files using [XInclude](https://www.w3.org/TR/xinclude/) tags (c.f. previous example):
#### psalm.xml
```xml
```
#### files.xml
```xml
```
## Different configuration file
You can also create a different configuration file, then run Psalm with:
```bash
vendor/bin/psalm --config=other-psalm-config.xml
```
## Optional <psalm /> attributes
### Coding style
#### errorLevel
```xml
```
This corresponds to Psalm‘s [error-detection level](error_levels.md).
#### reportMixedIssues
```xml
```
Setting this to `"false"` hides all issues with `Mixed` types in Psalm’s output. If not given, this defaults to `"false"` when `errorLevel` is 3 or higher, and `"true"` when the error level is 1 or 2.
#### totallyTyped
\(Deprecated\) This setting has been replaced by `reportMixedIssues` which is automatically enabled when `errorLevel` is 1.
#### resolveFromConfigFile
```xml
```
If this is enabled, relative directories mentioned in the config file will be resolved relative to the location
of the config file. If it is disabled, or absent they will be resolved relative to the working directory of the Psalm process.
New versions of Psalm enable this option when generating config files. Older versions did not include it.
#### useDocblockTypes
```xml
```
Whether or not to use types as defined in docblocks. Defaults to `true`.
#### useDocblockPropertyTypes
```xml
```
If not using all docblock types, you can still use docblock property types. Defaults to `false` (though only relevant if `useDocblockTypes` is `false`).
#### docblockPropertyTypesSealProperties
```xml
```
Whether using @property in class docblocks should imply @psalm-seal-properties. Defaults to `true`.
#### usePhpDocMethodsWithoutMagicCall
```xml
```
The PHPDoc `@method` annotation normally only applies to classes with a `__call` method. Setting this to `true` allows you to use the `@method` annotation to override inherited method return types. Defaults to `false`.
#### usePhpDocPropertiesWithoutMagicCall
```xml
```
The PHPDoc `@property`, `@property-read` and `@property-write` annotations normally only apply to classes with `__get`/`__set` methods. Setting this to `true` allows you to use the `@property`, `@property-read` and `@property-write` annotations to override property existence checks and resulting property types. Defaults to `false`.
#### disableVarParsing
```xml
```
Disables parsing of `@var` PHPDocs everywhere except for properties. Setting this to `true` can remove many false positives due to outdated `@var` annotations, used before integrations of Psalm generics and proper typing, enforcing Single Source Of Truth principles. Defaults to `false`.
#### strictBinaryOperands
```xml
```
If true we force strict typing on numerical and string operations (see https://github.com/vimeo/psalm/issues/24). Defaults to `true`.
#### allowBoolToLiteralBoolComparison
```xml
```
If false, disallows comparing a boolean to a literal boolean (mostly a codestyle rule, not a bug detection rule; see [RedundantIdentityWithTrue](https://psalm.dev/docs/running_psalm/issues/RedundantIdentityWithTrue/)). Defaults to `true`.
#### rememberPropertyAssignmentsAfterCall
```xml
```
Setting this to `false` means that function calls will cause Psalm to forget what it knew about object properties within the scope of the function it's currently analysing, unless the callee can't write them (see [property refinements after calls](../annotating_code/purity_model.md#property-refinements-after-calls)). This duplicates functionality that Hack has. Defaults to `true`.
#### allowStringToStandInForClass
```xml
```
When `true`, strings can be used as classes, meaning `$some_string::someMethod()` is allowed. If `false`, only class constant strings (of the form `Foo\Bar::class`) can stand in for classes, otherwise an `InvalidStringClass` issue is emitted. Defaults to `false`.
#### disableSuppressAll
```xml
```
When `true`, disables wildcard suppression of all issues with `@psalm-suppress all`. Defaults to `true`.
#### memoizeMethodCallResults
```xml
```
When `true`, the results of method calls without arguments passed are remembered between repeated calls of that method on a given object. Defaults to `false`.
#### hoistConstants
```xml
```
When `true`, constants defined in a function in a file are assumed to be available when requiring that file, and not just when calling that function. Defaults to `false` (i.e. constants defined in functions will *only* be available for use when that function is called)
#### addParamDefaultToDocblockType
```xml
```
Occasionally a param default will not match up with the docblock type. By default, Psalm emits an issue. Setting this flag to `true` causes it to expand the param type to include the param default. Defaults to `false`.
#### checkForThrowsDocblock
```xml
```
When `true`, Psalm will check that the developer has supplied `@throws` docblocks for every exception thrown in a given function or method. Defaults to `false`.
#### checkForThrowsInGlobalScope
```xml
```
When `true`, Psalm will check that the developer has caught every exception in global scope. Defaults to `false`.
#### ignoreInternalFunctionFalseReturn
```xml
```
When `true`, Psalm ignores possibly-false issues stemming from return values of internal functions (like `preg_split`) that may return false, but do so rarely. Defaults to `false`.
#### ignoreInternalFunctionNullReturn
```xml
```
When `true`, Psalm ignores possibly-null issues stemming from return values of internal array functions (like `current`) that may return null, but do so rarely. Defaults to `false`.
#### inferPropertyTypesFromConstructor
```xml
```
When `true`, Psalm infers property types from assignments seen in straightforward constructors. Defaults to `true`.
#### findUnusedVariablesAndParams
```xml
```
When `true`, Psalm will attempt to find all unused variables, the equivalent of running with `--find-unused-variables`. Defaults to `false`.
#### findUnusedCode
```xml
```
When `true`, Psalm will attempt to find all unused code (including unused variables), the equivalent of running with `--find-unused-code`. Defaults to `true`.
Unused-code detection is based on a graph of references between code elements, resolved by reachability from the program's entry points (the public API, top-level code, free functions, and code outside of the project directories). As a result, a class, method, property or constant that is referenced only by other unused code — including cycles of otherwise unreferenced code — is reported as unused. Suppressing an unused-code issue (e.g. `@psalm-suppress UnusedClass`) only silences the report for that symbol; it does not turn the symbol into an entry point, so code that only it references is still reported.
This is enabled by default since Psalm 6, so unused code issues are reported even without passing `--find-unused-code` (or `--find-dead-code`). Set `findUnusedCode="false"` to turn it off.
#### forceJit
```xml
```
When `true`, Psalm will enable JIT acceleration and exit immediately if it cannot be enabled, the equivalent of running with `--force-jit`. When `false` (default), Psalm runs without JIT.
#### noCache
```xml
```
When `true`, Psalm will disable usage of the cache, the equivalent of running with `--no-cache`. Defaults to `false`.
#### arrayCache
```xml
```
When `false`, Psalm will disable usage of the array cache.
The array cache is used together with the file cache to avoid re-loading cache entries when re-scanning the same file, which offers a nice performance improvement.
Defaults to `true`.
#### disallowLiteralKeysOnUnshapedArrays
```xml
```
When `true`, Psalm will emit issues when using literal keys on unshaped arrays (useful to enforce usage of shaped arrays). Defaults to `false`.
#### allFunctionsGlobal
```xml
```
When `true`, Psalm will treat all functions declared in scanned files as available to all files, even if they aren't loaded by the Composer autoloader (useful for legacy codebases which make heavy use of `require`/`include`, instead of Composer's autoloader). Defaults to `false`.
#### allConstantsGlobal
```xml
```
When `true`, Psalm will treat all constants declared in scanned files as available to all files, even if they aren't loaded by the Composer autoloader (useful for legacy codebases which make heavy use of `require`/`include`, instead of Composer's autoloader). Defaults to `false`.
#### findUnusedPsalmSuppress
```xml
```
When `true`, Psalm will report all `@psalm-suppress` annotations that aren't used, the equivalent of running with `--find-unused-psalm-suppress`. Defaults to `false`.
#### ensureArrayStringOffsetsExist
```xml
```
When `true`, Psalm will complain when referencing an explicit string offset on an array e.g. `$arr['foo']` without a user first asserting that it exists (either via an `isset` check or via an object-like array). Defaults to `false`.
#### ensureArrayIntOffsetsExist
```xml
```
When `true`, Psalm will complain when referencing an explicit integer offset on an array e.g. `$arr[7]` without a user first asserting that it exists (either via an `isset` check or via an object-like array). Defaults to `false`.
#### ensureOverrideAttribute
```xml
```
When `true`, Psalm will report class and interface methods that override a method on a parent, but do not have an `Override` attribute. Defaults to `true`.
#### phpVersion
```xml
```
Set the php version Psalm should assume when checking and/or fixing the project. If this attribute is not set, Psalm uses the declaration in `composer.json` if one is present. It will check against the earliest version of PHP that satisfies the declared `php` dependency
This can be overridden on the command-line using the `--php-version=` flag which takes the highest precedence over both the `phpVersion` setting and the version derived from `composer.json`.
#### skipChecksOnUnresolvableIncludes
```xml
```
When `true`, Psalm will skip checking classes, variables and functions after it comes across an `include` or `require` it cannot resolve. This allows code to reference functions and classes unknown to Psalm.
This defaults to `false`.
#### sealAllMethods
```xml
```
When `true`, Psalm will treat all classes as if they had sealed methods, meaning that if you implement the magic method `__call`, you also have to add `@method` for each magic method. Defaults to true.
#### sealAllProperties
```xml
```
When `true`, Psalm will treat all classes as if they had sealed properties, meaning that Psalm will disallow getting and setting any properties not contained in a list of `@property` (or `@property-read`/`@property-write`) annotations and not explicitly defined as a `property`. Defaults to true.
#### runTaintAnalysis
```xml
```
When `true` (the default), Psalm will run [Taint Analysis](../security_analysis/index.md) on your codebase. This config is the same as if you were running Psalm with `--taint-analysis`.
#### reportInfo
```xml
```
When `false`, Psalm will not consider issue at lower level than `errorLevel` as `info` (they will be suppressed instead). This can be a big improvement in analysis time for big projects. However, this config will prevent Psalm to count or suggest fixes for suppressed issue
#### allowNamedArgumentCalls
```xml
```
When `false`, Psalm will not report `ParamNameMismatch` issues in your code anymore. This does not replace the use of individual `@no-named-arguments` to prevent external access to a library's method or to reduce the type to a `list` when using variadics
#### triggerErrorExits
```xml
```
Describe the behavior of trigger_error. `always` means it always exits, `never` means it never exits, `default` means it exits only for `E_USER_ERROR`. Default is `default`
### Running Psalm
#### autoloader
```xml
```
If your application registers one or more custom autoloaders, and/or declares universal constants/functions, this autoloader script will be executed by Psalm before scanning starts. Psalm always registers composer's autoloader by default.
#### throwExceptionOnError
```xml
```
Useful in testing, this makes Psalm throw a regular-old exception when it encounters an error. Defaults to `false`.
#### hideExternalErrors
```xml
```
Whether or not to show issues in files that are used by your project files, but which are not included in ``. Defaults to `false`.
#### hideAllErrorsExceptPassedFiles
```xml
```
Whether or not to report issues only for files that were passed explicitly as arguments in CLI. This means any files that are loaded with require/include will not report either, if not set in CLI. Useful if you want to only check errors in a single or selected files. Defaults to `false`.
#### cacheDirectory
```xml
```
The directory used to store Psalm's cache data - if you specify one (and it does not already exist), its parent directory must already exist, otherwise Psalm will throw an error.
Defaults to `$XDG_CACHE_HOME/psalm`. If `$XDG_CACHE_HOME` is either not set or empty, a default equal to `$HOME/.cache/psalm` is used or `sys_get_temp_dir() . '/psalm'` when not defined.
#### allowFileIncludes
```xml
```
Whether or not to allow `require`/`include` calls in your PHP. Defaults to `true`.
#### ignoreIncludeSideEffects
```xml
```
Whether or not to ignore side effects of includes.
Ignoring include side effects can significantly speed up scans on legacy codebases, but changes to variables or variables defined inside of included files will not be visible to Psalm (functions, constants and classes will still be visible anyway, especially if the hoistConstants, allConstantsGlobal, allFunctionsGlobal configuration parameters are set to true).
Defaults to `false`.
#### respectIncludeOnce
```xml
```
Whether or not to process files after the first `require_once()` or `include_once()` call.
By default, Psalm treats `require_once()` and `include_once()` calls as if they were `require()` or `include()` calls in an attempt to consider all possible permutations of file include order. Respecting `require_once()` and `include_once()` behavior can significantly speed up scans on codebases with circular `require_once()` or `include_once()` calls. While potentially less comprehensive, this setting aims to more closely mimic PHP's runtime behavior.
Defaults to `false`.
#### serializer
```xml
```
Allows you to hard-code a serializer for Psalm to use when caching data. By default, Psalm uses `ext-igbinary` *if* the version is greater than or equal to 2.0.5, otherwise it defaults to PHP's built-in serializer.
#### compressor
```xml
```
Allows you to hard-code a compressor for Psalm's cache. By default, Psalm uses `ext-zlib` deflate, if it's enabled.
#### threads
```xml
```
Allows you to hard-code the number of threads Psalm will use (similar to `--threads` on the command line). This value will be used in place of detecting threads from the host machine, but will be overridden by using `--threads` or `--debug` (which sets threads to 1) on the command line
#### scanThreads
```xml
```
Allows you to hard-code the number of threads Psalm will use during the scan phase (as opposed to the analysis phase, controlled by the `threads` field) (similar to `--scan-threads` on the command line). This value will be used in place of detecting threads from the host machine, but will be overridden by using `--scan-threads`, `--threads` or `--debug` (which sets threads to 1) on the command line.
#### maxStringLength
```xml
```
This setting controls the maximum length of literal strings that will be transformed into a literal string type during Psalm analysis.
Strings longer than this value (by default 1000 bytes) will be transformed in a generic `non-empty-string` type, instead.
Please note that changing this setting might introduce unwanted side effects and those side effects won't be considered as bugs.
#### maxShapedArraySize
```xml
```
This setting controls the maximum size of shaped arrays that will be transformed into a shaped `array{key1: "value", key2: T}` type during Psalm analysis.
Arrays bigger than this value (100 by default) will be transformed in a generic `non-empty-array` type, instead.
Please note that changing this setting might introduce unwanted side effects and those side effects won't be considered as bugs.
#### longScanWarning
```xml
```
Specifies the maximum scan and analysis duration for individual files; files which take longer than the specified amount of seconds (as a floating point, so values smaller than one second are also accepted) will print out a warning to CLI (the scan will **not** be interrupted).
Only used in multithreaded mode, defaults to 10 seconds.
#### restrictReturnTypes
```xml
```
Emits `LessSpecificReturnType` when the declared return type is not as tight as
the inferred return type.
This code:
```php
function getOne(): int // declared type: int
{
return 1; // inferred type: 1 (int literal)
}
```
Will give this error: `LessSpecificReturnType - The inferred return type '1' for
getOne is more specific than the declared return type 'int'`
To fix the error, you should specify the more specific type in the doc-block:
```php
/**
* @return 1
*/
function getOne(): int
{
return 1;
}
```
**Warning**: Forcing a tighter type is not always the best course of action and
may cause unexpected results. The following code is invalid with
`restrictReturnTypes="true"`:
```php
class StandardCar {
/**
* @return list{'motor', 'brakes', 'wheels'}
*/
public function getSystems(): array {
return ['motor', 'brakes', 'wheels'];
}
}
class PremiumCar extends StandardCar {
/**
* @return list{'motor', 'brakes', 'wheels', 'rear parking sensor'}
*/
public function getSystems(): array {
return ['motor', 'brakes', 'wheels', 'rear parking sensor'];
}
}
```
`ImplementedReturnTypeMismatch - The inherited return type 'list{'motor', 'brakes', 'wheels'}' for StandardCar::getSystems is different to the implemented return type for PremiumCar::getsystems 'list{'motor', 'brakes', 'wheels', 'rear parking sensor'}'`
#### findUnusedBaselineEntry
Emits [UnusedBaselineEntry](issues/UnusedBaselineEntry.md) when a baseline entry
is not being used to suppress an issue. Defaults to `true`.
#### findUnusedIssueHandlerSuppression
Emits [UnusedIssueHandlerSuppression](issues/UnusedIssueHandlerSuppression.md) when a suppressed issue handler
is not being used to suppress an issue. Defaults to `true`.
## Project settings
#### <projectFiles>
Contains a list of all the directories that Psalm should inspect. You can also specify a set of files and folders to ignore with the `` directive. By default, ignored files/folders are required to exist. An `allowMissingFiles` attribute can be added for ignored files/folders than may or may not exist.
```xml
```
#### <extraFiles>
Optional. Same format as ``. Directories Psalm should load but not inspect.
#### <fileExtensions>
Optional. A list of extensions to search over. See [Checking non-PHP files](checking_non_php_files.md) to understand how to extend this.
#### <enableExtensions>
Optional. A list of extensions to enable. By default, only extensions required by your composer.json will be enabled.
```xml
```
#### <disableExtensions>
Optional. A list of extensions to disable. By default, only extensions required by your composer.json will be enabled.
```xml
```
#### <plugins>
Optional. A list of `` entries. See the [Plugins](plugins/using_plugins.md) section for more information.
#### <issueHandlers>
Optional. If you don't want Psalm to complain about every single issue it finds, the issueHandler tag allows you to configure that. [Dealing with code issues](dealing_with_code_issues.md) tells you more.
#### <unsuppressibleIssues>
Optional. A list of issues that can't be suppressed: Psalm reports them as errors whatever `@psalm-suppress`, ``, the [error level](error_levels.md), `reportMixedIssues` and the baseline say.
```xml
```
An entry names an issue, or a class or interface several issues extend, which makes all of them unsuppressible: `TaintedInput` for every taint issue, `MixedIssue` for every `Mixed*` issue, `ClassIssue`, `MethodIssue`, `PropertyIssue`, `ArgumentIssue`, `FunctionIssue`, `ClassConstantIssue`, `VariableIssue`, `PluginIssue` for every issue of a plugin, or `CodeIssue` for every issue. An issue of a plugin is named by the fully qualified name of its class.
Taint issues can only be suppressed in docblocks all at once, with `@psalm-suppress TaintedInput`, which stops tracking taints in the function or the statement it annotates: if any taint issue is unsuppressible, it doesn't, and every taint issue found there is reported.
The issues are still only reported in the files of `` that aren't ignored. A `@psalm-suppress` of an unsuppressible issue is never used, so [findUnusedPsalmSuppress](#findunusedpsalmsuppress) reports it, and a baseline entry for one is never used either: `--set-baseline` and `--update-baseline` leave them out, and [findUnusedBaselineEntry](#findunusedbaselineentry) reports those of an existing baseline.
#### <mockClasses>
Optional. Do you use mock classes in your tests? If you want Psalm to ignore them when checking files, include a fully-qualified path to the class with ``
#### <universalObjectCrates>
Optional. Do you have objects with properties that cannot be determined statically? If you want Psalm to treat all properties on a given classlike as mixed, include a fully-qualified path to the class with ``. By default, `stdClass` and `SimpleXMLElement` are configured to be universal object crates.
#### <stubs>
Optional. If your codebase uses classes and functions that are not visible to Psalm via reflection
(e.g. if there are internal packages that your codebase relies on that are not available on the machine running Psalm),
you can use stub files. Used by PhpStorm (a popular IDE) and others, stubs provide a description of classes and
functions without the implementations.
You can find a list of stubs for common classes [here](https://github.com/JetBrains/phpstorm-stubs).
List out each file with ``. In case classes to be tested use parent classes
or interfaces defined in a stub file, this stub should be configured with attribute `preloadClasses="true"`.
```xml
```
Stubs aren't analyzed, but the issues of their docblocks (e.g. `InvalidDocblock`) are reported, also for the stubs
plugins add, so that an annotation a stub gets wrong isn't silently dropped.
Note: some extension stubs are already built into Psalm, and can be enabled by requiring the extension in your `composer.json` or by using the [enableExtensions](https://psalm.dev/docs/running_psalm/configuration/#enableextensions) config key.
#### <ignoreExceptions>
Optional. A list of exceptions to not report for `checkForThrowsDocblock` or `checkForThrowsInGlobalScope`. The `class` tag will make Psalm ignore only instances of the specified class, while `classAndDescendants` will make Psalm also ignore subclasses. If an exception has `onlyGlobalScope` set to `true`, only `checkForThrowsInGlobalScope` is ignored for that exception, e.g.
```xml
```
#### <globals>
Optional. If your codebase uses global variables that are accessed with the `global` keyword, you can declare their type. e.g.
```xml
```
Some frameworks and libraries expose functionalities through e.g. `$GLOBALS[DB]->query($query)`.
The following configuration declares custom types for super-globals (`$GLOBALS`, `$_GET`, ...).
```xml
```
The example above declares global variables as shown below
- `$GLOBALS`
- `DB` of type `MyVendor\DatabaseConnection`
- `VIEW` of type `MyVendor\TemplateView`
- `$_GET`
- `data` e.g. like `["id" => "123", "title" => "Nice"]`
#### <forbiddenFunctions>
Optional. Allows you to specify a list of functions that should emit the [`ForbiddenCode`](issues/ForbiddenCode.md) issue type.
```xml
```
#### <forbiddenConstants>
Optional. Allows you to specify a list of constants that should emit the [`ForbiddenCode`](issues/ForbiddenCode.md) issue type.
```xml
```
#### <taintAnalysis>
Optional. Settings of the [security analysis](../security_analysis/index.md):
- ``: the files and directories whose taint paths are not reported (see
[Avoiding files in taint paths](../security_analysis/avoiding_false_positives.md#avoiding-files-in-taint-paths)).
- ``: custom taints, which the annotations can then name without a plugin registering them. Each can be added
to aliases of built-in taints (`input`, `tainted`, `input_except_sleep`) with ``: a taint added to `input` is
user input, which the built-in sources give (see
[Custom taints declared in the configuration](../security_analysis/custom_taint_sources.md#custom-taints-declared-in-the-configuration)).
```xml
```
## Accessing Psalm configuration in plugins
Plugins can access or modify the global configuration in plugins using
[singleton Psalm\Config](https://github.com/vimeo/psalm/blob/master/src/Psalm/Config.php).
```php
$config = \Psalm\Config::getInstance();
if (!isset($config->globals['$GLOBALS'])) {
$config->globals['$GLOBALS'] = 'array{data: array}';
}
```
---
### Running Psalm Dealing With Code Issues (`docs/running_psalm/dealing_with_code_issues.md`)
# Dealing with code issues
Psalm has a large number of [code issues](issues.md). Each project can specify its own reporting level for a given issue.
Code issue levels in Psalm fall into three categories:
- `error`
This will cause Psalm to print a message, and to ultimately terminate with a non-zero exit status
- `info`
This will cause Psalm to print a message
- `suppress`
This will cause Psalm to ignore the code issue entirely
The third category, `suppress`, is the one you will probably be most interested in, especially when introducing Psalm to a large codebase.
## Suppressing issues
There are two ways to suppress an issue – via the Psalm config or via a function docblock.
### Config suppression
You can use the `` tag in the config file to influence how issues are treated.
Some issue types allow the use of `referencedMethod`, `referencedClass` or `referencedVariable` to isolate known trouble spots.
```xml
```
### Docblock suppression
You can also use `@psalm-suppress IssueName` on a function's docblock to suppress Psalm issues e.g.
```php
`](configuration.md#unsuppressibleissues) can't be suppressed, neither this way nor with `` or a baseline.
## Using a baseline file
If you have a bunch of errors and you don't want to fix them all at once, Psalm can grandfather-in errors in existing code, while ensuring that new code doesn't have those same sorts of errors.
```
vendor/bin/psalm --set-baseline
```
will generate a file `psalm-baseline.xml` containing the current errors. Alternatively, you can specify the name of your baseline file.
```
vendor/bin/psalm --set-baseline=your-baseline.xml
```
You should commit that generated file so that Psalm can use it when running in other places (e.g. CI). It won't complain about those errors either.
You have two options to use the generated baseline when running psalm:
```
vendor/bin/psalm --use-baseline=your-baseline.xml
```
or using the configuration:
```xml
...
```
To update that baseline file, use
```
vendor/bin/psalm --update-baseline
```
This will remove fixed issues, but will _not_ add new issues. To add new issues, use `--set-baseline=...`.
In case you want to run psalm without the baseline, run
```
vendor/bin/psalm --ignore-baseline
```
Baseline files are a great way to gradually improve a codebase.
## Using a plugin
If you want something more custom, like suppressing a certain type of error on classes that implement a particular interface, you can use a plugin that implements `AfterClassLikeVisitInterface`
```php
getStorage();
if ($storage->user_defined
&& !$storage->is_interface
&& \class_exists($storage->name)
&& (new ReflectionClass($storage->name))->implementsInterface(\Your\Interface::class)
) {
$storage->suppressed_issues[-1] = 'PropertyNotSetInConstructor';
}
}
}
```
---
### Running Psalm Error Levels (`docs/running_psalm/error_levels.md`)
# Error levels
Psalm can run at error levels 1 (strictest) through 8 (most lenient). The default is **level 2**.
A stricter level (lower number) reports more issues as errors. A more lenient level (higher number) demotes issues to info (non-blocking).
### Quick-reference summary
| Level | Strictness | What changes compared to the level above |
|-------|-----------|-------------------------------|
| 1 (strictest) | Everything is an error | Adds `Mixed*` issues, `LessSpecificReturnType` as errors |
| **2 (default)** | Most issues | `Mixed*` demoted to info |
| 3 | Moderate | `Deprecated*`, `MissingParamType`, `PropertyNotSetInConstructor` demoted to info |
| 4 | Lenient | `Possibly*` issues demoted to info |
| 5 | More lenient | `InvalidScalarArgument`, `RedundantCondition`, `TooManyArguments` demoted to info |
| 6 | Very lenient | `FalsableReturnStatement`, `InvalidNullableReturnType` demoted to info |
| 7 | Extremely lenient | `InvalidArgument`, `InvalidMethodCall`, `UndefinedMethod` demoted to info |
| 8 (most lenient) | Almost nothing | `MethodSignatureMismatch`, `UninitializedProperty` demoted to info |
### Special categories
- **Always errors**: Issues with very low false-positive rates (e.g., `UndefinedClass`, `UndefinedVariable`). These cannot be suppressed by changing the error level.
- **Feature-specific errors**: Issues only reported when their feature is enabled (e.g., `--taint-analysis` for `Tainted*`, `--find-unused-code` for `Unused*`). When enabled, they are always treated as errors.
## Always treated as errors
These issues have very low false-positive rates and indicate definite problems. They cannot be suppressed by changing the error level.
- [AbstractMethodCall](issues/AbstractMethodCall.md)
- [ComplexFunction](issues/ComplexFunction.md)
- [ComplexMethod](issues/ComplexMethod.md)
- [ConfigIssue](issues/ConfigIssue.md)
- [ConstantDeclarationInTrait](issues/ConstantDeclarationInTrait.md)
- [DuplicateArrayKey](issues/DuplicateArrayKey.md)
- [DuplicateClass](issues/DuplicateClass.md)
- [DuplicateConstant](issues/DuplicateConstant.md)
- [DuplicateEnumCase](issues/DuplicateEnumCase.md)
- [DuplicateEnumCaseValue](issues/DuplicateEnumCaseValue.md)
- [DuplicateFunction](issues/DuplicateFunction.md)
- [DuplicateMethod](issues/DuplicateMethod.md)
- [DuplicateParam](issues/DuplicateParam.md)
- [DuplicateProperty](issues/DuplicateProperty.md)
- [EmptyArrayAccess](issues/EmptyArrayAccess.md)
- [ExtensionRequirementViolation](issues/ExtensionRequirementViolation.md)
- [ImplementationRequirementViolation](issues/ImplementationRequirementViolation.md)
- [ImpureByReferenceAssignment](issues/ImpureByReferenceAssignment.md)
- [ImpureFunctionCall](issues/ImpureFunctionCall.md)
- [ImpureGlobalVariable](issues/ImpureGlobalVariable.md)
- [ImpureMethodCall](issues/ImpureMethodCall.md)
- [ImpurePropertyAssignment](issues/ImpurePropertyAssignment.md)
- [ImpurePropertyFetch](issues/ImpurePropertyFetch.md)
- [ImpureStaticProperty](issues/ImpureStaticProperty.md)
- [ImpureStaticVariable](issues/ImpureStaticVariable.md)
- [ImpureVariable](issues/ImpureVariable.md)
- [InaccessibleClassConstant](issues/InaccessibleClassConstant.md)
- [InaccessibleMethod](issues/InaccessibleMethod.md)
- [InaccessibleProperty](issues/InaccessibleProperty.md)
- [InterfaceInstantiation](issues/InterfaceInstantiation.md)
- [InvalidAttribute](issues/InvalidAttribute.md)
- [InvalidEnumBackingType](issues/InvalidEnumBackingType.md)
- [InvalidEnumCaseValue](issues/InvalidEnumCaseValue.md)
- [InvalidEnumMethod](issues/InvalidEnumMethod.md)
- [InvalidExtendClass](issues/InvalidExtendClass.md)
- [InvalidGlobal](issues/InvalidGlobal.md)
- [InvalidInterfaceImplementation](issues/InvalidInterfaceImplementation.md)
- [InvalidParamDefault](issues/InvalidParamDefault.md)
- [InvalidParent](issues/InvalidParent.md)
- [InvalidPassByReference](issues/InvalidPassByReference.md)
- [InvalidScope](issues/InvalidScope.md)
- [InvalidStaticInvocation](issues/InvalidStaticInvocation.md)
- [InvalidThrow](issues/InvalidThrow.md)
- [LoopInvalidation](issues/LoopInvalidation.md)
- [MethodSignatureMustOmitReturnType](issues/MethodSignatureMustOmitReturnType.md)
- [MethodSignatureMustProvideReturnType](issues/MethodSignatureMustProvideReturnType.md)
- [MissingAbstractPureAnnotation](issues/MissingAbstractPureAnnotation.md)
- [MissingDependency](issues/MissingDependency.md)
- [MissingFile](issues/MissingFile.md)
- [MissingImmutableAnnotation](issues/MissingImmutableAnnotation.md)
- [MissingInterfaceImmutableAnnotation](issues/MissingInterfaceImmutableAnnotation.md)
- [MissingPureAnnotation](issues/MissingPureAnnotation.md)
- [MissingTemplateParam](issues/MissingTemplateParam.md)
- [MissingThrowsDocblock](issues/MissingThrowsDocblock.md)
- [NoEnumProperties](issues/NoEnumProperties.md)
- [NoValue](issues/NoValue.md)
- [NonInvariantPropertyType](issues/NonInvariantPropertyType.md)
- [NonStaticSelfCall](issues/NonStaticSelfCall.md)
- [NullArrayAccess](issues/NullArrayAccess.md)
- [NullFunctionCall](issues/NullFunctionCall.md)
- [NullIterator](issues/NullIterator.md)
- [NullPropertyAssignment](issues/NullPropertyAssignment.md)
- [NullPropertyFetch](issues/NullPropertyFetch.md)
- [NullReference](issues/NullReference.md)
- [OverriddenPropertyAccess](issues/OverriddenPropertyAccess.md)
- [ParadoxicalCondition](issues/ParadoxicalCondition.md)
- [ParentNotFound](issues/ParentNotFound.md)
- [TooFewArguments](issues/TooFewArguments.md)
- [UndefinedAttributeClass](issues/UndefinedAttributeClass.md)
- [UndefinedClass](issues/UndefinedClass.md)
- [UndefinedConstant](issues/UndefinedConstant.md)
- [UndefinedDocblockClass](issues/UndefinedDocblockClass.md)
- [UndefinedFunction](issues/UndefinedFunction.md)
- [UndefinedGlobalVariable](issues/UndefinedGlobalVariable.md)
- [UndefinedInterface](issues/UndefinedInterface.md)
- [UndefinedTrait](issues/UndefinedTrait.md)
- [UndefinedVariable](issues/UndefinedVariable.md)
- [UnimplementedAbstractMethod](issues/UnimplementedAbstractMethod.md)
- [UnimplementedInterfaceMethod](issues/UnimplementedInterfaceMethod.md)
- [UnrecognizedExpression](issues/UnrecognizedExpression.md)
- [UnrecognizedStatement](issues/UnrecognizedStatement.md)
- [UnresolvableConstant](issues/UnresolvableConstant.md)
- [UnsupportedPropertyReferenceUsage](issues/UnsupportedPropertyReferenceUsage.md)
- [UnusedBaselineEntry](issues/UnusedBaselineEntry.md)
- [UnusedFunctionCall](issues/UnusedFunctionCall.md)
- [UnusedIssueHandlerSuppression](issues/UnusedIssueHandlerSuppression.md)
- [UnusedMethodCall](issues/UnusedMethodCall.md)
## Errors that only appear at level 1
At the default level (2), these are reported as info. Set `errorLevel="1"` to treat them as errors.
- [ImmutableDependency](issues/ImmutableDependency.md)
- [IncompatibleTypeParameters](issues/IncompatibleTypeParameters.md)
- [IntMaskComparison](issues/IntMaskComparison.md)
- [InvalidClassConstantType](issues/InvalidClassConstantType.md)
- [LessSpecificClassConstantType](issues/LessSpecificClassConstantType.md)
- [LessSpecificReturnType](issues/LessSpecificReturnType.md)
- [MixedArgument](issues/MixedArgument.md)
- [MixedArgumentTypeCoercion](issues/MixedArgumentTypeCoercion.md)
- [MixedArrayAccess](issues/MixedArrayAccess.md)
- [MixedArrayAssignment](issues/MixedArrayAssignment.md)
- [MixedArrayOffset](issues/MixedArrayOffset.md)
- [MixedArrayTypeCoercion](issues/MixedArrayTypeCoercion.md)
- [MixedAssignment](issues/MixedAssignment.md)
- [MixedClone](issues/MixedClone.md)
- [MixedFunctionCall](issues/MixedFunctionCall.md)
- [MixedMethodCall](issues/MixedMethodCall.md)
- [MixedOperand](issues/MixedOperand.md)
- [MixedPropertyAssignment](issues/MixedPropertyAssignment.md)
- [MixedPropertyFetch](issues/MixedPropertyFetch.md)
- [MixedPropertyTypeCoercion](issues/MixedPropertyTypeCoercion.md)
- [MixedReturnStatement](issues/MixedReturnStatement.md)
- [MixedReturnTypeCoercion](issues/MixedReturnTypeCoercion.md)
- [MixedStringOffsetAssignment](issues/MixedStringOffsetAssignment.md)
- [MutableDependency](issues/MutableDependency.md)
- [PossiblyNullOperand](issues/PossiblyNullOperand.md)
- [RedundantFlag](issues/RedundantFlag.md)
- [RedundantIdentityWithTrue](issues/RedundantIdentityWithTrue.md)
- [Trace](issues/Trace.md)
## Errors at level 2 and below
These issues become info (non-blocking) at level 3 and higher.
- [ClassMustBeFinal](issues/ClassMustBeFinal.md)
- [DeprecatedClass](issues/DeprecatedClass.md)
- [DeprecatedConstant](issues/DeprecatedConstant.md)
- [DeprecatedFunction](issues/DeprecatedFunction.md)
- [DeprecatedInterface](issues/DeprecatedInterface.md)
- [DeprecatedMethod](issues/DeprecatedMethod.md)
- [DeprecatedProperty](issues/DeprecatedProperty.md)
- [DeprecatedTrait](issues/DeprecatedTrait.md)
- [DirectConstructorCall](issues/DirectConstructorCall.md)
- [DocblockTypeContradiction](issues/DocblockTypeContradiction.md)
- [InvalidDocblockParamName](issues/InvalidDocblockParamName.md)
- [InvalidFalsableReturnType](issues/InvalidFalsableReturnType.md)
- [InvalidStringClass](issues/InvalidStringClass.md)
- [MismatchingDocblockPropertyType](issues/MismatchingDocblockPropertyType.md)
- [MissingClassConstType](issues/MissingClassConstType.md)
- [MissingClosureParamType](issues/MissingClosureParamType.md)
- [MissingClosureReturnType](issues/MissingClosureReturnType.md)
- [MissingConstructor](issues/MissingConstructor.md)
- [MissingParamType](issues/MissingParamType.md)
- [MissingPropertyType](issues/MissingPropertyType.md)
- [MissingReturnType](issues/MissingReturnType.md)
- [NullOperand](issues/NullOperand.md)
- [PrivateFinalMethod](issues/PrivateFinalMethod.md)
- [PropertyNotSetInConstructor](issues/PropertyNotSetInConstructor.md)
- [RawObjectIteration](issues/RawObjectIteration.md)
- [RedundantCastGivenDocblockType](issues/RedundantCastGivenDocblockType.md)
- [RedundantConditionGivenDocblockType](issues/RedundantConditionGivenDocblockType.md)
- [RedundantFunctionCallGivenDocblockType](issues/RedundantFunctionCallGivenDocblockType.md)
- [ReferenceConstraintViolation](issues/ReferenceConstraintViolation.md)
- [RiskyTruthyFalsyComparison](issues/RiskyTruthyFalsyComparison.md)
- [UndefinedTrace](issues/UndefinedTrace.md)
- [UnresolvableInclude](issues/UnresolvableInclude.md)
- [UnsafeGenericInstantiation](issues/UnsafeGenericInstantiation.md)
- [UnsafeInstantiation](issues/UnsafeInstantiation.md)
- [UnsupportedReferenceUsage](issues/UnsupportedReferenceUsage.md)
## Errors at level 3 and below
These issues become info (non-blocking) at level 4 and higher.
- [ArgumentTypeCoercion](issues/ArgumentTypeCoercion.md)
- [LessSpecificReturnStatement](issues/LessSpecificReturnStatement.md)
- [MoreSpecificReturnType](issues/MoreSpecificReturnType.md)
- [NonInvariantDocblockPropertyType](issues/NonInvariantDocblockPropertyType.md)
- [PossiblyFalseArgument](issues/PossiblyFalseArgument.md)
- [PossiblyFalseIterator](issues/PossiblyFalseIterator.md)
- [PossiblyFalseOperand](issues/PossiblyFalseOperand.md)
- [PossiblyFalsePropertyAssignmentValue](issues/PossiblyFalsePropertyAssignmentValue.md)
- [PossiblyFalseReference](issues/PossiblyFalseReference.md)
- [PossiblyInvalidArgument](issues/PossiblyInvalidArgument.md)
- [PossiblyInvalidArrayAccess](issues/PossiblyInvalidArrayAccess.md)
- [PossiblyInvalidArrayAssignment](issues/PossiblyInvalidArrayAssignment.md)
- [PossiblyInvalidArrayOffset](issues/PossiblyInvalidArrayOffset.md)
- [PossiblyInvalidCast](issues/PossiblyInvalidCast.md)
- [PossiblyInvalidClone](issues/PossiblyInvalidClone.md)
- [PossiblyInvalidFunctionCall](issues/PossiblyInvalidFunctionCall.md)
- [PossiblyInvalidIterator](issues/PossiblyInvalidIterator.md)
- [PossiblyInvalidMethodCall](issues/PossiblyInvalidMethodCall.md)
- [PossiblyInvalidOperand](issues/PossiblyInvalidOperand.md)
- [PossiblyInvalidPropertyAssignment](issues/PossiblyInvalidPropertyAssignment.md)
- [PossiblyInvalidPropertyAssignmentValue](issues/PossiblyInvalidPropertyAssignmentValue.md)
- [PossiblyInvalidPropertyFetch](issues/PossiblyInvalidPropertyFetch.md)
- [PossiblyNullArgument](issues/PossiblyNullArgument.md)
- [PossiblyNullArrayAccess](issues/PossiblyNullArrayAccess.md)
- [PossiblyNullArrayAssignment](issues/PossiblyNullArrayAssignment.md)
- [PossiblyNullArrayOffset](issues/PossiblyNullArrayOffset.md)
- [PossiblyNullFunctionCall](issues/PossiblyNullFunctionCall.md)
- [PossiblyNullIterator](issues/PossiblyNullIterator.md)
- [PossiblyNullPropertyAssignment](issues/PossiblyNullPropertyAssignment.md)
- [PossiblyNullPropertyAssignmentValue](issues/PossiblyNullPropertyAssignmentValue.md)
- [PossiblyNullPropertyFetch](issues/PossiblyNullPropertyFetch.md)
- [PossiblyNullReference](issues/PossiblyNullReference.md)
- [PossiblyUndefinedArrayOffset](issues/PossiblyUndefinedArrayOffset.md)
- [PossiblyUndefinedGlobalVariable](issues/PossiblyUndefinedGlobalVariable.md)
- [PossiblyUndefinedMethod](issues/PossiblyUndefinedMethod.md)
- [PossiblyUndefinedVariable](issues/PossiblyUndefinedVariable.md)
- [PropertyTypeCoercion](issues/PropertyTypeCoercion.md)
- [RiskyCast](issues/RiskyCast.md)
## Errors at level 4 and below
These issues become info (non-blocking) at level 5 and higher.
- [FalseOperand](issues/FalseOperand.md)
- [ForbiddenCode](issues/ForbiddenCode.md)
- [IfThisIsMismatch](issues/IfThisIsMismatch.md)
- [ImplementedParamTypeMismatch](issues/ImplementedParamTypeMismatch.md)
- [ImplementedReturnTypeMismatch](issues/ImplementedReturnTypeMismatch.md)
- [ImplicitToStringCast](issues/ImplicitToStringCast.md)
- [InheritorViolation](issues/InheritorViolation.md)
- [InternalClass](issues/InternalClass.md)
- [InternalMethod](issues/InternalMethod.md)
- [InternalProperty](issues/InternalProperty.md)
- [InvalidDocblock](issues/InvalidDocblock.md)
- [InvalidLiteralArgument](issues/InvalidLiteralArgument.md)
- [InvalidOperand](issues/InvalidOperand.md)
- [InvalidScalarArgument](issues/InvalidScalarArgument.md)
- [InvalidToString](issues/InvalidToString.md)
- [MismatchingDocblockParamType](issues/MismatchingDocblockParamType.md)
- [MismatchingDocblockReturnType](issues/MismatchingDocblockReturnType.md)
- [MissingDocblockType](issues/MissingDocblockType.md)
- [NoInterfaceProperties](issues/NoInterfaceProperties.md)
- [PossibleRawObjectIteration](issues/PossibleRawObjectIteration.md)
- [PossiblyInvalidDocblockTag](issues/PossiblyInvalidDocblockTag.md)
- [RedundantCast](issues/RedundantCast.md)
- [RedundantCondition](issues/RedundantCondition.md)
- [RedundantFunctionCall](issues/RedundantFunctionCall.md)
- [RedundantPropertyInitializationCheck](issues/RedundantPropertyInitializationCheck.md)
- [ReferenceReusedFromConfusingScope](issues/ReferenceReusedFromConfusingScope.md)
- [StringIncrement](issues/StringIncrement.md)
- [TooManyArguments](issues/TooManyArguments.md)
- [TypeDoesNotContainNull](issues/TypeDoesNotContainNull.md)
- [TypeDoesNotContainType](issues/TypeDoesNotContainType.md)
- [UndefinedMagicMethod](issues/UndefinedMagicMethod.md)
- [UndefinedMagicPropertyAssignment](issues/UndefinedMagicPropertyAssignment.md)
- [UndefinedMagicPropertyFetch](issues/UndefinedMagicPropertyFetch.md)
## Errors at level 5 and below
These issues become info (non-blocking) at level 6 and higher.
- [ConstructorSignatureMismatch](issues/ConstructorSignatureMismatch.md)
- [FalsableReturnStatement](issues/FalsableReturnStatement.md)
- [InvalidNullableReturnType](issues/InvalidNullableReturnType.md)
- [LessSpecificImplementedReturnType](issues/LessSpecificImplementedReturnType.md)
- [MoreSpecificImplementedParamType](issues/MoreSpecificImplementedParamType.md)
- [NullableReturnStatement](issues/NullableReturnStatement.md)
- [UndefinedInterfaceMethod](issues/UndefinedInterfaceMethod.md)
- [UndefinedThisPropertyAssignment](issues/UndefinedThisPropertyAssignment.md)
## Errors at level 6 and below
These issues become info (non-blocking) at level 7 and higher.
- [AmbiguousConstantInheritance](issues/AmbiguousConstantInheritance.md)
- [InvalidArgument](issues/InvalidArgument.md)
- [InvalidArrayAccess](issues/InvalidArrayAccess.md)
- [InvalidArrayAssignment](issues/InvalidArrayAssignment.md)
- [InvalidArrayOffset](issues/InvalidArrayOffset.md)
- [InvalidCast](issues/InvalidCast.md)
- [InvalidCatch](issues/InvalidCatch.md)
- [InvalidClass](issues/InvalidClass.md)
- [InvalidClone](issues/InvalidClone.md)
- [InvalidConstantAssignmentValue](issues/InvalidConstantAssignmentValue.md)
- [InvalidFunctionCall](issues/InvalidFunctionCall.md)
- [InvalidIterator](issues/InvalidIterator.md)
- [InvalidMethodCall](issues/InvalidMethodCall.md)
- [InvalidNamedArgument](issues/InvalidNamedArgument.md)
- [InvalidPropertyAssignment](issues/InvalidPropertyAssignment.md)
- [InvalidPropertyAssignmentValue](issues/InvalidPropertyAssignmentValue.md)
- [InvalidPropertyFetch](issues/InvalidPropertyFetch.md)
- [InvalidReturnStatement](issues/InvalidReturnStatement.md)
- [InvalidReturnType](issues/InvalidReturnType.md)
- [InvalidTemplateParam](issues/InvalidTemplateParam.md)
- [NullArgument](issues/NullArgument.md)
- [NullArrayOffset](issues/NullArrayOffset.md)
- [OverriddenFinalConstant](issues/OverriddenFinalConstant.md)
- [OverriddenFinalProperty](issues/OverriddenFinalProperty.md)
- [OverriddenInterfaceConstant](issues/OverriddenInterfaceConstant.md)
- [TooManyTemplateParams](issues/TooManyTemplateParams.md)
- [TraitMethodSignatureMismatch](issues/TraitMethodSignatureMismatch.md)
- [UndefinedMethod](issues/UndefinedMethod.md)
- [UndefinedPropertyAssignment](issues/UndefinedPropertyAssignment.md)
- [UndefinedPropertyFetch](issues/UndefinedPropertyFetch.md)
- [UndefinedThisPropertyFetch](issues/UndefinedThisPropertyFetch.md)
## Errors at level 7 and below
These issues become info (non-blocking) at level 8.
- [AbstractInstantiation](issues/AbstractInstantiation.md)
- [AssignmentToVoid](issues/AssignmentToVoid.md)
- [CircularReference](issues/CircularReference.md)
- [ConflictingReferenceConstraint](issues/ConflictingReferenceConstraint.md)
- [ContinueOutsideLoop](issues/ContinueOutsideLoop.md)
- [InvalidOverride](issues/InvalidOverride.md)
- [InvalidTraversableImplementation](issues/InvalidTraversableImplementation.md)
- [InvalidTypeImport](issues/InvalidTypeImport.md)
- [MethodSignatureMismatch](issues/MethodSignatureMismatch.md)
- [NamedArgumentNotAllowed](issues/NamedArgumentNotAllowed.md)
- [NonVariableReferenceReturn](issues/NonVariableReferenceReturn.md)
- [OverriddenMethodAccess](issues/OverriddenMethodAccess.md)
- [ParamNameMismatch](issues/ParamNameMismatch.md)
- [ReservedWord](issues/ReservedWord.md)
- [UnhandledMatchCondition](issues/UnhandledMatchCondition.md)
- [UninitializedProperty](issues/UninitializedProperty.md)
## Feature-specific errors
These issues are only reported when their corresponding feature is enabled (e.g., `--taint-analysis` for Tainted* issues, `--find-unused-code` for Unused* issues). When enabled, they are always treated as errors.
- [LiteralKeyUnshapedArray](issues/LiteralKeyUnshapedArray.md)
- [MissingOverrideAttribute](issues/MissingOverrideAttribute.md)
- [PossiblyUndefinedIntArrayOffset](issues/PossiblyUndefinedIntArrayOffset.md)
- [PossiblyUndefinedStringArrayOffset](issues/PossiblyUndefinedStringArrayOffset.md)
- [PossiblyUnusedMethod](issues/PossiblyUnusedMethod.md)
- [PossiblyUnusedParam](issues/PossiblyUnusedParam.md)
- [PossiblyUnusedProperty](issues/PossiblyUnusedProperty.md)
- [PossiblyUnusedReturnValue](issues/PossiblyUnusedReturnValue.md)
- [TaintedCallable](issues/TaintedCallable.md)
- [TaintedCookie](issues/TaintedCookie.md)
- [TaintedCustom](issues/TaintedCustom.md)
- [TaintedEval](issues/TaintedEval.md)
- [TaintedExtract](issues/TaintedExtract.md)
- [TaintedFile](issues/TaintedFile.md)
- [TaintedHeader](issues/TaintedHeader.md)
- [TaintedHtml](issues/TaintedHtml.md)
- [TaintedInclude](issues/TaintedInclude.md)
- [TaintedInput](issues/TaintedInput.md)
- [TaintedLdap](issues/TaintedLdap.md)
- [TaintedLlmPrompt](issues/TaintedLlmPrompt.md)
- [TaintedNosql](issues/TaintedNosql.md)
- [TaintedSSRF](issues/TaintedSSRF.md)
- [TaintedShell](issues/TaintedShell.md)
- [TaintedSleep](issues/TaintedSleep.md)
- [TaintedSql](issues/TaintedSql.md)
- [TaintedSystemSecret](issues/TaintedSystemSecret.md)
- [TaintedTextWithQuotes](issues/TaintedTextWithQuotes.md)
- [TaintedUnserialize](issues/TaintedUnserialize.md)
- [TaintedUrlComponent](issues/TaintedUrlComponent.md)
- [TaintedUrlPath](issues/TaintedUrlPath.md)
- [TaintedUserSecret](issues/TaintedUserSecret.md)
- [TaintedXpath](issues/TaintedXpath.md)
- [UncaughtThrowInGlobalScope](issues/UncaughtThrowInGlobalScope.md)
- [UnevaluatedCode](issues/UnevaluatedCode.md)
- [UnnecessaryVarAnnotation](issues/UnnecessaryVarAnnotation.md)
- [UnusedClass](issues/UnusedClass.md)
- [UnusedClosureParam](issues/UnusedClosureParam.md)
- [UnusedConstructor](issues/UnusedConstructor.md)
- [UnusedDocblockParam](issues/UnusedDocblockParam.md)
- [UnusedForeachValue](issues/UnusedForeachValue.md)
- [UnusedMethod](issues/UnusedMethod.md)
- [UnusedParam](issues/UnusedParam.md)
- [UnusedProperty](issues/UnusedProperty.md)
- [UnusedPsalmSuppress](issues/UnusedPsalmSuppress.md)
- [UnusedReturnValue](issues/UnusedReturnValue.md)
- [UnusedVariable](issues/UnusedVariable.md)
---
### Running Psalm Installation (`docs/running_psalm/installation.md`)
# Installation
The latest version of Psalm requires PHP >= 8.2 and [Composer](https://getcomposer.org/).
```bash
composer require --dev vimeo/psalm
```
Generate a config file:
```bash
./vendor/bin/psalm --init
```
Psalm will scan your project and figure out an appropriate [error level](error_levels.md) for your codebase.
Then run Psalm:
```bash
./vendor/bin/psalm --no-cache
```
Psalm will probably find a number of issues - find out how to deal with them in [Dealing with code issues](dealing_with_code_issues.md).
## Docker image
It is recommended to run Psalm in the official docker image: it uses a custom build of PHP built from scratch, running Psalm **+30% faster** on average than normal PHP (**+50% faster** if comparing to PHP without opcache installed).
```bash
docker run -v $PWD:/app --rm -it ghcr.io/danog/psalm:latest /composer/vendor/bin/psalm --no-cache
```
More specific tags are also available (i.e. `ghcr.io/danog/psalm:6.9.1`, as well as branch tags).
Issues due to missing extensions can be fixed by enabling them in psalm.xml and/or requiring them in composer.json [see here »](https://psalm.dev/docs/running_psalm/configuration/#enableextensions) for more info.
Extensions not stubbed by Psalm itself (and thus not available as a psalm config option) may be stubbed using [traditional PHP stubs](https://github.com/JetBrains/phpstorm-stubs/).
## Installing plugins
While Psalm can figure out the types used by various libraries based on
their source code and docblocks, it works even better with custom-tailored types
provided by Psalm plugins.
Check out the [list of existing plugins on Packagist](https://packagist.org/?type=psalm-plugin).
Install them with `composer require --dev && vendor/bin/psalm-plugin enable `
Read more about plugins in [Using Plugins chapter](plugins/using_plugins.md).
## Using the Phar
Sometimes your project can conflict with one or more of Psalm’s dependencies. In
that case you may find the Phar (a self-contained PHP executable) useful.
The Phar can be downloaded from GitHub:
```bash
wget https://github.com/vimeo/psalm/releases/latest/download/psalm.phar
chmod +x psalm.phar
./psalm.phar --version
```
Alternatively, you can use Composer to install the Phar:
```bash
composer require --dev psalm/phar
```
---
### Running Psalm Issues (`docs/running_psalm/issues.md`)
# Issue types
- [AbstractInstantiation](issues/AbstractInstantiation.md)
- [AbstractMethodCall](issues/AbstractMethodCall.md)
- [AmbiguousConstantInheritance](issues/AmbiguousConstantInheritance.md)
- [ArgumentTypeCoercion](issues/ArgumentTypeCoercion.md)
- [AssignmentToVoid](issues/AssignmentToVoid.md)
- [CheckType](issues/CheckType.md)
- [CircularReference](issues/CircularReference.md)
- [ClassMustBeFinal](issues/ClassMustBeFinal.md)
- [ComplexFunction](issues/ComplexFunction.md)
- [ComplexMethod](issues/ComplexMethod.md)
- [ConfigIssue](issues/ConfigIssue.md)
- [ConflictingReferenceConstraint](issues/ConflictingReferenceConstraint.md)
- [ConstantDeclarationInTrait](issues/ConstantDeclarationInTrait.md)
- [ConstructorSignatureMismatch](issues/ConstructorSignatureMismatch.md)
- [ContinueOutsideLoop](issues/ContinueOutsideLoop.md)
- [DeprecatedClass](issues/DeprecatedClass.md)
- [DeprecatedConstant](issues/DeprecatedConstant.md)
- [DeprecatedFunction](issues/DeprecatedFunction.md)
- [DeprecatedInterface](issues/DeprecatedInterface.md)
- [DeprecatedMethod](issues/DeprecatedMethod.md)
- [DeprecatedProperty](issues/DeprecatedProperty.md)
- [DeprecatedTrait](issues/DeprecatedTrait.md)
- [DirectConstructorCall](issues/DirectConstructorCall.md)
- [DocblockTypeContradiction](issues/DocblockTypeContradiction.md)
- [DuplicateArrayKey](issues/DuplicateArrayKey.md)
- [DuplicateClass](issues/DuplicateClass.md)
- [DuplicateConstant](issues/DuplicateConstant.md)
- [DuplicateEnumCase](issues/DuplicateEnumCase.md)
- [DuplicateEnumCaseValue](issues/DuplicateEnumCaseValue.md)
- [DuplicateFunction](issues/DuplicateFunction.md)
- [DuplicateMethod](issues/DuplicateMethod.md)
- [DuplicateParam](issues/DuplicateParam.md)
- [DuplicateProperty](issues/DuplicateProperty.md)
- [EmptyArrayAccess](issues/EmptyArrayAccess.md)
- [ExtensionRequirementViolation](issues/ExtensionRequirementViolation.md)
- [FalsableReturnStatement](issues/FalsableReturnStatement.md)
- [FalseOperand](issues/FalseOperand.md)
- [ForbiddenCode](issues/ForbiddenCode.md)
- [IfThisIsMismatch](issues/IfThisIsMismatch.md)
- [ImmutableDependency](issues/ImmutableDependency.md)
- [ImplementationRequirementViolation](issues/ImplementationRequirementViolation.md)
- [ImplementedParamTypeMismatch](issues/ImplementedParamTypeMismatch.md)
- [ImplementedReturnTypeMismatch](issues/ImplementedReturnTypeMismatch.md)
- [ImplicitToStringCast](issues/ImplicitToStringCast.md)
- [ImpureByReferenceAssignment](issues/ImpureByReferenceAssignment.md)
- [ImpureFunctionCall](issues/ImpureFunctionCall.md)
- [ImpureGlobalVariable](issues/ImpureGlobalVariable.md)
- [ImpureMethodCall](issues/ImpureMethodCall.md)
- [ImpurePropertyAssignment](issues/ImpurePropertyAssignment.md)
- [ImpurePropertyFetch](issues/ImpurePropertyFetch.md)
- [ImpureStaticProperty](issues/ImpureStaticProperty.md)
- [ImpureStaticVariable](issues/ImpureStaticVariable.md)
- [ImpureVariable](issues/ImpureVariable.md)
- [InaccessibleClassConstant](issues/InaccessibleClassConstant.md)
- [InaccessibleMethod](issues/InaccessibleMethod.md)
- [InaccessibleProperty](issues/InaccessibleProperty.md)
- [IncompatibleTypeParameters](issues/IncompatibleTypeParameters.md)
- [InheritorViolation](issues/InheritorViolation.md)
- [InterfaceInstantiation](issues/InterfaceInstantiation.md)
- [InternalClass](issues/InternalClass.md)
- [InternalMethod](issues/InternalMethod.md)
- [InternalProperty](issues/InternalProperty.md)
- [IntMaskComparison](issues/IntMaskComparison.md)
- [InvalidArgument](issues/InvalidArgument.md)
- [InvalidArrayAccess](issues/InvalidArrayAccess.md)
- [InvalidArrayAssignment](issues/InvalidArrayAssignment.md)
- [InvalidArrayOffset](issues/InvalidArrayOffset.md)
- [InvalidAttribute](issues/InvalidAttribute.md)
- [InvalidCast](issues/InvalidCast.md)
- [InvalidCatch](issues/InvalidCatch.md)
- [InvalidClass](issues/InvalidClass.md)
- [InvalidClassConstantType](issues/InvalidClassConstantType.md)
- [InvalidClone](issues/InvalidClone.md)
- [InvalidConstantAssignmentValue](issues/InvalidConstantAssignmentValue.md)
- [InvalidDocblock](issues/InvalidDocblock.md)
- [InvalidDocblockParamName](issues/InvalidDocblockParamName.md)
- [InvalidEnumBackingType](issues/InvalidEnumBackingType.md)
- [InvalidEnumCaseValue](issues/InvalidEnumCaseValue.md)
- [InvalidEnumMethod](issues/InvalidEnumMethod.md)
- [InvalidExtendClass](issues/InvalidExtendClass.md)
- [InvalidFalsableReturnType](issues/InvalidFalsableReturnType.md)
- [InvalidFunctionCall](issues/InvalidFunctionCall.md)
- [InvalidGlobal](issues/InvalidGlobal.md)
- [InvalidInterfaceImplementation](issues/InvalidInterfaceImplementation.md)
- [InvalidIterator](issues/InvalidIterator.md)
- [InvalidLiteralArgument](issues/InvalidLiteralArgument.md)
- [InvalidMethodCall](issues/InvalidMethodCall.md)
- [InvalidNamedArgument](issues/InvalidNamedArgument.md)
- [InvalidNullableReturnType](issues/InvalidNullableReturnType.md)
- [InvalidOperand](issues/InvalidOperand.md)
- [InvalidOverride](issues/InvalidOverride.md)
- [InvalidParamDefault](issues/InvalidParamDefault.md)
- [InvalidParent](issues/InvalidParent.md)
- [InvalidPassByReference](issues/InvalidPassByReference.md)
- [InvalidPropertyAssignment](issues/InvalidPropertyAssignment.md)
- [InvalidPropertyAssignmentValue](issues/InvalidPropertyAssignmentValue.md)
- [InvalidPropertyFetch](issues/InvalidPropertyFetch.md)
- [InvalidReturnStatement](issues/InvalidReturnStatement.md)
- [InvalidReturnType](issues/InvalidReturnType.md)
- [InvalidScalarArgument](issues/InvalidScalarArgument.md)
- [InvalidScope](issues/InvalidScope.md)
- [InvalidStaticInvocation](issues/InvalidStaticInvocation.md)
- [InvalidStringClass](issues/InvalidStringClass.md)
- [InvalidTemplateParam](issues/InvalidTemplateParam.md)
- [InvalidThrow](issues/InvalidThrow.md)
- [InvalidToString](issues/InvalidToString.md)
- [InvalidTraversableImplementation](issues/InvalidTraversableImplementation.md)
- [InvalidTypeImport](issues/InvalidTypeImport.md)
- [LessSpecificClassConstantType](issues/LessSpecificClassConstantType.md)
- [LessSpecificImplementedReturnType](issues/LessSpecificImplementedReturnType.md)
- [LessSpecificReturnStatement](issues/LessSpecificReturnStatement.md)
- [LessSpecificReturnType](issues/LessSpecificReturnType.md)
- [LiteralKeyUnshapedArray](issues/LiteralKeyUnshapedArray.md)
- [LoopInvalidation](issues/LoopInvalidation.md)
- [MethodSignatureMismatch](issues/MethodSignatureMismatch.md)
- [MethodSignatureMustOmitReturnType](issues/MethodSignatureMustOmitReturnType.md)
- [MethodSignatureMustProvideReturnType](issues/MethodSignatureMustProvideReturnType.md)
- [MismatchingDocblockParamType](issues/MismatchingDocblockParamType.md)
- [MismatchingDocblockPropertyType](issues/MismatchingDocblockPropertyType.md)
- [MismatchingDocblockReturnType](issues/MismatchingDocblockReturnType.md)
- [MissingAbstractPureAnnotation](issues/MissingAbstractPureAnnotation.md)
- [MissingClassConstType](issues/MissingClassConstType.md)
- [MissingClosureParamType](issues/MissingClosureParamType.md)
- [MissingClosureReturnType](issues/MissingClosureReturnType.md)
- [MissingConstructor](issues/MissingConstructor.md)
- [MissingDependency](issues/MissingDependency.md)
- [MissingDocblockType](issues/MissingDocblockType.md)
- [MissingFile](issues/MissingFile.md)
- [MissingImmutableAnnotation](issues/MissingImmutableAnnotation.md)
- [MissingInterfaceImmutableAnnotation](issues/MissingInterfaceImmutableAnnotation.md)
- [MissingOverrideAttribute](issues/MissingOverrideAttribute.md)
- [MissingParamType](issues/MissingParamType.md)
- [MissingPropertyType](issues/MissingPropertyType.md)
- [MissingPureAnnotation](issues/MissingPureAnnotation.md)
- [MissingReturnType](issues/MissingReturnType.md)
- [MissingTemplateParam](issues/MissingTemplateParam.md)
- [MissingThrowsDocblock](issues/MissingThrowsDocblock.md)
- [MixedArgument](issues/MixedArgument.md)
- [MixedArgumentTypeCoercion](issues/MixedArgumentTypeCoercion.md)
- [MixedArrayAccess](issues/MixedArrayAccess.md)
- [MixedArrayAssignment](issues/MixedArrayAssignment.md)
- [MixedArrayOffset](issues/MixedArrayOffset.md)
- [MixedArrayTypeCoercion](issues/MixedArrayTypeCoercion.md)
- [MixedAssignment](issues/MixedAssignment.md)
- [MixedClone](issues/MixedClone.md)
- [MixedFunctionCall](issues/MixedFunctionCall.md)
- [MixedMethodCall](issues/MixedMethodCall.md)
- [MixedOperand](issues/MixedOperand.md)
- [MixedPropertyAssignment](issues/MixedPropertyAssignment.md)
- [MixedPropertyFetch](issues/MixedPropertyFetch.md)
- [MixedPropertyTypeCoercion](issues/MixedPropertyTypeCoercion.md)
- [MixedReturnStatement](issues/MixedReturnStatement.md)
- [MixedReturnTypeCoercion](issues/MixedReturnTypeCoercion.md)
- [MixedStringOffsetAssignment](issues/MixedStringOffsetAssignment.md)
- [MoreSpecificImplementedParamType](issues/MoreSpecificImplementedParamType.md)
- [MoreSpecificReturnType](issues/MoreSpecificReturnType.md)
- [MutableDependency](issues/MutableDependency.md)
- [NamedArgumentNotAllowed](issues/NamedArgumentNotAllowed.md)
- [NoEnumProperties](issues/NoEnumProperties.md)
- [NoInterfaceProperties](issues/NoInterfaceProperties.md)
- [NonInvariantDocblockPropertyType](issues/NonInvariantDocblockPropertyType.md)
- [NonInvariantPropertyType](issues/NonInvariantPropertyType.md)
- [NonStaticSelfCall](issues/NonStaticSelfCall.md)
- [NonVariableReferenceReturn](issues/NonVariableReferenceReturn.md)
- [NoValue](issues/NoValue.md)
- [NullableReturnStatement](issues/NullableReturnStatement.md)
- [NullArgument](issues/NullArgument.md)
- [NullArrayAccess](issues/NullArrayAccess.md)
- [NullArrayOffset](issues/NullArrayOffset.md)
- [NullFunctionCall](issues/NullFunctionCall.md)
- [NullIterator](issues/NullIterator.md)
- [NullOperand](issues/NullOperand.md)
- [NullPropertyAssignment](issues/NullPropertyAssignment.md)
- [NullPropertyFetch](issues/NullPropertyFetch.md)
- [NullReference](issues/NullReference.md)
- [OverriddenFinalConstant](issues/OverriddenFinalConstant.md)
- [OverriddenFinalProperty](issues/OverriddenFinalProperty.md)
- [OverriddenInterfaceConstant](issues/OverriddenInterfaceConstant.md)
- [OverriddenMethodAccess](issues/OverriddenMethodAccess.md)
- [OverriddenPropertyAccess](issues/OverriddenPropertyAccess.md)
- [ParadoxicalCondition](issues/ParadoxicalCondition.md)
- [ParamNameMismatch](issues/ParamNameMismatch.md)
- [ParentNotFound](issues/ParentNotFound.md)
- [ParseError](issues/ParseError.md)
- [PluginIssue](issues/PluginIssue.md)
- [PossibleRawObjectIteration](issues/PossibleRawObjectIteration.md)
- [PossiblyFalseArgument](issues/PossiblyFalseArgument.md)
- [PossiblyFalseIterator](issues/PossiblyFalseIterator.md)
- [PossiblyFalseOperand](issues/PossiblyFalseOperand.md)
- [PossiblyFalsePropertyAssignmentValue](issues/PossiblyFalsePropertyAssignmentValue.md)
- [PossiblyFalseReference](issues/PossiblyFalseReference.md)
- [PossiblyInvalidArgument](issues/PossiblyInvalidArgument.md)
- [PossiblyInvalidArrayAccess](issues/PossiblyInvalidArrayAccess.md)
- [PossiblyInvalidArrayAssignment](issues/PossiblyInvalidArrayAssignment.md)
- [PossiblyInvalidArrayOffset](issues/PossiblyInvalidArrayOffset.md)
- [PossiblyInvalidCast](issues/PossiblyInvalidCast.md)
- [PossiblyInvalidClone](issues/PossiblyInvalidClone.md)
- [PossiblyInvalidDocblockTag](issues/PossiblyInvalidDocblockTag.md)
- [PossiblyInvalidFunctionCall](issues/PossiblyInvalidFunctionCall.md)
- [PossiblyInvalidIterator](issues/PossiblyInvalidIterator.md)
- [PossiblyInvalidMethodCall](issues/PossiblyInvalidMethodCall.md)
- [PossiblyInvalidOperand](issues/PossiblyInvalidOperand.md)
- [PossiblyInvalidPropertyAssignment](issues/PossiblyInvalidPropertyAssignment.md)
- [PossiblyInvalidPropertyAssignmentValue](issues/PossiblyInvalidPropertyAssignmentValue.md)
- [PossiblyInvalidPropertyFetch](issues/PossiblyInvalidPropertyFetch.md)
- [PossiblyNullArgument](issues/PossiblyNullArgument.md)
- [PossiblyNullArrayAccess](issues/PossiblyNullArrayAccess.md)
- [PossiblyNullArrayAssignment](issues/PossiblyNullArrayAssignment.md)
- [PossiblyNullArrayOffset](issues/PossiblyNullArrayOffset.md)
- [PossiblyNullFunctionCall](issues/PossiblyNullFunctionCall.md)
- [PossiblyNullIterator](issues/PossiblyNullIterator.md)
- [PossiblyNullOperand](issues/PossiblyNullOperand.md)
- [PossiblyNullPropertyAssignment](issues/PossiblyNullPropertyAssignment.md)
- [PossiblyNullPropertyAssignmentValue](issues/PossiblyNullPropertyAssignmentValue.md)
- [PossiblyNullPropertyFetch](issues/PossiblyNullPropertyFetch.md)
- [PossiblyNullReference](issues/PossiblyNullReference.md)
- [PossiblyUndefinedArrayOffset](issues/PossiblyUndefinedArrayOffset.md)
- [PossiblyUndefinedGlobalVariable](issues/PossiblyUndefinedGlobalVariable.md)
- [PossiblyUndefinedIntArrayOffset](issues/PossiblyUndefinedIntArrayOffset.md)
- [PossiblyUndefinedMethod](issues/PossiblyUndefinedMethod.md)
- [PossiblyUndefinedStringArrayOffset](issues/PossiblyUndefinedStringArrayOffset.md)
- [PossiblyUndefinedVariable](issues/PossiblyUndefinedVariable.md)
- [PossiblyUnusedMethod](issues/PossiblyUnusedMethod.md)
- [PossiblyUnusedParam](issues/PossiblyUnusedParam.md)
- [PossiblyUnusedProperty](issues/PossiblyUnusedProperty.md)
- [PossiblyUnusedReturnValue](issues/PossiblyUnusedReturnValue.md)
- [PrivateFinalMethod](issues/PrivateFinalMethod.md)
- [PropertyNotSetInConstructor](issues/PropertyNotSetInConstructor.md)
- [PropertyTypeCoercion](issues/PropertyTypeCoercion.md)
- [RawObjectIteration](issues/RawObjectIteration.md)
- [RedundantCast](issues/RedundantCast.md)
- [RedundantCastGivenDocblockType](issues/RedundantCastGivenDocblockType.md)
- [RedundantCondition](issues/RedundantCondition.md)
- [RedundantConditionGivenDocblockType](issues/RedundantConditionGivenDocblockType.md)
- [RedundantFlag](issues/RedundantFlag.md)
- [RedundantFunctionCall](issues/RedundantFunctionCall.md)
- [RedundantFunctionCallGivenDocblockType](issues/RedundantFunctionCallGivenDocblockType.md)
- [RedundantIdentityWithTrue](issues/RedundantIdentityWithTrue.md)
- [RedundantPropertyInitializationCheck](issues/RedundantPropertyInitializationCheck.md)
- [ReferenceConstraintViolation](issues/ReferenceConstraintViolation.md)
- [ReferenceReusedFromConfusingScope](issues/ReferenceReusedFromConfusingScope.md)
- [ReservedWord](issues/ReservedWord.md)
- [RiskyCast](issues/RiskyCast.md)
- [RiskyTruthyFalsyComparison](issues/RiskyTruthyFalsyComparison.md)
- [StringIncrement](issues/StringIncrement.md)
- [TaintedCallable](issues/TaintedCallable.md)
- [TaintedCookie](issues/TaintedCookie.md)
- [TaintedCustom](issues/TaintedCustom.md)
- [TaintedEval](issues/TaintedEval.md)
- [TaintedExtract](issues/TaintedExtract.md)
- [TaintedFile](issues/TaintedFile.md)
- [TaintedHeader](issues/TaintedHeader.md)
- [TaintedHtml](issues/TaintedHtml.md)
- [TaintedInclude](issues/TaintedInclude.md)
- [TaintedInput](issues/TaintedInput.md)
- [TaintedLdap](issues/TaintedLdap.md)
- [TaintedLlmPrompt](issues/TaintedLlmPrompt.md)
- [TaintedNosql](issues/TaintedNosql.md)
- [TaintedShell](issues/TaintedShell.md)
- [TaintedSleep](issues/TaintedSleep.md)
- [TaintedSql](issues/TaintedSql.md)
- [TaintedSSRF](issues/TaintedSSRF.md)
- [TaintedSystemSecret](issues/TaintedSystemSecret.md)
- [TaintedTextWithQuotes](issues/TaintedTextWithQuotes.md)
- [TaintedUnserialize](issues/TaintedUnserialize.md)
- [TaintedUrlComponent](issues/TaintedUrlComponent.md)
- [TaintedUrlPath](issues/TaintedUrlPath.md)
- [TaintedUserSecret](issues/TaintedUserSecret.md)
- [TaintedXpath](issues/TaintedXpath.md)
- [TooFewArguments](issues/TooFewArguments.md)
- [TooManyArguments](issues/TooManyArguments.md)
- [TooManyTemplateParams](issues/TooManyTemplateParams.md)
- [Trace](issues/Trace.md)
- [TraitMethodSignatureMismatch](issues/TraitMethodSignatureMismatch.md)
- [TypeDoesNotContainNull](issues/TypeDoesNotContainNull.md)
- [TypeDoesNotContainType](issues/TypeDoesNotContainType.md)
- [UncaughtThrowInGlobalScope](issues/UncaughtThrowInGlobalScope.md)
- [UndefinedAttributeClass](issues/UndefinedAttributeClass.md)
- [UndefinedClass](issues/UndefinedClass.md)
- [UndefinedConstant](issues/UndefinedConstant.md)
- [UndefinedDocblockClass](issues/UndefinedDocblockClass.md)
- [UndefinedFunction](issues/UndefinedFunction.md)
- [UndefinedGlobalVariable](issues/UndefinedGlobalVariable.md)
- [UndefinedInterface](issues/UndefinedInterface.md)
- [UndefinedInterfaceMethod](issues/UndefinedInterfaceMethod.md)
- [UndefinedMagicMethod](issues/UndefinedMagicMethod.md)
- [UndefinedMagicPropertyAssignment](issues/UndefinedMagicPropertyAssignment.md)
- [UndefinedMagicPropertyFetch](issues/UndefinedMagicPropertyFetch.md)
- [UndefinedMethod](issues/UndefinedMethod.md)
- [UndefinedPropertyAssignment](issues/UndefinedPropertyAssignment.md)
- [UndefinedPropertyFetch](issues/UndefinedPropertyFetch.md)
- [UndefinedThisPropertyAssignment](issues/UndefinedThisPropertyAssignment.md)
- [UndefinedThisPropertyFetch](issues/UndefinedThisPropertyFetch.md)
- [UndefinedTrace](issues/UndefinedTrace.md)
- [UndefinedTrait](issues/UndefinedTrait.md)
- [UndefinedVariable](issues/UndefinedVariable.md)
- [UnevaluatedCode](issues/UnevaluatedCode.md)
- [UnhandledMatchCondition](issues/UnhandledMatchCondition.md)
- [UnimplementedAbstractMethod](issues/UnimplementedAbstractMethod.md)
- [UnimplementedInterfaceMethod](issues/UnimplementedInterfaceMethod.md)
- [UninitializedProperty](issues/UninitializedProperty.md)
- [UnnecessaryVarAnnotation](issues/UnnecessaryVarAnnotation.md)
- [UnrecognizedExpression](issues/UnrecognizedExpression.md)
- [UnrecognizedStatement](issues/UnrecognizedStatement.md)
- [UnresolvableConstant](issues/UnresolvableConstant.md)
- [UnresolvableInclude](issues/UnresolvableInclude.md)
- [UnsafeGenericInstantiation](issues/UnsafeGenericInstantiation.md)
- [UnsafeInstantiation](issues/UnsafeInstantiation.md)
- [UnsupportedPropertyReferenceUsage](issues/UnsupportedPropertyReferenceUsage.md)
- [UnsupportedReferenceUsage](issues/UnsupportedReferenceUsage.md)
- [UnusedBaselineEntry](issues/UnusedBaselineEntry.md)
- [UnusedClass](issues/UnusedClass.md)
- [UnusedClosureParam](issues/UnusedClosureParam.md)
- [UnusedConstructor](issues/UnusedConstructor.md)
- [UnusedDocblockParam](issues/UnusedDocblockParam.md)
- [UnusedForeachValue](issues/UnusedForeachValue.md)
- [UnusedFunctionCall](issues/UnusedFunctionCall.md)
- [UnusedIssueHandlerSuppression](issues/UnusedIssueHandlerSuppression.md)
- [UnusedMethod](issues/UnusedMethod.md)
- [UnusedMethodCall](issues/UnusedMethodCall.md)
- [UnusedParam](issues/UnusedParam.md)
- [UnusedProperty](issues/UnusedProperty.md)
- [UnusedPsalmSuppress](issues/UnusedPsalmSuppress.md)
- [UnusedReturnValue](issues/UnusedReturnValue.md)
- [UnusedVariable](issues/UnusedVariable.md)
---
### Running Psalm Language Server (`docs/running_psalm/language_server.md`)
# Using Psalm’s Language Server
Psalm now has built-in Language Server Compatibility support so you can run it in your favourite IDE.
It currently supports diagnostics (i.e. finding errors and warnings), go-to-definition and hover, with limited support for autocompletion (PRs are welcome!).
It works well in a variety of editors (listed alphabetically):
## Client configuration
### Emacs
I got it working with [eglot](https://github.com/joaotavora/eglot)
This is the config I used:
```
(when (file-exists-p "vendor/bin/psalm-language-server")
(progn
(require 'php-mode)
(require 'eglot)
(add-to-list 'eglot-server-programs '(php-mode . ("php" "vendor/bin/psalm-language-server")))
(add-hook 'php-mode-hook 'eglot-ensure)
(advice-add 'eglot-eldoc-function :around
(lambda (oldfun)
(let ((help (help-at-pt-kbd-string)))
(if help (message "%s" help) (funcall oldfun)))))
)
)
```
### PhpStorm
#### Native Support
As of PhpStorm 2020.3 support for psalm is supported and on by default, you can read more about that [here](https://www.jetbrains.com/help/phpstorm/using-psalm.html)
#### With LSP
Alternatively, psalm works with `gtache/intellij-lsp` plugin ([Jetbrains-approved version](https://plugins.jetbrains.com/plugin/10209-lsp-support), [latest version](https://github.com/gtache/intellij-lsp/releases/tag/v1.6.0)).
Setup is done via a GUI.
When you install the plugin, you should see a "Language Server Protocol" section under the "Languages & Frameworks" tab.
In the "Server definitions" tab you should add a definition for Psalm:
- Select `Executable`
- Extension: `php`
- Path: `` e.g. `/usr/local/bin/php` or `C:\php\php.exe`
- this should be an absolute path, not just `php`
- Args: `vendor/bin/psalm-language-server` (on Windows use `vendor/vimeo/psalm/psalm-language-server`, or for a 'global' install '%APPDATA%' + `\Composer\vendor\vimeo\psalm\psalm-language-server`, where the '%APPDATA%' environment variable is probably something like `C:\Users\\AppData\Roaming\`)
In the "Timeouts" tab you can adjust the initialization timeout. This is important if you have a large project. You should set the "Init" value to the number of milliseconds you allow Psalm to scan your entire project and your project's dependencies. For opening a couple of projects that use large PHP frameworks, on a high-end business laptop, try `240000` milliseconds for Init.
### Sublime Text
I use the excellent Sublime [LSP plugin](https://github.com/tomv564/LSP) with the following config(Package Settings > LSP > Settings):
```json
"clients": {
"psalm": {
"command": ["php", "vendor/bin/psalm-language-server"],
"selector": "source.php | embedding.php",
"enabled": true
}
}
```
### Vim & Neovim
**ALE**
[ALE](https://github.com/w0rp/ale) has support for Psalm (since v2.3.0).
```vim
let g:ale_linters = { 'php': ['php', 'psalm'] }
```
**vim-lsp**
I also got it working with [vim-lsp](https://github.com/prabirshrestha/vim-lsp)
This is the config I used (for Vim):
```vim
au User lsp_setup call lsp#register_server({
\ 'name': 'psalm-language-server',
\ 'cmd': {server_info->[expand('vendor/bin/psalm-language-server')]},
\ 'allowlist': ['php'],
\ })
```
**coc.nvim**
It also works with [coc.nvim](https://github.com/neoclide/coc.nvim).
Add settings to `coc-settings.json`:
```jsonc
"languageserver": {
"psalmls": {
"command": "vendor/bin/psalm-language-server",
"filetypes": ["php"],
"rootPatterns": ["psalm.xml", "psalm.xml.dist"],
"requireRootPattern": true
}
}
```
### VS Code
[Get the Psalm plugin here](https://marketplace.visualstudio.com/items?itemName=getpsalm.psalm-vscode-plugin) (Requires VS Code 1.26+):
## Running the server in a docker container
Make sure you use `--map-folder` option. Using it without argument will map the server's CWD to the host's project root folder. You can also specify a custom mapping. For example:
```bash
docker-compose exec php /usr/share/php/psalm/psalm-language-server \
-r=/var/www/html \
--map-folder=/var/www/html:$PWD
```
---
### Security Analysis Annotations (`docs/security_analysis/annotations.md`)
# Security analysis annotations
## `@psalm-taint-source `
See [Custom taint sources](custom_taint_sources.md#taint-source-annotation).
## `@psalm-taint-sink `
See [Custom taint sinks](custom_taint_sinks.md).
## `@psalm-taint-escape `
See [Escaping tainted output](avoiding_false_positives.md#escaping-tainted-output).
## `@psalm-taint-unescape `
See [Unescaping statements](avoiding_false_negatives.md#unescaping-statements).
## Taint type complements
Wherever these annotations take a ``, `~(|)` (or `~` for one) stands
for every taint but the ones listed: the built-in ones (`user_secret` and `system_secret` too), the custom ones,
including those other annotations only register later. The ones listed may be aliases, like `input`. Write it without
spaces.
```php
] ( , [ , ] ) [ -> return ]`
See [Taint Flow](taint_flow.md#optimized-taint-flow).
Each `` is a parameter, like `$value`. With `-> return`, an `` can also be:
- `$this`: the object the method is called on
- a parameter followed by `()`, like `$compute()`: what the callables passed to that parameter return
## `@psalm-flow ( , [ , ] ) -> ::$[]` and `@psalm-flow ::$[] -> return`
See [Keyed stores](taint_flow.md#keyed-stores)
---
### Security Analysis Avoiding False Negatives (`docs/security_analysis/avoiding_false_negatives.md`)
# Avoiding false-negatives
## Unescaping statements
Post-processing previously escaped/encoded statements can cause insecure scenarios.
`@psalm-taint-unescape ` allows to declare those components insecure explicitly.
```php
', '"', '"'],
$str
);
}
$safe = htmlspecialchars($_GET['text']);
echo decode($safe);
```
---
### Security Analysis Avoiding False Positives (`docs/security_analysis/avoiding_false_positives.md`)
# Avoiding false-positives
When you run Psalm's taint analysis for the first time you may see a bunch of false-positives.
Nobody likes false-positives!
There are a number of ways you can prevent them:
## Escaping tainted input
Some operations remove taints from data – for example, wrapping `$_GET['name']` in an `htmlentities` call prevents cross-site-scripting attacks in that `$_GET` call.
Psalm allows you to remove taints via a `@psalm-taint-escape ` annotation:
```php
'], '', $str);
echo $str;
}
echoVar($_GET["text"]);
```
## Types
A value can only carry the taints its type can hold: a number or a boolean can't hold HTML, SQL or a path, a string can't be a NoSQL query document (but what `json_decode()`, `unserialize()`, `parse_str()` and the other decoders build out of it can), and a literal string (a value the code wrote, or one Psalm knows is among such values) can't hold anything the client sent. An array holds what its keys and values can: `list` holds no HTML, while the string keys of `array` can hold anything. A union holds what any of its types can hold, and `null` holds nothing.
Psalm removes the taints a value can't carry where it is cast, passed to a function, returned, or assigned to a variable or a property, using the type it infers for the value, and where PHP guarantees a type:
- casts: `(int) $_GET['id']` is only left with the taints a number can carry;
- the native type of a parameter, inside the function;
- the native return type of a function or method, for what it returns, taint sources included: a method annotated `@psalm-taint-source input` with a `string` return type never returns a NoSQL query.
```php
find(['name' => getParam('name')]); // a string can't inject query operators
echo '' . getId('id') . ''; // an int can't carry HTML
$direction = getParam('direction');
if ($direction === 'asc' || $direction === 'desc') {
echo $direction; // 'asc'|'desc' is a literal
}
```
A function that validates a value against data the code trusts can tell Psalm about it with `@psalm-assert-if-true literal-string`: once validated, the value can't hold anything the client chose.
```php
city = $city; // stored without any taint
}
```
## Conditionally escaping tainted input
A slightly modified version of the previous example is using a condition to determine whether the return value
is considered secure. Only in case function argument `$escape` is true, the corresponding annotation
`@psalm-taint-escape` is applied for taint types `html` and `has_quotes`.
```php
purify($html);
}
```
## Specializing taints in functions
For functions, methods and classes you can use the `@psalm-taint-specialize` annotation.
```php
name = $name;
}
}
/**
* @psalm-taint-specialize
*/
function echoUserName(User $user) {
echo $user->name; // Error, detected tainted input
}
$user1 = new User("Keith");
$user2 = new User($_GET["name"]);
echoUserName($user1);
```
Adding `@psalm-taint-specialize` to the class fixes the issue.
```php
name = $name;
}
}
/**
* @psalm-taint-specialize
*/
function echoUserName(User $user) {
echo $user->name; // No error
}
$user1 = new User("Keith");
$user2 = new User($_GET["name"]);
echoUserName($user1);
```
Each instance then holds its own taints, which only follow the variables the instance is assigned to. So Psalm makes sure the instance doesn't change once constructed, as the change wouldn't reach the other variables holding the same instance: its properties are readonly, and its methods can't write them. Nor can its methods write other objects, static properties or global variables, from which another instance could read back what this one wrote. To get a changed instance, create a new one, for instance by cloning it:
```php
name = $name;
return $new;
}
}
```
The classes that extend a class with `@psalm-taint-specialize` are specialized too, and held to the same rules: Psalm reports an [ImmutableDependency](../running_psalm/issues/ImmutableDependency.md) issue for those that don't have the annotation themselves.
And, because it’s form of purity enforcement, `@psalm-immutable` can also be used:
```php
name = $name;
}
}
/**
* @psalm-taint-specialize
*/
function echoUserName(User $user) {
echo $user->name; // No error
}
$user1 = new User("Keith");
$user2 = new User($_GET["name"]);
echoUserName($user1);
```
## Avoiding files in taint paths
You can also tell Psalm that you’re not interested in any taint paths that flow through certain files or directories by specifying them in your Psalm config:
```xml
```
---
### Security Analysis Custom Taint Sinks (`docs/security_analysis/custom_taint_sinks.md`)
# Custom Taint Sinks
The `@psalm-taint-sink ` annotation allows you to define a taint sink.
Any tainted value matching the given [taint type](index.md#taint-types) will be reported as an error by Psalm.
### Example
Here the `PDOWrapper` class has an `exec` method that should not receive tainted SQL, so we can prevent its insertion:
```php
$templates template names => template sources
* @psalm-taint-sink eval $templates[*]
*/
public function __construct(private array $templates) {}
}
```
Here a tainted template name is not reported, a tainted template source is.
---
### Security Analysis Custom Taint Sources (`docs/security_analysis/custom_taint_sources.md`)
# Custom Taint Sources
You can define your own taint sources with an annotation or a plugin.
## Taint source annotation
You can use the annotation `@psalm-taint-source ` to indicate a function or method that provides user input.
In the below example the `input` taint type is specified as a standin for input taints as defined in [Psalm\Type\TaintKind](https://github.com/vimeo/psalm/blob/master/src/Psalm/Type/TaintKind.php).
```php
```
A taint added to the alias `input` with `` is a kind of user input like the built-in ones:
`$_GET` and the other built-in sources of user input give it, `@psalm-taint-source input`, `@psalm-taint-sink input`
and `@psalm-taint-escape input` name it, and a value of a type that can't hold user input (a literal string, a number,
a boolean, null) can't carry it. Plugins get these taints with `Codebase::getInputTaints()`. Each of the other aliases,
`tainted` and `input_except_sleep`, holds the custom taints added to it with its own ``, and only those. A
taint without an alias, like `session_id` above, only comes from the annotations naming it
(`@psalm-taint-source session_id`), and only reaches the sinks naming it.
A taint's name is a word (letters, digits, `_` and `-`) other than those of the built-in taints.
## Custom taint plugin
For example this plugin treats all variables named `$bad_data` as taint sources.
```
/* Detailed source-code truncated for AI context efficiency. */
```
---
### Security Analysis Taint Flow (`docs/security_analysis/taint_flow.md`)
# Taint Flow
## Optimized Taint Flow
When dealing with frameworks, keeping track of the data flow might involve different layers
and even other 3rd party components. Using the `@psalm-flow` annotation allows PsalmPHP to
take a shortcut and to make a tainted data flow more explicit.
### Proxy hint
```php
return
*/
function inputOutputHandler(string $value, string ...$items): string
{
// lots of complicated magic
}
echo inputOutputHandler('first', 'second', $_GET['malicious'] ?? '');
```
The example above states, that the function parameters `$value` and `$items` are reflected
again in the return value. Thus, in case any of the input parameters to the function
`inputOutputHandler` is tainted, then the resulting return value is as well. In this
example `TaintedHtml` would be detected due to using `echo`.
### Object to return value hint
```php
return
*/
public function getBody(): string;
}
/**
* @psalm-taint-source input
*/
function fetch(): Message {
// a request to another server
}
echo fetch()->getBody();
```
`$this` in a return value hint states that what a method returns holds what the object it is called on holds: here,
the bodies of the messages `fetch()` returns are tainted, while those of the messages the code builds itself only hold
what they were given. This is useful for methods whose bodies Psalm doesn't analyze, such as those of interfaces,
stubs and vendor code. With `@psalm-taint-specialize`, each call returns what its own object holds; without it, what
any object the method is called on holds flows into what every call returns.
### Callable result to return value hint
```php
return
*/
public function get(string $key, callable $compute): mixed;
}
function show(Cache $cache): void
{
echo $cache->get('key', fn(): string => $_GET['malicious'] ?? '');
}
```
`$compute()` in a return value hint states that what the function returns holds what the callables given to `$compute`
return: the closure's body, or the function named. Here `TaintedHtml` is detected. As for `$this`, each call returns
what its own callables return only with `@psalm-taint-specialize`.
### Keyed stores
Caches, key-value stores and similar services keep what they are given out of the analyzed code, under a key. Their
methods can say so, and what is stored under a key then flows into what the reads of that key return, wherever the
code reading it is:
```php
Cache::$data[$key]
*/
public static function set(string $key, string $value): void {}
/**
* @psalm-flow Cache::$data[$key] -> return
*/
public static function get(string $key): string {}
}
function remember(string $id): void {
Cache::set('comment_' . $id, $_GET['comment'] ?? '');
}
echo Cache::get('comment_1'); // TaintedHtml
echo Cache::get('title_1'); // no issue
```
+ `($value, $other) -> Store::$data[$key]` stores the arguments given to `$value` and `$other` under the key given to
`$key`, and `Store::$data[$key] -> return` makes a call return what is stored under its key. `($compute())` stores
what the callables given to `$compute` return, as in a [return value hint](#callable-result-to-return-value-hint):
`($compute()) -> Cache::$data[$key]` for a cache computing what it stores when the key is missing.
+ A store is named like a static property, `Class::$name`. The class and the property need not exist; `self` and
`static` name the class declaring the method. The methods of other classes (a wrapper, an extension) share a store
by naming the same one.
+ `[*]` is any key: `($values) -> Store::$data[*]` for a method storing an array of keys and values, and
`Store::$data[*] -> return` for one returning what is stored under any key. `[$keys[*]]` is each key of a list, as
for `mGet(array $keys)`. In nested stores, like `Store::$data[$namespace][$key]`, only the first key tells the values
apart.
+ Keys are told apart by what the analysis knows of them: the exact keys of literal strings and class names, else how
the key starts: the start of a concatenation, of an interpolated string, of a `sprintf()` format up to its first
conversion other than `%s`, of an `implode()` of a list with a literal separator, `__CLASS__`, or what the variable
(also one a closure uses), the property of `$this`, the method of the class or the function giving the key starts
with. A property set only by its default and its constructor starts like what the constructor is given by the `new`
of the classes analyzed. The keys of a list start like all its items: those of a literal list, those assigned to it
(`$keys[] = 'lock_' . $id;`), and those of a list a method or a function builds this way and returns. A key the
analysis knows nothing of can be any key.
+ Psalm's stubs declare the keyed store of phpredis, `Redis::$data`, and that of APCu, `APCu::$data`. Plugins can
connect their own nodes to a store with `Codebase::addTaintStoreWrite()` (paths from a node into the store under
the names) and `Codebase::addTaintStoreRead()` (paths from the store to a node), with the names
`Codebase::getTaintStoreNames()` tells for an expression, for stores whose keys an annotation can't express (a
table named in an SQL query).
### Combined proxy & return value hint
```php
return
*/
function handleInput(string $value, string ...$items): string
{
// lots of complicated magic
}
echo handleInput($_GET['malicious'] ?? '');
```
The example above combines both previous examples and shows, that the `@psalm-flow` annotation
can be used multiple times. Here, it would lead to detecting both `TaintedHtml` and `TaintedShell`.
---
### Annotating Code Type Syntax Array Types (`docs/annotating_code/type_syntax/array_types.md`)
# Array types
In PHP, the `array` type is commonly used to represent three different data structures:
[List](https://en.wikipedia.org/wiki/List_(abstract_data_type)):
```php
'hello', 5 => 'goodbye'];
$b = ['a' => 'AA', 'b' => 'BB', 'c' => 'CC'];
```
Makeshift [Structs](https://en.wikipedia.org/wiki/Struct_(C_programming_language)):
```php
'Psalm', 'type' => 'tool'];
```
PHP treats all these arrays the same, essentially (though there are some optimisations under the hood for the first case).
Psalm has a few different ways to represent arrays in its type system:
## Generic arrays
Psalm uses a syntax [borrowed from Java](https://en.wikipedia.org/wiki/Generics_in_Java) that allows you to denote the types of both keys *and* values:
```php
/** @return array */
```
You can also specify that an array is non-empty with the special type `non-empty-array`.
### PHPDoc syntax
PHPDoc [allows you to specify](https://docs.phpdoc.org/guide/guides/types.html#arrays) the type of values a generic array holds with the annotation:
```php
/** @return ValueType[] */
```
In Psalm this annotation is equivalent to `@psalm-return array`.
Generic arrays encompass both _associative arrays_ and _lists_.
## Lists
(Psalm 3.6+)
Psalm supports a `list` type that represents continuous, integer-indexed arrays like `["red", "yellow", "blue"]`.
A frequent way to create a list is with the `$arr[] =` notation.
These arrays will return true to `array_is_list($arr)`(PHP 8.1+) and represent a large percentage of all array usage in PHP applications.
A `list` type is of the form `list`, where `SomeType` is any permitted [union type](union_types.md) supported by Psalm.
- `list` is a subtype of `array`
- `list` is a subtype of `array`.
List types show their value in a few ways:
```php
$arr
*/
function takesArray(array $arr) : void {
if ($arr) {
// this index may not be set
echo $arr[0];
}
}
/**
* @psalm-param list $arr
*/
function takesList(array $arr) : void {
if ($arr) {
// list indexes always start from zero,
// so a non-empty list will have an element here
echo $arr[0];
}
}
takesArray(["hello"]); // this is fine
takesArray([1 => "hello"]); // would trigger bug, without warning
takesList(["hello"]); // this is fine
takesList([1 => "hello"]); // triggers warning in Psalm
```
## Array shapes
Psalm supports a special format for arrays where the key offsets are known: array shapes, also known as "object-like arrays".
Given an array
```php
new stdClass, 28 => false];
```
Psalm will type it internally as:
```
array{0: string, 1: string, foo: stdClass, 28: false}
```
You can specify types in that format yourself, e.g.
```php
/** @return array{foo: string, bar: int} */
```
Optional keys can be denoted by a trailing `?`, e.g.:
```php
/** @return array{optional?: string, bar: int} */
```
You can use "one-line" comments (similar to PHP), e.g:
```php
/** @return array { // Array with comments.
* // Comments can be placed on their own line.
* foo: string, // An array key description.
* bar: array {, // Another array key description.
* 'foo//bar': string, // Array key with "//" in it's name.
* },
* }
*/
```
Tip: if you find yourself copying the same complex array shape over and over again to avoid `InvalidArgument` issues, try using [type aliases](utility_types.md#type-aliases), instead.
### Validating array shapes
Use [Valinor](https://github.com/CuyZ/Valinor) in strict mode to easily assert array shapes at runtime using Psalm array shape syntax (instead of manually asserting keys with isset):
```php
try {
$array = (new \CuyZ\Valinor\MapperBuilder())
->mapper()
->map(
'array{a: string, b: int}',
json_decode(file_get_contents('https://.../'), true)
);
/** @psalm-trace $array */; // array{a: string, b: int}
echo $array['a'];
echo $array['b'];
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
// Do something…
}
```
Valinor provides both runtime and static Psalm assertions with full Psalm syntax support and many other features, check out the [Valinor documentation](https://valinor.cuyz.io/latest/) for more info!
## List shapes
Starting in Psalm 5, Psalm also supports a special format for list arrays where the key offsets are known.
Given a list array
```php
` you can use other array generic types to provide more information about the open shape.
```php
// This is an open array
/** @param array{someKey: string, ...} */
// Which is the same as
/** @param array{someKey: string, ...} */
// But it can be further locked down with a shape ...
/** @return array{someKey: string, ...} */
```
## Callable arrays
An array holding a callable, like PHP's native `call_user_func()` and friends supports it:
```php
`.
---
### Annotating Code Type Syntax Atomic Types (`docs/annotating_code/type_syntax/atomic_types.md`)
# Atomic types
Atomic types are the basic building block of all type information used in Psalm. Multiple atomic types can be combined, either with [union types](union_types.md) or [intersection types](intersection_types.md). Psalm allows many different sorts of atomic types to be expressed in docblock syntax:
**Note**: you can view detailed documentation and usage examples for all atomic types by clicking on each type in the following list.
* [Scalar types](scalar_types.md)
* [bool](scalar_types.md#scalar)
* [int](scalar_types.md#scalar)
* [float](scalar_types.md#scalar)
* [string](scalar_types.md#scalar)
* [`int-range`](scalar_types.md#int-range)
* [`int-mask<1, 2, 4>`](scalar_types.md#int-mask1-2-4)
* [`int-mask-of`](scalar_types.md#int-mask-ofmyclassclass_constant_)
* [class-string and class-string<Foo>](scalar_types.md#class-string-interface-string)
* [trait-string](scalar_types.md#trait-string)
* [enum-string](scalar_types.md#enum-string)
* [callable-string](scalar_types.md#callable-string)
* [numeric-string](scalar_types.md#numeric-string)
* [literal-string](scalar_types.md#literal-string)
* [literal-int](scalar_types.md#literal-int)
* [array-key](scalar_types.md#array-key)
* [numeric](scalar_types.md#numeric)
* [scalar](scalar_types.md#scalar)
* [Object types](object_types.md)
* [object](object_types.md#unnamed-objects)
* [object{foo: string}](object_types.md#object-properties)
* [Exception, Foo\MyClass and `Foo\MyClass`](object_types.md#named-objectsmd)
* [Generator](object_types.md#generators)
* [Array types](array_types.md)
* [array<int, string>](array_types.md#generic-arrays)
* [non-empty-array](array_types.md#non-empty-array)
* [string\[\]](array_types.md#phpdoc-syntax)
* [list & non-empty-list](array_types.md#lists)
* [list<string>](array_types.md#lists)
* [array{foo: int, bar: string} and list{int, string}](array_types.md#object-like-arrays)
* [callable-array](array_types.md#callable-arrays)
* [Callable types](callable_types.md)
* [Value types](value_types.md)
* [null](value_types.md#null)
* [true, false](value_types.md#true-false)
* [6, 7.0, "forty-two" and 'forty two'](value_types.md#some_string-4-314)
* [Foo\Bar::MY_SCALAR_CONST](value_types.md#regular-class-constants)
* [Utility types](utility_types.md)
* [(T is true ? string : bool)](conditional_types.md)
* [`key-of`](utility_types.md#key-oft)
* [`value-of`](utility_types.md#value-oft)
* [`properties-of`](utility_types.md#properties-oft)
* [`class-string-map`](utility_types.md#class-string-mapt-of-foo-t)
* [`T[K]`](utility_types.md#tk)
* [Type aliases](utility_types.md#type-aliases)
* [Variable templates](utility_types.md#variable-templates)
* [Other types](other_types.md)
* [`iterable`](other_types.md)
* [void](other_types.md)
* [resource](other_types.md)
* [closed-resource](other_types.md)
* [Top and bottom types](top_bottom_types.md)
* [mixed](top_bottom_types.md#mixed)
* [never](top_bottom_types.md#never)
---
### Annotating Code Type Syntax Callable Types (`docs/annotating_code/type_syntax/callable_types.md`)
# Callable types
Psalm supports a special format for `callable`s of the form. It can also be used for annotating `Closure`.
```
callable(Type1, OptionalType2=, SpreadType3...):ReturnType
```
Adding `=` after the type implies it is optional, and suffixing with `...` implies the use of the spread operator.
Using this annotation you can specify that a given function return a `Closure` e.g.
```php
$items */
public function __construct(private array $items) {}
/**
* @param pure-callable(int, int): int $callback
* @psalm-capabilities read-props
*/
public function walk(callable $callback): int {
return array_reduce($this->items, $callback, 0);
}
}
$list = new intList([1,2,3]);
// This is ok, as the callable is pure
echo $list->walk(fn (int $c, int $v): int => $c + $v);
// This will cause an InvalidArgument error, as the closure calls an impure function
echo $list->walk(fn (int $c, int $v): int => $c + random_int(1, $v));
```
---
### Annotating Code Type Syntax Conditional Types (`docs/annotating_code/type_syntax/conditional_types.md`)
# Conditional types
Psalm supports the equivalent of TypeScript’s [conditional types](https://www.typescriptlang.org/docs/handbook/advanced-types.html#conditional-types).
Conditional types have the form:
`( is ? : )`
All conditional types must be wrapped inside brackets e.g. `(...)`
Conditional types are dependent on [template parameters](../templated_annotations.md), so you can only use them in a function where template parameters are defined.
## Example application
Let's suppose we want to make a userland implementation of PHP's numeric addition (but please never do this). You could type this with a conditional return type:
```php
createMock(Hare::class);
```
`$hare` will be an instance of a class that extends `Hare`, and implements `\PHPUnit\Framework\MockObject\MockObject`. So
`$hare` is typed as `Hare&\PHPUnit\Framework\MockObject\MockObject`. You can use this syntax whenever a value is
required to implement multiple interfaces.
Another use case is being able to merge object-like arrays:
```php
/**
* @psalm-type A=array{a: int}
* @psalm-type B=array{b: int}
*
* @param A $a
* @param B $b
*
* @return A&B
*/
function foo($a, $b) {
return $a + $b;
}
```
The returned type will contain the properties of both `A` and `B`. In other words, it will be `{a: int, b: int}`.
Intersections are only valid for lists of only *object types* and lists of only *object-like arrays*.
You can also intersect a class with an object shape to describe properties the class doesn't declare. This helps with
classes that read properties through the magic `__get` method, where Psalm can't know which properties exist:
```php
$columns */
public function __construct(private array $columns) {}
public function __get(string $name): mixed
{
return $this->columns[$name] ?? null;
}
}
/** @param Row&object{email: string} $user */
function sendWelcomeEmail(Row $user): void
{
mail($user->email, 'Welcome!', 'Thanks for signing up.');
}
```
With a plain `Row`, `$user->email` would be `mixed`. With `Row&object{email: string}` it is a `string`.
Psalm takes a property from the shape only when the class doesn't declare it. The shape takes priority over a property
that comes from a `@mixin`. A `final` class can only have undeclared properties through `__get`, so for a final class
without `__get` (its own or inherited) Psalm still reports `UndefinedPropertyFetch`.
---
### Annotating Code Type Syntax Object Types (`docs/annotating_code/type_syntax/object_types.md`)
# Object types
## Unnamed objects
`object` are examples of unnamed object types. This type is also a valid type in PHP.
## Named objects
`stdClass`, `Foo`, `Bar\Baz` etc. are examples of named object types. These types are also valid types in PHP.
## Object properties
Psalm supports specifying the properties of an object and their expected types, e.g.:
```php
/** @param object{foo: string} $obj */
function takesObject(object $obj) : string {
return $obj->foo;
}
takesObject((object) ["foo" => "hello"]);
```
Optional properties can be denoted by a trailing `?`, e.g.:
```php
/** @param object{optional?: string} */
```
## Generic object types
Psalm supports using generic object types like `ArrayObject`. Any generic object should be typehinted with appropriate [`@template` tags](../templated_annotations.md).
## Generators
Generator types support up to four parameters, e.g. `Generator`:
1. `TKey`, the type of the `yield` key - default: `mixed`
2. `TValue`, the type of the `yield` value - default: `mixed`
3. `TSend`, the type of the `send()` method's parameter - default: `mixed`
4. `TReturn`, the return type of the `getReturn()` method - default: `mixed`
`Generator` is a shorthand for `Generator`.
`Generator` is a shorthand for `Generator`.
---
### Annotating Code Type Syntax Other Types (`docs/annotating_code/type_syntax/other_types.md`)
# Other types
- `iterable` - represents the [iterable pseudo-type](https://php.net/manual/en/language.types.iterable.php). Like arrays, iterables can have type parameters e.g. `iterable`, and a purity in brackets, what iterating over them may do: `iterable[pure]` accepts arrays and `Traversable[pure]` (see [Iterators and generators](../purity_model.md#iterators-and-generators)).
- `void` - can be used in a return type when a function does not return a value.
- `resource` represents a [PHP resource](https://www.php.net/manual/en/language.types.resource.php).
- `closed-resource` represents a [PHP resource](https://www.php.net/manual/en/language.types.resource.php) that was closed (using `fclose` or another closing function).
---
### Annotating Code Type Syntax Scalar Types (`docs/annotating_code/type_syntax/scalar_types.md`)
# Scalar types
## scalar
`int`, `bool`, `float`, `string` are examples of scalar types. Scalar types represent scalar values in PHP. These types are also valid types in PHP 7.
The type `scalar` is the supertype of all scalar types.
## int-range
Integer ranges indicate an integer within a range, specified using generic syntax: `int`.
`x` and `y` must be integer numbers.
`x` can also be `min` to indicate PHP_INT_MIN, and `y` can be `max` to indicate PHP_INT_MAX.
Examples:
* `int<-1, 3>`
* `int`
* `int<1, max>` (equivalent to `positive-int`)
* `int<0, max>` (equivalent to `non-negative-int`)
* `int` (equivalent to `negative-int`)
* `int` (equivalent to `non-positive-int`)
* `int` (equivalent to `int`)
## int-mask<1, 2, 4>
Represents the type that is the result of a bitmask combination of its parameters.
`int-mask<1, 2, 4>` corresponds to `0|1|2|3|4|5|6|7`.
## int-mask-of<MyClass::CLASS_CONSTANT_*>
Represents the type that is the result of a bitmask combination of its parameters.
This is the same concept as [`int-mask`](#int-mask1-2-4) but this type is used with a reference to constants in code: `int-mask-of` will correspond to `0|1|2|3|4|5|6|7` if there are three constants called `CLASS_CONSTANT_{A,B,C}` with values 1, 2 and 4.
### Comparing masks
A value of an `int-mask` or `int-mask-of` type is a set of bits, and Psalm remembers it through `&`, `|` and `^`: `$mask & B` is a narrowed mask of the bits of `B`. A mask may only be compared by value with `0` (no bit set) or with all of its bits: any other comparison only matches one exact set of bits, where testing some bits with `($mask & B) === B` or `($mask & B) !== 0` is usually meant, and is reported as [IntMaskComparison](../../running_psalm/issues/IntMaskComparison.md).
## array-key
`array-key` is the supertype (but not a union) of `int` and `string`.
## numeric
`numeric` is a supertype of `int` or `float` or [`numeric-string`](#numeric-string).
## class-string, interface-string
Psalm supports a special meta-type for `MyClass::class` constants, `class-string`, which can be used everywhere `string` can.
For example, given a function with a `string` parameter `$class_name`, you can use the annotation `@param class-string $class_name` to tell Psalm make sure that the function is always called with a `::class` constant in that position:
```php
`](value_types.md#regular-class-constants). This tells Psalm that any matching type must either be a class string of `Foo` or one of its descendants.
## trait-string
Psalm also supports a `trait-string` annotation denoting a trait that exists.
## enum-string
Psalm also supports a `enum-string` annotation denote an enum that exists.
## callable-string
`callable-string` denotes a string value that has passed an `is_callable` check.
## numeric-string
`numeric-string` denotes a string value that has passed an `is_numeric` check.
## literal-string
`literal-string` denotes a string value that is entirely composed of strings in your application.
Examples:
- `"hello " . "world"`
- `"hello " . Person::DEFAULT_NAME`
- `implode(', ', ["one", "two"])`
- `implode(', ', [1, 2, 3])`
- `"hello " . `
Strings that don't pass this type check:
- `file_get_contents("foo.txt")`
- `$_GET["foo"]`
- `"hello " . $_GET["foo"]`
## literal-int
`literal-int` denotes an int value that is entirely composed of literal integers in your application.
Examples:
- `12`
- `12+42`
Integers that don't pass this type check:
- `(int) file_get_contents("foo.txt")`
- `(int) $_GET["foo"]`
- `((int)$_GET["foo"]) + 2`
## lowercase-string, non-empty-string, non-empty-lowercase-string
A non empty string, lowercased or both at once.
`empty` here is defined as all strings except the empty string `''`. Another type `non-falsy-string` is effectively a subtype of `non-empty-string`, and also precludes the string value `'0'`.
---
### Annotating Code Type Syntax Top Bottom Types (`docs/annotating_code/type_syntax/top_bottom_types.md`)
# Top types, bottom types
## `mixed`
This is the _top type_ in PHP's type system, and represents a lack of type information. Psalm warns about `mixed` types when the `reportMixedIssues` flag is turned on, or when you're on level 1.
## `never`
It can be aliased to `no-return` or `never-return` in docblocks. Note: it replaced the old `empty` type that used to exist in Psalm
This is the _bottom type_ in PHP's type system. It's used to describe a type that has no possible value. It can happen in multiple cases:
- the actual `never` type from PHP 8.1 (can be used in docblocks for older versions). This type can be used as a return type for functions that will never return, either because they always throw exceptions or always exit()
- a union type that has been stripped of all its possible types. (For example, if a variable is `string|int` and we perform an is_bool() check in a condition, the type of the variable in the condition will be `never` as the condition will never be entered)
- it can represent a placeholder for types yet to come — a good example is the type of the empty array `[]`, which Psalm types as `array`, the content of the array is void so it can accept any content
- it can also happen in the same context as the line above for templates that have yet to be defined
---
### Annotating Code Type Syntax Union Types (`docs/annotating_code/type_syntax/union_types.md`)
# Union Types
An annotation of the form `Type1|Type2|Type3` is a _Union Type_. `Type1`, `Type2` and `Type3` are all acceptable possible types of that union type.
`Type1`, `Type2` and `Type3` are each [atomic types](atomic_types.md).
Union types can be generated in a number of different ways, for example in ternary expressions:
```php
` evaluates to offset-type of `ARRAY_CONST` (Psalm 3.3+)
- `key-of>` evaluates to `int`
- `key-of` evaluates to `'a'|'b'|'c'`
- `key-of` evaluates to `array-key`
- `key-of` evaluates to the template param's offset-type (ensure `@template T of array`)
### Notes on template usage
If you use `key-of` with a template param, you can fulfill the type check only with these allowed methods:
- `array_keys($t)`
- `array_key_first($t)`
- `array_key_last($t)`
Currently `array_key_exists($key, $t)` **does not** infer that `$key` is of `key-of`.
```php
/**
* @template T of array
* @param T $array
* @return list>
*/
function getKeys($array) {
return array_keys($array);
}
```
## value-of<T>
(Psalm 5.0+)
The `value-of` utility returns the value-type for any [array type](array_types.md).
Some examples:
- `value-of