psalm Documentation

Technical Documentation: vimeo/psalm

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`docs/README.md`) Copy Section

About Psalm

Psalm is a static analysis tool that attempts to dig into your program and find as many type-related bugs as possible.

It has a few features that go further than other similar tools:

• Mixed type warnings
  If Psalm cannot infer a type for an expression then it uses a mixed placeholder type. mixed types can sometimes mask bugs, so keeping track of them helps you avoid a number of common pitfalls.

• Intelligent logic checks
  Psalm keeps track of logical assertions made about your code, so if ($a && $a) {} and if ($a && !$a) {} are both treated as issues. Psalm also keeps track of logical assertions made in prior code paths, preventing issues like if ($a) {} elseif ($a) {}.

• Property initialisation checks
  Psalm checks that all properties of a given object have values after the constructor is called.

• Taint analysis
  Psalm can detect security vulnerabilities in your code.

• Language Server
  Psalm has a Language Server that’s compatible with a range of different IDEs.

• Automatic fixes
  Psalm can fix many of the issues it finds automatically.

• Automatic refactoring
  Psalm can also perform simple refactors from the command line.

Example output Copy Chapter

Given a file implode_strings.php:

<?php
$a = ['foo', 'bar'];
echo implode($a, ' ');

> ./vendor/bin/psalm implode_strings.php
ERROR: InvalidArgument - somefile.php:3:14 - Argument 1 of implode expects `string`, `array` provided (see https://psalm.dev/004)

Inspirations Copy Chapter

There are two main inspirations for Psalm:

• Etsy's Phan, which uses nikic's php-ast extension to create an abstract syntax tree
• Facebook's Hack, a PHP-like language that supports many advanced typing features natively, so docblocks aren't necessary.

Index Copy Chapter

• Running Psalm:
  • Installation
  • Configuration
  • Plugins
    • Using plugins
    • Authoring plugins
    • How Psalm represents types
  • Command line usage
  • IDE support
  • Handling errors:
    • Dealing with code issues
    • Issue Types
  • Checking non-PHP files
• Security analysis:
  • Security Analysis in Psalm
  • Custom Taint Sources
  • Custom Taint Sinks
  • Avoiding false-positives
  • Avoiding false-negatives
  • Security analysis annotations
  • Taint Flow
• Annotating code:
  • Typing in Psalm
  • Supported Annotations
  • Template Annotations
  • Type Variables
  • The Purity Model
• Manipulating code:
  • Fixing code
  • Refactoring code

Contributing Index (`docs/contributing/index.md`) Copy Section

Contributing to Psalm

Psalm is made possible through the contributions of hundreds of developers.

Hopefully you can be one of them?

Getting started Copy Chapter

Here’s a rough guide to the codebase.

Here's the philosophy underpinning the Psalm’s development.

I've also put together a list of Psalm’s complexities.

Are you looking for low-hanging fruit? Here are some GitHub issues that shouldn't be too difficult to resolve.

Don’t be afraid! Copy Section

One great thing about working on Psalm is that it’s very hard to introduce any sort of type error in Psalm’s codebase. There are almost 5,000 PHPUnit tests, so the risk of you messing up (without the CI system noticing) is very small.

Why static analysis is cool Copy Section

Day-to-day PHP programming involves solving concrete problems, but they're rarely very complex. Psalm, on the other hand, attempts to solve a pretty hard collection of problems, which then allows it to detect a ton of bugs in PHP code without actually executing that code.

There's a lot of interesting theory behind the things Psalm does, too. If you want you can go very deep, though you don't need to know really any theory to improve Psalm.

Lastly, working to improve static analysis tools will also make you a better PHP developer – it'll help you think more about how values flow through your program.

Guides Copy Section

• Editing callmaps
• Adding a new issue type

Pull Requests Copy Chapter

Before you send a pull request, make sure you follow these guidelines:

Run integration checks locally: composer tests

If you're adding new features or fixing bugs, don’t forget to add tests!

Security Analysis Index (`docs/security_analysis/index.md`) Copy Section

Security Analysis in Psalm

Psalm can attempt to find connections between user-controlled input (like $_GET['name']) and places that we don’t want unescaped user-controlled input to end up (like echo "<h1>$name</h1>" by looking at the ways that data flows through your application (via assignments, function/method calls and array/property access).

You can enable this mode with the --taint-analysis command line flag.

Tainted input is anything that can be controlled, wholly or in part, by a user of your application. In taint analysis, tainted input is called a taint source.

Example sources:

• $_GET[‘id’]
• $_POST['email']
• $_COOKIE['token']

Taint analysis tracks how data flows from taint sources into taint sinks. Taint sinks are places you really don’t want untrusted data to end up.

Example sinks:

• ">
• $pdo->exec("select * from users where name='" . $name . "'")

Taint Types Copy Chapter

Psalm recognises a number of taint types by default, defined in the Psalm\Type\TaintKind 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 Copy Chapter

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.

Taint Sinks Copy Chapter

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.

Avoiding False-Positives Copy Chapter

Nobody likes to wade through a ton of false-positives – here’s a guide to avoiding them.

Limitations Copy Chapter

Taint Analysis relies on not making any mistakes when escaping values, e.g.

$sql = 'SELECT * FROM users WHERE id = ' . $mysqli->real_escape_string((string) $_GET['id']);

$html = "
  <img src=" . htmlentities((string) $_GET['img']) . " alt='' />
  <a href='" . htmlentities((string) $_GET['a1']) . "'>Link 1</a>
  <a href='" . htmlentities((string) $_GET['a2']) . "'>Line 2</a>";

// 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 type to ensure sensitive strings are defined in your application (i.e. have been written by a developer).

Security Issues Copy Chapter

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 Copy Chapter

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 Copy Chapter

Psalm supports the SARIF 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 Copy Section

GitHub code scanning can be set up by using the Psalm GitHub Action.

Alternatively, the generated SARIF file can be manually uploaded as described in the GitHub documentation.

The results will then be available in the "Security" tab of your repository.

Other SARIF compatible software Copy Section

To generate a SARIF report run Psalm with the --report flag and a .sarif extension. For example:

psalm --report=results.sarif

Debugging the taint graph Copy Chapter

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:

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`) Copy Section

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.

Examples Copy Chapter

If you have a class that verified its input is an array of strings, you can make that clear to Psalm:

<?php
/** @psalm-assert string[] $arr */
function validateStringArray(array $arr) : void {
    foreach ($arr as $s) {
        if (!is_string($s)) {
          throw new UnexpectedValueException('Invalid value ' . gettype($s));
        }
    }
}

This enables you to call the validateStringArray function on some data and have Psalm understand that the given data must be an array of strings:

<?php
function takesString(string $s) : void {}
function takesInt(int $s) : void {}

function takesArray(array $arr) : void {
    takesInt($arr[0]); // this is fine

    validateStringArray($arr);

    takesInt($arr[0]); // this is an error

    foreach ($arr as $a) {
        takesString($a); // this is fine
    }
}

Similarly, @psalm-assert-if-true and @psalm-assert-if-false will filter input if the function/method returns true and false respectively:

<?php
class A {
    public function isValid() : bool {
        return (bool) rand(0, 1);
    }
}
class B extends A {
    public function bar() : void {}
}

/**
 * @psalm-assert-if-true B $a
 */
function isValidB(A $a) : bool {
    return $a instanceof B && $a->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
/**
 * @psalm-assert !null $value
 */
function assertNotNull($value): void {
  // Some check that will mean the method will only complete if $value is not null.
}

And you can check on null values:

<?php
/**
 * @psalm-assert-if-true null $value
 */
function isNull($value): bool {
  return ($value === null);
}

Asserting return values of methods Copy Section

You can also use the @psalm-assert-if-true and @psalm-assert-if-false annotations to assert return values of
methods inside classes. As you can see, Psalm even allows you to specify multiple annotations in the same DocBlock:

<?php
class Result {
    /**
     * @var ?Exception
     */
    private $exception;

    /**
     * @psalm-assert-if-true Exception $this->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
in the config file or annotate the class as 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

/**
 * @template T
 */
class a {
    /**
     * @var list<T>
     */
    private array $data;
    /**
     * @param T $data
     */
    public function __construct($data) {
        $this->data = [$data];
    }
    /**
     * @template NewT
     * 
     * @param NewT $data
     * 
     * @psalm-this-out self<T|NewT>
     * 
     * @return void
     */
    public function addData($data) {
        /** @var self<T|NewT> $this */
        $this->data []= $data;
    }
    /**
     * @template NewT
     * 
     * @param NewT $data
     * 
     * @psalm-this-out self<NewT>
     * 
     * @return void
     */
    public function setData($data) {
        /** @var self<NewT> $this */
        $this->data = [$data];
    }
    /**
     * @psalm-if-this-is a<int>
     */
    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<int> 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<TKey|int, TValue> : $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`) Copy Section

Assertion syntax

Psalm’s assertion annotation 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 Copy Chapter

is_xxx assertions Copy Section

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
/** @psalm-assert-if-true int $x */
function custom_is_int($x) {
  return is_int($x);
}

Object type assertions Copy Section

Any class can be used as an assertion e.g.

@psalm-assert SomeObjectType $foo

Generic assertions Copy Section

Generic type parameters can also now be asserted e.g.

@psalm-assert array $foo

Negated assertions Copy Chapter

Any assertion above can be negated:

This asserts that $foo is not an int:

<?php
/** @psalm-assert !int $foo */

This asserts that $bar is not an object of type SomeObjectType:

<?php
/** @psalm-assert !SomeObjectType $bar  */

Bool assertions Copy Chapter

This asserts that $bar is true:

<?php
/** @psalm-assert true $bar  */

This asserts that $bar is not false:

<?php
/** @psalm-assert !false $bar  */

Equality assertions Copy Chapter

Psalm also supports the equivalent of assert($some_int === $other_int) in the form

<?php
/** @psalm-assert =int $some_int */

There are two differences between the above assertion and

<?php
/** @psalm-assert int $some_int */

Firstly, the negation of =int has no meaning:

<?php
/** @psalm-assert-if-true =int $x */
function equalsFive($x) {
  return is_int($x) && $x === 5;
}

function foo($y) : void {
  if (equalsFive($y)) {
    // $y is definitely an int
  } else {
    // $y might be an int, but it might not
  }
}

function bar($y) : void {
  if (is_int($y)) {
    // $y is definitely an int
  } else {
    // $y is definitely not an int
  }
}

Secondly, calling equalsFive($some_int) is not a RedundantCondition in Psalm, whereas calling is_int($some_int) is.

Annotating Code Purity Model (`docs/annotating_code/purity_model.md`) Copy Section

The Purity Model

Psalm describes what a function, method or closure may do as a set of capabilities:
permissions to perform particular side effects, such as writing a property or printing. The
model comes from Hack's contexts and capabilities.
It replaces the three fixed levels of Psalm 6 (@psalm-pure, @psalm-mutation-free and
@psalm-external-mutation-free), which are now three points in a larger space.

This page explains how the model works. The annotations are listed in
Supported Annotations. The examples only
mark the issues they are about: Psalm also suggests annotations for the unannotated code in them
(see Inferring annotations).

Capabilities Copy Chapter

Builtins touching process-wide state (mt_rand, ini_set, spl_autoload_register, …) need
write-globals instead of io.

Two names stand for the extremes: pure is the empty set, a
pure function whose result depends only on its
arguments, and impure is every capability. A set is written with | or commas:
read-props|write-this-props.

A function-like may only do something, or call something, when its own set contains every
capability that needs. Code without an annotation is impure: it may do anything, and nothing
inside it is checked.

Each name means that one capability only. Writing does not include reading, so $this->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
final class Counter {
    public static int $count = 0;
    private int $n = 0;

    /** @psalm-capabilities read-props|write-this-props */
    public function next(): int {
        return ++$this->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 Copy Section

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
final class Config {
    public string $env = "prod";
    public static ?Config $instance = null;
}

/** @psalm-capabilities read-globals */
function config(): ?Config {
    return Config::$instance;
}

/** @psalm-capabilities read-globals|write-props */
function tamper(): void {
    $config = config();
    if ($config !== null) {
        $config->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) 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 Copy Chapter

Every purity annotation is a name for a capability set:

@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 Copy Section

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
/** @psalm-type Storage = write-props|io */
final class Repo {
    /** @psalm-capabilities Storage */
    public function save(): void { echo "saved"; }
}

/** @psalm-import-type Storage from Repo */
final class Service {
    /**
     * @psalm-capabilities Storage
     * @param Closure[Storage](): void $after
     */
    public function run(Repo $repo, Closure $after): void {
        $repo->save();
        $after();
    }
}

Conditional capabilities Copy Section

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
/** @psalm-capabilities ($seed is null ? io : pure) */
function makeId(?int $seed = null): int {
    return $seed ?? random_int(0, PHP_INT_MAX);
}

/** @psalm-pure */
function fromSeed(int $seed): int {
    return makeId($seed); // fine: $seed can't be null
}

/** @psalm-pure */
function fresh(): int {
    return makeId(); // ImpureFunctionCall: The context is pure but function call on makeid requires io
}

The constructor of MongoDB\BSON\ObjectId is stubbed this way: without an id it generates one
from the clock and a counter of the process, while given an id it only validates it.

Closures Copy Section

Closures don't need an annotation. Psalm infers their capabilities from their bodies and keeps
them in their type, for example Closure[io](int): void (see
callable types). Creating a closure is not an
effect: a pure function may build and return an impure closure. Calling it, or passing it to a
parameter that expects fewer capabilities, is checked.

A closure that captures a variable by reference (use (&$x)) shares it with the enclosing
scope: reading it needs read-props and writing it write-this-props, as if it were a property
of the closure, so such a closure is not pure. The enclosing scope may still call it freely,
since the variable is its own, and only needs a capability when the variable is shared further:
write-refs for a by-reference parameter, write-globals for a global.

<?php
/**
 * @psalm-pure
 * @param list<int> $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 Copy Chapter

@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
/** @psalm-capabilities io */
final class Logger {
    public static int $level = 0;

    public function log(string $message): void {
        echo $message; // fine: the class allows io
    }

    /** @psalm-capabilities io|write-globals */
    public function setLevel(int $level): void { // ImpureFunctionCall: setLevel is marked @psalm-capabilities write-globals|io but its containing class allows fewer capabilities, @psalm-capabilities io
        self::$level = $level;
    }
}

A class extending or implementing one with a contract must have a contract that fits inside it;
otherwise Psalm reports ImmutableDependency.
A marker interface, declaring no method or property and inheriting none, is pure without an
annotation, as it does nothing; unlike an interface marked @psalm-pure, it caps none of its
implementers.
Abstract methods, and the methods of interfaces, have no body to infer anything from, so each of
them needs its own annotation, even inside a class with a contract
(MissingAbstractPureAnnotation); use
@psalm-impure for one that may do anything.

How calls are charged Copy Chapter

A caller normally needs every capability of the function-likes it calls. Two kinds of calls are
charged more precisely.

Method calls Copy Section

A method that needs write-this-props writes its own $this, which may or may not be the
caller's. The call is charged according to the receiver:

• the caller's own $this, also when a call on it of a method returning its receiver gives it
  back (see Fluent calls): write-this-props;
• an object the caller created with new, from a class whose contract needs at most
  read-props|write-this-props|write-refs, or whose constructor can't keep a reference to it:
  nothing, as nobody else can see it change;
• any other object, including a parameter, a property of $this, or an object returned by
  another call: write-props.

<?php
/** @psalm-capabilities read-props|write-this-props */
final class Counter {
    private int $n = 0;

    public function inc(): void {
        $this->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
/** @psalm-capabilities read-props|write-this-props */
final class Tally {
    public int $n = 0;

    public function inc(): void {
        $this->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
final class Greeting {
    /** @var list<string> */
    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
final class Point {
    public int $z = 0;

    public function __construct(public int $x, public int $y) {}
}

/** @psalm-pure */
function lift(int $x, int $y): Point {
    $point = new Point($x, $y);
    $point->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
final class Registered {
    /** @var list<Registered> */
    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
final class Tracked {
    /** @var list<Tracked> */
    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
/** @psalm-consistent-constructor */
class Item {
    public int $count = 0;

    /** @psalm-capabilities read-props|write-this-props */
    public function bump(): void {
        $this->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<Item> $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) is charged the same way,
except that it is never waived for a new object. A receiver reached from
global state also costs write-globals.

Fluent calls Copy Section

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.

<?php
abstract class Query {
    /** @var list<string> */
    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 Copy Section

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
final class Stats {
    public static int $n = 0;
}

/** @psalm-capabilities write-refs */
function inc(int &$i): void {
    $i++;
}

/** @psalm-capabilities write-refs */
function update(int &$ref): void {
    $local = 0;
    inc($local);    // fine: $local belongs to update()
    inc($ref);      // fine: like writing $ref directly, costs write-refs
    // both reported on the next line:
    // ImpureStaticProperty: The context is write-refs but reading a static property requires read-globals
    // ImpureFunctionCall: The context is write-refs but function call on inc requires write-globals
    inc(Stats::$n);
}

Implicit calls Copy Section

Everything a function-like does is checked, including what happens implicitly: clone calls
__clone, string interpolation and casts call __toString, $object() calls __invoke, array
access on objects calls the ArrayAccess methods, throw new and new $className call the
constructor (an unknown class may do anything), and foreach over an object calls its iteration
methods (see Iterators and generators). A callable string or array
whose target is not known may do anything, so a pure function may not call one.

Destructors Copy Section

Destroying an object calls its destructor, where the object dies. So a pure function may not
hold, in a local variable, an object it created with new whose __destruct has effects, unless
the object leaves the function (returned, stored, passed on, captured). Nor may it unset() a
variable, property or array element holding such an object, overwrite one by assigning it, or
discard one (new Guard();).

Only the declared destructors of the known classes of the dropped value count: a mixed,
object or template value is not charged. A property is assumed to hold nothing yet in its
class's constructor (and to be kept by the original in __clone), and a variable first assigned
in a loop body to hold a value like the one assigned when it is assigned again, the previous
iteration's.

Parameter default values Copy Section

Parameter default values are evaluated like in Hack: with no capabilities at all, or with
read-globals|write-globals when the function-like has write-globals, whatever else it may do.
Only function-likes without a purity annotation may use anything in a default value, so new in
the defaults of unannotated code stays free.

Purity templates Copy Chapter

Sometimes what a function does depends on what it is given: array_map() is pure when its
callback is pure. A purity template is a template parameter whose value is a capability set
instead of a type. It is declared with
@psalm-purity-template.

Binding a purity template Copy Section

Purity arguments are written in square brackets, before any type arguments, as in Hack:

• Closure[P](int): int, callable[pure](): void: the purity of a callable;
• Handler[pure], Box[io]: 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]<K, V> and @psalm-purity-template P,
constructed with a Generator[pure], is a
Foo[pure]>.

`@psalm-purity-from-template` Copy Section

@psalm-purity-from-template P 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
/** @psalm-purity-template P */
abstract class Handler {
    /**
     * @psalm-pure
     * @psalm-purity-from-template P
     */
    abstract public function handle(string $input): string;
}

/** @extends Handler[pure] */
final class Upper extends Handler {
    /** @psalm-pure */
    public function handle(string $input): string {
        return strtoupper($input);
    }
}

/** @extends Handler[io] */
final class Printer extends Handler {
    /** @psalm-capabilities io */
    public function handle(string $input): string {
        echo $input;
        return $input;
    }
}

/** @psalm-pure */
function viaUpper(Upper $handler): string {
    return $handler->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
/**
 * @psalm-pure
 * @psalm-purity-template P
 * @param Closure[P](int): int $callback
 * @psalm-purity-from-template P
 */
function apply(Closure $callback): int {
    return $callback(1);
}

/** @psalm-pure */
function usePure(): int {
    return apply(fn(int $x): int => $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
/**
 * @template T of callable(): void
 */
final class Deferred {
    /** @var T */
    private $callback;

    /**
     * @param T $callback
     * @psalm-capabilities write-this-props
     */
    public function __construct($callback) {
        $this->callback = $callback;
    }

    /**
     * @psalm-capabilities read-props
     * @psalm-purity-from-template T
     */
    public function run(): void {
        ($this->callback)();
    }
}

/**
 * @psalm-capabilities read-props
 * @param Deferred<pure-Closure(): void> $deferred
 */
function runPure(Deferred $deferred): void {
    $deferred->run(); // fine: T is a pure closure
}

The `_` shorthand Copy Section

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
/**
 * @psalm-pure
 * @param Closure[_](int): int $callback
 */
function apply(Closure $callback): int {
    return $callback(1);
}

_ may appear anywhere in a parameter's type (list<Closure[_](int): int>,
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
final class Holder {
    /**
     * @psalm-pure
     * @param Closure[_](): int $f
     */
    public function __construct(public Closure $f) {}
}

To keep the closure's purity in the property, use a class purity template instead
(@psalm-purity-template P on the class, @param Closure[P](): int $f on the constructor): then
new Holder(fn(): int => 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
/**
 * @method int run(Closure[_](): int $callback)
 */
final class Runner {
    /** @psalm-pure */
    public function __call(string $name, array $args): int { return 1; }
}

/** @psalm-pure */
function usePure(Runner $runner): int {
    return $runner->run(fn(): int => 1); // fine: the closure is pure
}

Defaults and bounds Copy Section

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
/** @psalm-purity-template write-this-props <= C(write-this-props) <= write-this-props|write-props|io */
abstract class Doer {
    public int $runs = 0;

    /**
     * @psalm-capabilities read-props
     * @psalm-purity-from-template C
     */
    public function run(): int {
        $this->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 Copy Section

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
/**
 * @template TValue
 * @psalm-purity-template TStorage(write-props) <= write-props
 * @psalm-capabilities read-props|write-this-props
 */
final class Store {
    private int $writes = 0;

    /**
     * @param array<TValue>|object $storage
     * @return ($storage is array ? Store[pure]<TValue> : Store[write-props]<TValue>)
     * @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]<int>
    $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]<mixed>
    $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<K, V>|Container[PP]<K, V> $param and @return self[$param is array ? pure : PP]<K, V>,
new Wrapper($container) takes the purity argument of $container, io for a
Container[io]<string, int>. 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 Copy Section

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.

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
/**
 * @psalm-pure
 * @param Closure[_](): int $f
 * @return Generator<int, int>
 */
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]<int, int, mixed, mixed>
        $total += $x;
    }
    return $total;
}

/**
 * @psalm-pure
 * @param Generator[io]<int, int> $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]<int, int, mixed, mixed> 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 Copy Section

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 Copy Chapter

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
/** @psalm-immutable */
interface Shape {
    /** @psalm-capabilities read-props */
    public function area(): float;
}

/** @psalm-immutable */
final class Square implements Shape {
    public function __construct(private float $side) {}

    public function area(): float { // fine: read-props, like Shape::area
        return $this->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 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 Copy Chapter

By default Psalm remembers what it knows about object properties across calls. With
rememberPropertyAssignmentsAfterCall="false",
it forgets refinements after a call, but only those the call could invalidate:

This applies to function calls, method calls, static calls and new. With
rememberPropertyAssignmentsAfterCall="false", this code reports one issue:

<?php
final class Order {
    public ?int $total = null;
    public static ?string $currency = null;
}

/** @psalm-capabilities read-globals */
function currencyIsSet(): bool {
    return Order::$currency !== null;
}

/** @psalm-capabilities write-props */
function clear(Order $order): void {
    $order->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 Copy Chapter

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: a function or method
  that could have @psalm-pure or @psalm-capabilities;
• MissingImmutableAnnotation: a class
  that could have @psalm-pure, @psalm-immutable or @psalm-capabilities;
• MissingAbstractPureAnnotation: an
  abstract method with no annotation;
• MissingInterfaceImmutableAnnotation:
  an interface with no annotation.

The first two can be fixed automatically:

vendor/bin/psalm --alter --issues=MissingPureAnnotation,MissingImmutableAnnotation

Given this code:

<?php
function slug(string $title): string { // MissingPureAnnotation: slug must be marked @psalm-pure to aid security analysis, run with --alter --issues=MissingPureAnnotation to fix this
    return strtolower(trim($title));
}

final class Cart { // MissingImmutableAnnotation: Cart must be marked @psalm-capabilities read-props|write-this-props|write-refs to aid security analysis, run with --alter --issues=MissingImmutableAnnotation to fix this
    private int $items = 0;

    public function addItem(): void { // MissingPureAnnotation: addItem must be marked @psalm-capabilities read-props|write-this-props|write-refs to aid security analysis, run with --alter --issues=MissingPureAnnotation to fix this
        $this->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 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, 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
abstract class Shape { // fine: no suggestion, as only impure covers Circle
    /** @psalm-pure */
    public function name(): string {
        return 'shape';
    }
}

final class Circle extends Shape {
    public function draw(): void {
        echo 'o';
    }
}

class Base { // MissingImmutableAnnotation: Base must be marked @psalm-capabilities read-props|write-this-props|write-refs to aid security analysis, run with --alter --issues=MissingImmutableAnnotation to fix this
    /** @psalm-pure */
    public function name(): string {
        return 'base';
    }
}

final class Child extends Base {
    private int $count = 0;

    /** @psalm-capabilities read-props|write-this-props */
    public function increment(): void {
        $this->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 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:

<issueHandlers>
    <MissingPureAnnotation errorLevel="suppress" />
    <MissingImmutableAnnotation errorLevel="suppress" />
    <MissingAbstractPureAnnotation errorLevel="suppress" />
    <MissingInterfaceImmutableAnnotation errorLevel="suppress" />
</issueHandlers>

Migrating from Psalm 6 Copy Chapter

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).
• 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).
• 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).
• 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.

Annotating Code Supported Annotations (`docs/annotating_code/supported_annotations.md`) Copy Section

Supported docblock annotations

Psalm supports a wide range of docblock annotations.

PHPDoc tags Copy Chapter

Psalm uses the following PHPDoc tags to understand your code:

• @var
  Used for specifying the types of properties and variables
• @return
  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)
• @param
  Used for specifying types of parameters passed to functions, methods and closures
• @property
  Used to specify what properties can be accessed on an object that uses __get and __set
• @property-read
  Used to specify what properties can be read on object that uses __get
• @property-write
  Used to specify what properties can be written on object that uses __set
• @method
  Used to specify which magic methods are available on object that uses __call.
• @deprecated
  Used to mark functions, methods, classes and interfaces as being deprecated
• @internal
  Used to mark classes, functions and properties that are internal to an application or library.
• @mixin
  Used to tell Psalm that the current class proxies the methods and properties of the referenced class.

Off-label usage of the `@var` tag Copy Section

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
/** @var string */
$a = $_GET['foo'];

/** @var string $b */
$b = $_GET['bar'];

function bat(): string {
    /** @var string */
    return $_GET['bat'];
}

@mixins Copy Section

Adding @mixin to a classes docblock tells Psalm that the class proxies will proxy the methods and properties of the referenced class.

class A
{
    public string $a = 'A';
 
    public function doA(): void
    {
    }
}

/**
 * @mixin A
 */
class B
{
    public string $b = 'B';

    public function doB(): void
    {
    }

    public function __call($name, $arguments)
    {
        (new A())->$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<T> is not traversed.

Psalm-specific tags Copy Chapter

There are a number of custom tags that determine how Psalm treats your code.

`@psalm-consistent-constructor` Copy Section

See UnsafeInstantiation

`@psalm-consistent-templates` Copy Section

See UnsafeGenericInstantiation

`@param-out`, `@psalm-param-out` Copy Section

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
/**
 * @param-out string $s
 */
function addFoo(?string &$s) : void {
    if ($s === null) {
        $s = "hello";
    }
    $s .= "foo";
}

`@param-closure-this`, `@psalm-param-closure-this`, `@phpstan-param-closure-this` Copy Section

This binds $this to a specific class type inside a Closure or arrow-function expression passed directly as an argument. Use it when the receiving function or method runs the callback with Closure::bind / Closure::call so that $this resolves to a different object than the caller's $this. The bound type may be a class name (including a generic type such as Box), $this, static, self, parent, or a class-level template parameter.

<?php
class Macroable {
    /**
     * @param-closure-this static $macro
     */
    public static function macro(string $name, Closure $macro): void {
        // store $macro and later run $macro->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` Copy Section

When specifying types in a format not supported by phpDocumentor (but supported by Psalm) 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` Copy Section

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
/** @return iterable<array-key,\DateTime> $f */
function getTimes(int $n): iterable {
    while ($n--) {
        yield new \DateTime();
    }
};
/**
 * @var \Datetime[] $times
 * @psalm-ignore-var
 */
$times = getTimes(3);
// this trace shows "iterable<array-key, DateTime>" instead of "array<array-key, Datetime>"
/** @psalm-trace $times */
foreach ($times as $time) {
    echo $time->format('Y-m-d H:i:s.u') . PHP_EOL;
}

`@psalm-suppress SomeIssueName` Copy Section

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
/**
 * @psalm-suppress PossiblyNullOperand
 */
function addString(?string $s) {
    echo "hello " . $s;
}

Inline example:

<?php
function addString(?string $s) {
    /** @psalm-suppress PossiblyNullOperand */
    echo "hello " . $s;
}

@psalm-suppress all can be used to suppress all issues instead of listing them individually.

Suppressing an unused-code issue (such as UnusedClass or PossiblyUnusedMethod) only silences the report for that symbol — it does not mark the symbol as used, so code that is only referenced from it is still reported as unused. Redundant @psalm-suppress annotations, in any docblock (including on classes, interfaces, traits and enums), are reported by --find-unused-psalm-suppress.

`@psalm-assert`, `@psalm-assert-if-true`, `@psalm-assert-if-false`, `@psalm-if-this-is` and `@psalm-this-out` Copy Section

See Adding assertions.

`@psalm-ignore-nullable-return` Copy Section

This can be used to tell Psalm not to worry if a function/method returns null. It’s a bit of a hack, but occasionally useful for scenarios where you either have a very high confidence of a non-null value, or some other function guarantees a non-null value for that particular code path.

<?php
class Foo {}
function takesFoo(Foo $f): void {}

/** @psalm-ignore-nullable-return */
function getFoo(): ?Foo {
  return rand(0, 10000) > 1 ? new Foo() : null;
}

takesFoo(getFoo());

`@psalm-ignore-falsable-return` Copy Section

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` Copy Section

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
/**
 * @property string $foo
 * @seal-properties
 */
class A {
     public function __get(string $name): ?string {
          if ($name === "foo") {
               return "hello";
          }
     }

     public function __set(string $name, $value): void {}
}

$a = new A();
$a->bar = 5; // this call fails

`@psalm-seal-methods`, `@psalm-no-seal-methods`, `@seal-methods`, `@no-seal-methods` Copy Section

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
/**
 * @method foo(): string
 * @seal-methods
 */
class A {
     public function __call(string $name, array $args) {
          if ($name === "foo") {
               return "hello";
          }
     }
 }

$a = new A();
$b = $a->bar(); // this call fails

`@psalm-internal` Copy Section

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
namespace A\B {
    /**
     * @internal
     * @psalm-internal A\B
     */
    class Foo { }
}

namespace A\B\C {
    class Bat {
        public function batBat(): void {
            $a = new \A\B\Foo(); // this is fine
        }
    }
}

namespace A {
    class B {
        public function batBat(): void {
            $a = new \A\B\Foo(); // this is fine
        }
    }
}

namespace A\C {
    class Bat {
        public function batBat(): void {
            $a = new \A\B\Foo(); // error
        }
    }
}

namespace X {
    class Foo {        
        /**
         * @psalm-internal Y\Bat::batBat
         */
        public static function barBar(): void {
        }
    }
}

namespace Y {
    class Bat {
        public function batBat() : void {
            \X\Foo::barBar(); // this is fine
        }
        public function fooFoo(): void {
            \X\Foo::barBar(); // error
        }
    }
}

`@psalm-readonly` and `@readonly` Copy Section

Used to annotate a property that can only be written to in its defining class's constructor.

<?php
class B {
  /** @readonly */
  public string $s;

  public function __construct(string $s) {
    $this->s = $s;
  }
}

$b = new B("hello");
echo $b->s;
$b->s = "boo"; // disallowed

Purity and capabilities Copy Section

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
explains what each capability allows, how calls are charged and how purity templates work. The
annotations are listed below.

`@psalm-pure` and `@psalm-impure` Copy Section

@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.

`@psalm-capabilities` Copy Section

@psalm-capabilities <set> 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. On a class or interface, it is a
contract for every method of the class and of the classes
extending or implementing it. See Capabilities.

`@psalm-immutable` Copy Section

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

<?php
/**
 * @psalm-immutable
 */
abstract class Foo
{
    public string $baz;

    abstract public function bar(): int;
}

/**
 * @psalm-immutable
 */
final class ChildClass extends Foo
{
    public function __construct(string $baz)
    {
        $this->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` Copy Section

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` Copy Section

@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.

Iterators and generators Copy Section

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.

`@psalm-purity-from-template` Copy Section

@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.

`@psalm-allow-private-mutation` Copy Section

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
class Counter {
  /**
   * @readonly
   * @psalm-allow-private-mutation
   */
  public int $count = 0;

  public function increment() : void {
    $this->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` Copy Section

This is a shorthand for the property annotations @readonly and @psalm-allow-private-mutation.

<?php
class Counter {
  /**
   * @psalm-readonly-allow-private-mutation
   */
  public int $count = 0;

  public function increment() : void {
    $this->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` Copy Section

You can use this annotation to trace inferred type (applied to the next statement).

<?php

/** @psalm-trace $username */
$username = $_GET['username']; // prints something like "test.php:4 $username: mixed"

Note: it throws special low-level issue.
To see it, you can set the global errorLevel to 1, or invoke Psalm with
--show-info=true, but both these solutions will probably result in a lot of
output. Another solution is to selectively bump the error level of the issue,
so that you only get one more error:

<issueHandlers>
  <Trace errorLevel="error"/>
</issueHandlers>

`@psalm-check-type` Copy Section

You can use this annotation to ensure the inferred type matches what you expect.

<?php

/** @psalm-check-type $foo = int */
$foo = 1; // No issue

/** @psalm-check-type $bar = int */
$bar = "not-an-int"; // Checked variable $bar = int does not match $bar = 'not-an-int'

`@psalm-check-type-exact` Copy Section

Like @psalm-check-type, but checks the exact type of the variable without allowing subtypes.

<?php

/** @psalm-check-type-exact $foo = int */
$foo = 1; // Checked variable $foo = int does not match $foo = 1

`@psalm-taint-*` Copy Section

See Security Analysis annotations.

`@psalm-type` Copy Section

This allows you to define an alias for another type.

<?php
/**
 * @psalm-type PhoneType = array{phone: string}
 */
class Phone {
    /**
     * @psalm-return PhoneType
     */
    public function toArray(): array {
        return ["phone" => "Nokia"];
    }
}

`@psalm-import-type` Copy Section

You can use this annotation to import a type defined with @psalm-type if it was defined somewhere else.

<?php
/**
 * @psalm-import-type PhoneType from Phone
 */
class User {
    /**
     * @psalm-return PhoneType
     */
    public function toArray(): array {
        return array_merge([], (new Phone())->toArray());
    }
}

You can also alias a type when you import it:

<?php
/**
 * @psalm-import-type PhoneType from Phone as MyPhoneTypeAlias
 */
class User {
    /**
     * @psalm-return MyPhoneTypeAlias
     */
    public function toArray(): array {
        return array_merge([], (new Phone())->toArray());
    }
}

`@psalm-require-extends` Copy Section

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
abstract class DatabaseModel {
  // methods, properties, etc.
}

/**
 * @psalm-require-extends DatabaseModel
 */
trait SoftDeletingTrait {
  // useful but scoped functionality, that depends on methods/properties from DatabaseModel
}


class MyModel extends DatabaseModel {
  // valid
  use SoftDeletingTrait;
}

class NormalClass {
  // triggers an error
  use SoftDeletingTrait;
}

`@psalm-require-implements` Copy Section

Behaves the same way as @psalm-require-extends, but for interfaces.

Psalm also reads the @phpstan-require-implements spelling. When a docblock has both, only the @psalm-require-implements tags are used.

`@no-named-arguments` Copy Section

This will prevent access to the function or method tagged with named parameters (by emitting a NamedArgumentNotAllowed issue).

Incidentally, it will change the inferred type for the following code:

<?php
    function a(int ...$a){
        var_dump($a);
    }

The type of $a is array<array-key, int> 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` Copy Section

Instructs Psalm to ignore variable property fetch / variable method call when looking for dead code.

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 to delete Foo::$bar.

@psalm-ignore-variable-method behaves the same way, but for variable method calls.

`@psalm-yield` Copy Section

Used to specify the type of value which will be sent back to a generator when an annotated object instance is yielded.

<?php
/**
 * @template-covariant TValue
 * @psalm-yield TValue
 */
interface Promise {}

/**
 * @template-covariant TValue
 * @template-implements Promise<TValue>
 */
class Success implements Promise {
    /**
     * @psalm-param TValue $value
     */
    public function __construct($value) {}
}

/**
 * @return Promise<string>
 */
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` Copy Section

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.

/**
 * @psalm-api
 */
class UnreferencedClass {}

When an Unused* issue 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` Copy Section

Used to tell Psalm that a class can only be extended by a certain subset of classes.

For example,

<?php
/**
 * @psalm-inheritors FooClass|BarClass
 */
class BaseClass {}
class FooClass extends BaseClass {}
class BarClass extends BaseClass {}
class BazClass extends BaseClass {} // this is an error

Type Syntax Copy Chapter

Psalm supports PHPDoc’s type syntax, and also the proposed PHPDoc PSR type syntax.

A detailed write-up is found in Typing in Psalm

Annotating Code Templated Annotations (`docs/annotating_code/templated_annotations.md`) Copy Section

Templating

Docblocks allow you to tell Psalm some simple information about how your code works. For example @return int in a function return type tells Psalm that a function should return an int and @return MyContainer tells Psalm that a function should return an instance of a user-defined class MyContainer. In either case, Psalm can check that the function actually returns those types and that anything calling that function uses its returned value properly.

Templated types allow you to tell Psalm even more information about how your code works.

Let's look at a simple class MyContainer:

<?php
class MyContainer {
  private $value;

  public function __construct($value) {
    $this->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
/**
 * @template T
 */
class MyContainer {
  /** @var T */
  private $value;

  /** @param T $value */
  public function __construct($value) {
    $this->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
class One_off_instance_of_MyContainer {
  /** @var int */
  private $value;

  /** @param int $value */
  public function __construct($value) {
    $this->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` Copy Chapter

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
/**
 * @template T
 * @psalm-param T $t
 * @return T
 */
function mirror($t) {
    return $t;
}

$a = 5;
$b = mirror($a); // Psalm knows the result is an int

$c = "foo";
$d = mirror($c); // Psalm knows the result is string

Psalm also uses @template annotations in its stubbed versions of PHP array functions e.g.

<?php
/**
 * Takes one array with keys and another with values and combines them
 *
 * @template TKey
 * @template TValue
 *
 * @param array<mixed, TKey> $arr
 * @param array<mixed, TValue> $arr2
 * @return array<TKey, TValue>
 */
function array_combine(array $arr, array $arr2) {}

Notes Copy Section

• @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> Copy Chapter

Psalm also allows you to parameterize class types

<?php
/**
 * @template T of Foo
 * @psalm-param class-string<T> $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 Copy Chapter

Psalm allows you to extend templated classes with @extends/@template-extends:

<?php
/**
 * @template T
 */
class ParentClass {}

/**
 * @extends ParentClass<int>
 */
class ChildClass extends ParentClass {}

similarly you can implement interfaces with @implements/@template-implements

<?php
/**
 * @template T
 */
interface IFoo {}

/**
 * @implements IFoo<int>
 */
class Foo implements IFoo {}

and import traits with @use/@template-use

<?php
/**
 * @template T
 */
trait MyTrait {}

class Foo {
    /**
     * @use MyTrait<int>
     */
    use MyTrait;
}

You can also extend one templated class with another, e.g.

<?php
/**
 * @template T1
 */
class ParentClass {}

/**
 * @template T2
 * @extends ParentClass<T2>
 */
class ChildClass extends ParentClass {}

Template constraints Copy Chapter

You can use @template of <type> to restrict input. For example, to restrict to a given class you can use

<?php
class Foo {}
class FooChild extends Foo {}

/**
 * @template T of Foo
 * @psalm-param T $t
 * @return array<int, T>
 */
function makeArray($t) {
    return [$t];
}
$a = makeArray(new Foo()); // typed as array<int, Foo>
$b = makeArray(new FooChild()); // typed as array<int, FooChild>
$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
/**
 * @template T0 of array-key
 *
 * @template-implements IteratorAggregate<T0, int>
 */
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<T0, int, mixed, T0>
   */
  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<int>
 */
class Bar extends Foo {
  protected function getFuzzyType(int $i) : int {
    return $i;
  }
}

/**
 * @template-extends Foo<string>
 */
class Baz extends Foo {
  protected function getFuzzyType(int $i) : string {
    return static::class . '[' . $i . ']';
  }
}

Template covariance Copy Chapter

Imagine you have code like this:

<?php
class Animal {}
class Dog extends Animal {}
class Cat extends Animal {}

/**
 * @template T
 */
class Collection {
    /**
     * @var array<int, T>
     */
    public array $list;

    /**
     * @param array<int, T> $list
     */
    public function __construct(array $list) {
        $this->list = $list;
    }

    /**
     * @param T $t
     */
    public function add($t) : void {
        $this->list[] = $t;
    }
}

/**
 * @param Collection<Animal> $collection
 */
function addAnimal(Collection $collection) : void {
    $collection->add(new Cat());
}

/**
 * @param Collection<Dog> $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<Animal>, but Collection<Dog> 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
abstract class Animal {
    abstract public function getNoise() : string;
}
class Dog extends Animal {
    public function getNoise() : string { return "woof"; }
}
class Cat extends Animal {
    public function getNoise() : string { return "miaow"; }
}

/**
 * @template T
 */
class Collection {
    /** @var array<int, T> */
    public array $list = [];
}

/**
 * @param Collection<Animal> $collection
 */
function getNoises(Collection $collection) : void {
    foreach ($collection->list as $animal) {
        echo $animal->getNoise();
    }
}

/**
 * @param Collection<Dog> $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<Animal>, but Collection<Dog> 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
/**
 * @template-covariant T
 */
class Collection {
    /** @var array<int, T> */
    public array $list = [];
}

Doing this for the above example produces no errors: 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 – 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? Copy Section

Psalm has comprehensive support for declaring functional immutability.

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
/**
 * @template-covariant T
 * @psalm-immutable
 */
class Collection {
    /**
     * @var array<int, T>
     */
    public array $list = [];

    /**
     * @param array<int, T> $list
     */
    public function __construct(array $list) {
        $this->list = $list;
    }

    /**
     * @param T $t
     * @return Collection<T>
     */
    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 Copy Chapter

Psalm has support for a number of builtin classes and interfaces that you can extend/implement in your own code.

• interface Traversable<TKey, TValue>

• interface ArrayAccess<TKey, TValue>

• interface IteratorAggregate<TKey, TValue> extends Traversable<TKey, TValue>

• interface Iterator<TKey, TValue> extends Traversable<TKey, TValue>

• interface SeekableIterator<TKey, TValue> extends Iterator<TKey, TValue>

• class Generator<TKey, TValue, TSend, TReturn> extends Traversable<TKey, TValue>

• class ArrayObject<TKey, TValue> implements IteratorAggregate<TKey, TValue>, ArrayAccess<TKey, TValue>

• class ArrayIterator<TKey of array-key, TValue> implements SeekableIterator<TKey, TValue>, ArrayAccess<TKey, TValue>

• class DOMNodeList<TNode of DOMNode> implements Traversable

• class SplDoublyLinkedList<TValue> implements Iterator<TKey, TValue>, ArrayAccess<TKey, TValue>

• class SplQueue<TValue> extends SplDoublyLinkedList<TValue>

• abstract class FilterIterator<TKey, TValue, TIterator>

Annotating Code Type Variables (`docs/annotating_code/type_variables.md`) Copy Section

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 Copy Chapter

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>/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<string> 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,
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

/**
 * @template T of int|string
 */
class Box {
    /** @param T $t */
    public function __construct(public $t) {}
    /** @param T $item */
    public function set($item): void {
        $this->t = $item;
    }
}

/** @return Box<string> */
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 Copy Chapter

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<string> 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 Copy Chapter

• 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<A> 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`) Copy Section

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 Copy Chapter

Psalm allows you to express a lot of complicated type information in docblocks.

All docblock types are either atomic types, union types or intersection types.

Additionally, Psalm supports PHPDoc’s type syntax, and also the proposed PHPDoc PSR type syntax.

Property declaration types vs Assignment typehints Copy Chapter

You can use the /** @var Type */ docblock to annotate both property declarations and to help Psalm understand variable assignment.

Property declaration types Copy Section

You can specify a particular type for a class property declaration in Psalm by using the @var declaration:

<?php
/** @var string|null */
public $foo;

When checking $this->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 Copy Section

Consider the following code:

<?php
namespace YourCode {
  function bar() : int {
    $a = \ThirdParty\foo();
    return $a;
  }
}
namespace ThirdParty {
  function foo() {
    return mt_rand(0, 100);
  }
}

Psalm does not know what the third-party function ThirdParty\foo returns, because the author has not added any return types. If you know that the function returns a given value you can use an assignment typehint like so:

<?php
namespace YourCode {
  function bar() : int {
    /** @var int */
    $a = \ThirdParty\foo();
    return $a;
  }
}
namespace ThirdParty {
  function foo() {
    return mt_rand(0, 100);
  }
}

This tells Psalm that int is a possible type for $a, and allows it to infer that return $a; produces an integer.

Unlike property types, however, assignment typehints are not binding – they can be overridden by a new assignment without Psalm emitting an issue e.g.

<?php
/** @var string|null */
$a = foo();
$a = 6; // $a is now typed as an int

You can also use typehints on specific variables e.g.

<?php
/** @var string $a */
echo strpos($a, 'hello');

This tells Psalm to assume that $a is a string (though it will still throw an error if $a is undefined).

Specifying string/int options (aka enums) Copy Chapter

Psalm allows you to specify a specific set of allowed string/int values for a given function or method.

Whereas this would cause Psalm to complain that not all paths return a value:

<?php
function foo(string $s) : string {
  switch ($s) {
    case 'a':
      return 'hello';

    case 'b':
      return 'goodbye';
  }
}

If you specify the param type of $s as 'a'|'b' Psalm will know that all paths return a value:

<?php
/**
 * @param 'a'|'b' $s
 */
function foo(string $s) : string {
  switch ($s) {
    case 'a':
      return 'hello';

    case 'b':
      return 'goodbye';
  }
}

If the values are in class constants, you can use those too:

<?php
class A {
  const FOO = 'foo';
  const BAR = 'bar';
}

/**
 * @param A::FOO | A::BAR $s
 */
function foo(string $s) : string {
  switch ($s) {
    case A::FOO:
      return 'hello';

    case A::BAR:
      return 'goodbye';
  }
}

If the class constants share a common prefix, you can specify them all using a wildcard:

<?php
class A {
  const STATUS_FOO = 'foo';
  const STATUS_BAR = 'bar';
}

/**
 * @param A::STATUS_* $s
 */
function foo(string $s) : string {
  switch ($s) {
    case A::STATUS_FOO:
      return 'hello';

    default:
      // any other status
      return 'goodbye';
  }
}

Contributing Adding Issues (`docs/contributing/adding_issues.md`) Copy Section

Adding a new issue type

To add a new issue type there are a number of required steps, listed below.

Generating a new shortcode Copy Chapter

Run bin/max_used_shortcode.php and note the value it printed ($max_shortcode)

Create issue class Copy Chapter

Create a class in Psalm\Issue namespace like this:

<?php

namespace Psalm\Issue;

final class MyNewIssue extends CodeIssue 
{
    public const ERROR_LEVEL = 2;
    public const SHORTCODE = 123;
}

For SHORTCODE value use $max_shortcode + 1. To choose appropriate error level see Error levels.

There a number of abstract classes you can extend:

• CodeIssue - non-specific, default issue. It's a base class for all issues.
• ClassIssue - issue related to a specific class (also interface, trait, enum). These issues can be suppressed for specific classes in psalm.xml by using referencedClass attribute
• PropertyIssue - issue related to a specific property. Can be targeted by using referencedProperty in psalm.xml
• FunctionIssue - issue related to a specific function. Can be suppressed with referencedFunction attribute.
• ArgumentIssue - issue related to a specific argument. Can be targeted with referencedFunction attribute.
• MethodIssue - issue related to a specific method. Can be targeted with referencedMethod attribute.
• ClassConstantIssue - issue related to a specific class constant. Can be targeted with referencedConstant.
• VariableIssue - issue for a specific variable. Targeted with referencedVariable

Add a `config.xsd` entry Copy Chapter

All issue types needs to be listed in config.xsd, which is used to validate psalm.xml. Choose appropriate type attribute. E.g. for issues extending PropertyIssue use type="PropertyIssueHandlerType".

Add a doc page for your new issue Copy Chapter

Every issue needs to be documented. Create a markdown file in docs/running_psalm/issues folder. Make sure to include a snippet of code illustrating your issue. Important: snippets must use fenced php code block and must include opening PHP tag (<?php). The snippet must actually produce the issue you're documenting. It's checked by our test suite.

Add links to the doc page Copy Chapter

Add links to the doc page you created to docs/running_psalm/error_levels.md and docs/running_psalm/issues.md

Run documentation tests Copy Chapter

$ vendor/bin/phpunit tests/DocumentationTest.php

It will check whether you did all (or at least most) of the steps above.

Use your new issue type in Psalm core Copy Chapter

IssueBuffer::maybeAdd(new MyNewIssue(...))

Contributing Editing Callmaps (`docs/contributing/editing_callmaps.md`) Copy Section

Altering callmaps

Intro Copy Chapter

One of the first things most contributors start with is proposing changes to
callmaps.

Callmap is a data file (formatted as a PHP file returning an array) that tells
Psalm what arguments function/method takes and what it returns.

There is a partial callmap file in dictionaries/override/CallMap.php folder, and
a number of delta files that provide information on
how signatures changed in various PHP versions in dictionaries/override/CallMap_*_delta.php.

To alter info for a function, edit the signatures in dictionaries/override/CallMap* (adding the function if missing, copying it from dictionaries/autogen/CallMap_$latest.php).

When editing info for a function, don't forget to alter all revisions of the same function in dictionaries/override/CallMap_*_delta.php.

The callmap files in the override subfolder are then used, in conjunction with the
automatically-generated reflection callmaps in dictionaries/autogen, to generate the
final callmaps in dictionaries/CallMap_*, which are the actual callmaps in use by Psalm.

After editing an override callmap, run bin/gen_callmap.php to regenerate the final callmap file.

To also regenerate the base callmaps, run bin/gen_callmap.sh: it will use the dockerfiles in bin/
to extract types from PHP and a set of extensions.
To add types from an extension to the callmap, edit all versions of the Dockerfiles.

Full callmap format Copy Chapter

The full callmap (CallMap.php) has function/method
names as keys and an array representing the corresponding signature as a value.

First element of that value is a return type (it also doesn't have a key), and
subsequent elements represent function/method parameters. Parameter name for an
optional parameter is postfixed with =, references with &/&r_/&w_/&rw_
(depending on the read/write meaning of the reference param) and
variadic args are prefixed with ....

Callmaps also support function aliases: aliases are very useful to specify that
a certain function behaves differently according to the parameter types.

For example, the following aliases are currently in use in the callmap to specify
that the version_compare function can be called with an operator parameter,
in which case it will return a boolean; otherwise it will return an integer.

[
    'version_compare' => [
        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
function naive_version_compare(string $a, string $b, ?string $operator = null): int|bool {
    return 0;
}

$a = ["1.0", "2.0"];

// OK
usort($a, "version_compare");

// InvalidArgument: Argument 2 of usort expects callable(string, string):int, but impure-callable(string, string, null|string=):(bool|int) provided
usort($a, "naive_version_compare");

The first usort succeeds, because psalm chooses the correct alias to use between the two provided in the callmap.
The second usort fails (equivalent to the non-split return type of version_compare inferred by reflection), because the return type is a union of the two possible signatures of version_compare.

When you have multifaceted functions like these, it's a very good idea to at least define a templated stub in stubs/ for them, or a custom return type provider for even more complex logic, not representable with templates/conditional types/etc in a stub.

Also note that bin/gen_callmap.php has some validation logic which will re-add back removed parameters in overridden aliased callmaps: to avoid this, explicitly whitelist aliased functions by editing assertParameter in bin/gen_callmap_utils.php, and eventually bin/gen_callmap.php as needed.

Delta file format Copy Chapter

Delta files (named CallMap__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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

To put that into practical perspective, let's see how a couple of typical
callmap changes may look like.

Adding a new function Copy Section

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.

Correcting the function signature Copy Section

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.

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

Contributing How Psalm Works (`docs/contributing/how_psalm_works.md`) Copy Section

How Psalm works

The entry point for all analysis is ProjectAnalyzer

ProjectAnalyzer is in charge of two things: Scanning and Analysis

Scanning Copy Chapter

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 statements. PHP Parser converts PHP code into an abstract syntax tree that Psalm uses for all its analysis.

Deep scanning vs shallow scanning Copy Section

Psalm then uses a custom PHP Parser NodeVisitor called ReflectorVisitor 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
use Vendor\VendorClass;
use Vendor\OtherVendorClass;

class A extends VendorClass
{
    public function foo(OtherVendorClass $c): void {}
}

And will also deep scan the file belonging to Vendor\VendorClass, because it may have to check instantiations of properties at some point.

It will do a shallow scan of Vendor\OtherVendorClass (and any dependents) because all it cares about are the method signatures and return types of the variable $c.

Finding files from class names Copy Section

To figure out the ClassName => src/FileName.php mapping it uses reflection for project files and the Composer classmap for vendor files.

Storing data from scanning Copy Section

For each file that ReflectorVisitor visits, Psalm creates a FileStorage instance, along with ClassLikeStorage and FunctionLikeStorage 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 class and then move onto analysis.

At the end of the scanning step we have populated all the necessary information in ClassLikes, Functions and Methods classes, and created a complete list of FileStorage and ClassLikeStorage objects (in FileStorageProvider and ClassLikeStorageProvider respectively) for all classes and files used in our project.

Analysis Copy Chapter

We analyse files in FileAnalyzer

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, InterfaceAnalyzer and FunctionAnalyzer.

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 Copy Section

FunctionAnalyzer::analyze is defined in FunctionLikeAnalyzer. 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 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 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 Copy Section

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, 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`) Copy Section

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 Copy Chapter

Advantages Copy Section

• 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 Copy Section

• 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 Copy Section

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 (written in Python) can also compile to a C Python extension, 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 – written in Go. Runs much faster than Psalm (but does not support many modern PHP features)
• Ruby
  • Sorbet - written in C
• Python
  • Pyre - written in OCaml
• Hack - the typechecker is written in OCaml and Rust

Psalm's primary purpose is finding bugs Copy Chapter

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 Copy Chapter

Psalm is almost always run on PHP code that parses a lint check (php -l <filename>) – 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 Copy Chapter

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 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 Copy Chapter

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 Copy Chapter

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.

Contributing What Makes Psalm Complicated (`docs/contributing/what_makes_psalm_complicated.md`) Copy Section

Things that make developing Psalm complicated

This is a somewhat informal list that might aid others.

Type inference Copy Chapter

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 Copy Chapter

Detecting unused variables requires some fun data-flow analysis.

Detecting unused classes and methods between different runs requires maintaining references to those classes in cache (see below).

Supporting the community Copy Chapter

• 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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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`) Copy Section

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 Copy Chapter

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 Copy Chapter

You can pass in your own manipulation plugins e.g.

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 Copy Chapter

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 Copy Section

Running vendor/bin/psalter --issues=MissingReturnType --php-version=7.0 on

<?php
function foo() {
  return "hello";
}

gives

<?php
function foo() : string {
  return "hello";
}

and running vendor/bin/psalter --issues=MissingReturnType --php-version=5.6 on

<?php
function foo() {
  return "hello";
}

gives

<?php
/**
 * @return string
 */
function foo() {
  return "hello";
}

MissingClosureReturnType Copy Section

As above, except for closures

InvalidReturnType Copy Section

Running vendor/bin/psalter --issues=InvalidReturnType on

<?php
/**
 * @return int
 */
function foo() {
  return "hello";
}

gives

<?php
/**
 * @return string
 */
function foo() {
  return "hello";
}

There's also support for return typehints, so running vendor/bin/psalter --issues=InvalidReturnType on

<?php
function foo() : int {
  return "hello";
}

gives

<?php
function foo() : string {
  return "hello";
}

InvalidNullableReturnType Copy Section

Running vendor/bin/psalter --issues=InvalidNullableReturnType --php-version=7.1 on

<?php
function foo() : string {
  return rand(0, 1) ? "hello" : null;
}

gives

<?php
function foo() : ?string {
  return rand(0, 1) ? "hello" : null;
}

and running vendor/bin/psalter --issues=InvalidNullableReturnType --php-version=7.0 on

<?php
function foo() : string {
  return rand(0, 1) ? "hello" : null;
}

gives

<?php
/**
 * @return string|null
 */
function foo() {
  return rand(0, 1) ? "hello" : null;
}

InvalidFalsableReturnType Copy Section

Running vendor/bin/psalter --issues=InvalidFalsableReturnType on

<?php
function foo() : string {
  return rand(0, 1) ? "hello" : false;
}

gives

<?php
/**
 * @return string|false
 */
function foo() {
  return rand(0, 1) ? "hello" : false;
}

MissingParamType Copy Section

Running vendor/bin/psalter --issues=MissingParamType on

<?php
class C {
  public static function foo($s) : void {
    echo $s;
  }
}
C::foo("hello");

gives

<?php
class C {
  /**
   * @param string $s
   */
  public static function foo($s) : void {
    echo $s;
  }
}
C::foo("hello");

MissingPropertyType Copy Section

Running vendor/bin/psalter --issues=MissingPropertyType on

<?php
class A {
    public $foo;
    public $bar;
    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];
    }
}

gives

<?php
class A {
    /**
     * @var string|int
     */
    public $foo;

    public string $bar;

    /**
     * @var array<int, int>|null
     * @psalm-var non-empty-list<int>|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 Copy Section

Given

<?php
class A {}
class B extends A {}
class C extends A {}
class D {}

running vendor/bin/psalter --issues=MismatchingDocblockParamType on

<?php
/**
 * @param B|C $first
 * @param D $second
 */
function foo(A $first, A $second) : void {}

gives

<?php
/**
 * @param B|C $first
 * @param A $second
 */
function foo(A $first, A $second) : void {}

MismatchingDocblockReturnType Copy Section

Running vendor/bin/psalter --issues=MismatchingDocblockReturnType on

<?php
/**
 * @return int
 */
function foo() : string {
  return "hello";
}

gives

<?php
/**
 * @return string
 */
function foo() : string {
  return "hello";
}

LessSpecificReturnType Copy Section

Running vendor/bin/psalter --issues=LessSpecificReturnType on

<?php
function foo() : ?string {
  return "hello";
}

gives

<?php
function foo() : string {
  return "hello";
}

PossiblyUndefinedVariable Copy Section

Running vendor/bin/psalter --issues=PossiblyUndefinedVariable on

<?php
function foo()
{
    if (rand(0, 1)) {
      $a = 5;
    }
    echo $a;
}

gives

<?php
function foo()
{
    $a = null;
    if (rand(0, 1)) {
      $a = 5;
    }
    echo $a;
}

PossiblyUndefinedGlobalVariable Copy Section

Running vendor/bin/psalter --issues=PossiblyUndefinedGlobalVariable on

<?php
if (rand(0, 1)) {
  $a = 5;
}
echo $a;

gives

<?php
$a = null;
if (rand(0, 1)) {
  $a = 5;
}
echo $a;

UnusedMethod Copy Section

This removes private unused methods.

Running vendor/bin/psalter --issues=UnusedMethod on

<?php
class A {
    private function foo() : void {}
}

new A();

gives

<?php
class A {

}

new A();

PossiblyUnusedMethod Copy Section

This removes protected/public unused methods.

Running vendor/bin/psalter --issues=PossiblyUnusedMethod on

<?php
class A {
    protected function foo() : void {}
    public function bar() : void {}
}

new A();

gives

<?php
class A {

}

new A();

UnusedProperty Copy Section

This removes private unused properties.

Running vendor/bin/psalter --issues=UnusedProperty on

<?php
class A {
    /** @var string */
    private $foo;
}

new A();

gives

<?php
class A {

}

new A();

PossiblyUnusedProperty Copy Section

This removes protected/public unused properties.

Running vendor/bin/psalter --issues=PossiblyUnusedProperty on

<?php
class A {
    /** @var string */
    public $foo;

    /** @var string */
    protected $bar;
}

new A();

gives

<?php
class A {

}

new A();

UnusedVariable Copy Section

This removes unused variables.

Running vendor/bin/psalter --issues=UnusedVariable on

<?php
function foo(string $s) : void {
    $a = 5;
    $b = 6;
    $c = $b += $a -= intval($s);
    echo "foo";
}

gives

<?php
function foo(string $s) : void {
    echo "foo";
}

UnnecessaryVarAnnotation Copy Section

This removes unused @var annotations

Running vendor/bin/psalter --issues=UnnecessaryVarAnnotation on

<?php
function foo() : string {
    return "hello";
}

/** @var string */
$a = foo();

gives

<?php
function foo() : string {
    return "hello";
}

$a = foo();

ParamNameMismatch Copy Section

This aligns child class param names with their parent.

Running vendor/bin/psalter --issues=ParamNameMismatch on

<?php

class A {
    public function foo(string $str, bool $b = false) : void {}
}

class AChild extends A {
    public function foo(string $string, bool $b = false) : void {
        echo $string;
    }
}

gives

<?php

class A {
    public function foo(string $str, bool $b = false) : void {}
}

class AChild extends A {
    public function foo(string $str, bool $b = false) : void {
        echo $str;
    }
}

Manipulating Code Refactoring (`docs/manipulating_code/refactoring.md`) Copy Section

Refactoring Code

Sometimes you want to make big changes to your codebase like moving methods or classes.

Psalm has a refactoring tool you can access with either vendor/bin/psalm-refactor or vendor/bin/psalm --refactor, followed by appropriate commands.

Moving all classes from one namespace to another Copy Chapter

vendor/bin/psalm-refactor --move "Ns1\*" --into "Some\Other\Namespace"

This moves all classes in Ns1 (e.g. Ns1\Foo, Ns1\Baz) into the specified namespace. Files are moved as necessary.

Moving classes between namespaces Copy Chapter

vendor/bin/psalm-refactor --move "Ns1\Foo" --into "Ns2"

This tells Psalm to move class Ns1\Foo into the namespace Ns2, so any reference to Ns1\Foo becomes Ns2\Foo). Files are moved as necessary.

Moving and renaming classes Copy Chapter

vendor/bin/psalm-refactor --rename "Ns1\Foo" --to "Ns2\Bar\Baz"

This tells Psalm to move class Ns1\Foo into the namespace Ns2\Bar and rename it to Baz, so any reference to Ns1\Foo becomes Ns2\Bar\Baz). Files are moved as necessary.

Moving methods between classes Copy Chapter

vendor/bin/psalm-refactor --move "Ns1\Foo::bar" --into "Ns2\Baz"

This tells Psalm to move a method named bar inside Ns1\Foo into the class Ns2\Baz, so any reference to Ns1\Foo::bar becomes Ns2\Baz::bar). Psalm currently allows you to move static methods between arbitrary classes, and instance methods into child classes of that instance.

Moving and renaming methods Copy Chapter

vendor/bin/psalm-refactor --rename "Ns1\Foo::bar" --to "Ns2\Baz::bat"

This tells Psalm to move method Ns1\Foo::bar into the class Ns2\Baz and rename it to bat, so any reference to Ns1\Foo::bar becomes Ns2\Baz::bat).

Running Psalm Checking Non Php Files (`docs/running_psalm/checking_non_php_files.md`) Copy Section

Checking non-PHP files

Psalm supports the ability to check various PHPish files by extending the FileChecker class. For example, if you have a template where the variables are set elsewhere, Psalm can scrape those variables and check the template with those variables pre-populated.

An example TemplateChecker is provided here.

Using `psalm.xml` Copy Chapter

To ensure your custom FileChecker is used, you must update the Psalm fileExtensions config in psalm.xml:

<fileExtensions>
    <extension name=".php" />
    <extension name=".phpt" checker="path/to/TemplateChecker.php" />
</fileExtensions>

Using custom plugin Copy Chapter

Plugins can register their own custom scanner and analyzer implementations for particular file extensions.

<?php
namespace Psalm\Example;

use Psalm\Plugin\PluginEntryPointInterface;
use Psalm\Plugin\PluginFileExtensionsInterface;
use Psalm\Plugin\FileExtensionsInterface;
use Psalm\Plugin\RegistrationInterface;

class CustomPlugin implements PluginEntryPointInterface, PluginFileExtensionsInterface
{
    public function __invoke(RegistrationInterface $registration, ?\SimpleXMLElement $config = null): void
    {
        // ... regular plugin processes, stub registration, hook registration
    }

    public function processFileExtensions(FileExtensionsInterface $fileExtensions, ?SimpleXMLElement $config = null): void
    {
        $fileExtensions->addFileTypeScanner('phpt', TemplateScanner::class);
        $fileExtensions->addFileTypeAnalyzer('phpt', TemplateAnalyzer::class);
    }    
}

Running Psalm Command Line Usage (`docs/running_psalm/command_line_usage.md`) Copy Section

Running Psalm

Once you've set up your config file, you can run Psalm from your project's root directory with

./vendor/bin/psalm

and Psalm will scan all files in the project referenced by ``.

If you want to run on specific files, use

./vendor/bin/psalm file1.php [file2.php...]

Command-line options Copy Chapter

Run with --help to see a list of options that Psalm supports.

Exit status Copy Chapter

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 Copy Chapter

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 Copy Chapter

To run Psalm up to 50% faster, use the official 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.
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 Copy Chapter

Psalm now offers a psalm-review tool which allows you to manually review issues one by one in your favorite IDE.

./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:

./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`) Copy Section

Configuration

Psalm uses an XML config file (by default, psalm.xml). A barebones example looks like this:

<?xml version="1.0"?>
<psalm>
    <projectFiles>
        <directory name="src" />
    </projectFiles>
</psalm>

Configuration file may be split into several files using XInclude tags (c.f. previous example):

psalm.xml

<?xml version="1.0"?>
<psalm
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://getpsalm.org/schema/config"
    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
    xmlns:xi="http://www.w3.org/2001/XInclude"
>
    <xi:include href="files.xml"/>
</psalm>

files.xml

<?xml version="1.0" encoding="UTF-8"?>
<projectFiles xmlns="https://getpsalm.org/schema/config">
    <file name="Bar.php" />
    <file name="Bat.php" />
</projectFiles>

Different configuration file Copy Chapter

You can also create a different configuration file, then run Psalm with:

vendor/bin/psalm --config=other-psalm-config.xml

Optional <psalm /> attributes Copy Chapter

Coding style Copy Section

errorLevel

<psalm
  errorLevel="[int]"
/>

This corresponds to Psalm‘s error-detection level.

reportMixedIssues

<psalm
  reportMixedIssues="[bool]"
/>

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

<psalm
  resolveFromConfigFile="[bool]"
/>

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

<psalm
  useDocblockTypes="[bool]"
>

Whether or not to use types as defined in docblocks. Defaults to true.

useDocblockPropertyTypes

<psalm
  useDocblockPropertyTypes="[bool]"
>

If not using all docblock types, you can still use docblock property types. Defaults to false (though only relevant if useDocblockTypes is false).

docblockPropertyTypesSealProperties

<psalm
  docblockPropertyTypesSealProperties="[bool]"
>

Whether using @property in class docblocks should imply @psalm-seal-properties. Defaults to true.

usePhpDocMethodsWithoutMagicCall

<psalm
  usePhpDocMethodsWithoutMagicCall="[bool]"
>

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

<psalm
  usePhpDocPropertiesWithoutMagicCall="[bool]"
>

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

<psalm
  disableVarParsing="[bool]"
/>

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

<psalm
  strictBinaryOperands="[bool]"
>

If true we force strict typing on numerical and string operations (see https://github.com/vimeo/psalm/issues/24). Defaults to true.

allowBoolToLiteralBoolComparison

<psalm
  allowBoolToLiteralBoolComparison="[bool]"
>

If false, disallows comparing a boolean to a literal boolean (mostly a codestyle rule, not a bug detection rule; see RedundantIdentityWithTrue). Defaults to true.

rememberPropertyAssignmentsAfterCall

<psalm
  rememberPropertyAssignmentsAfterCall="[bool]"
>

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). This duplicates functionality that Hack has. Defaults to true.

allowStringToStandInForClass

<psalm
  allowStringToStandInForClass="[bool]"
>

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

<psalm
  disableSuppressAll="[bool]"
>

When true, disables wildcard suppression of all issues with @psalm-suppress all. Defaults to true.

memoizeMethodCallResults

<psalm
  memoizeMethodCallResults="[bool]"
>

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

<psalm
  hoistConstants="[bool]"
>

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

<psalm
  addParamDefaultToDocblockType="[bool]"
>

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

<psalm
  checkForThrowsDocblock="[bool]"
>

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

<psalm
  checkForThrowsInGlobalScope="[bool]"
>

When true, Psalm will check that the developer has caught every exception in global scope. Defaults to false.

ignoreInternalFunctionFalseReturn

<psalm
  ignoreInternalFunctionFalseReturn="[bool]"
>

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

<psalm
  ignoreInternalFunctionNullReturn="[bool]"
>

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

<psalm
  inferPropertyTypesFromConstructor="[bool]"
>

When true, Psalm infers property types from assignments seen in straightforward constructors. Defaults to true.

findUnusedVariablesAndParams

<psalm
  findUnusedVariablesAndParams="[bool]"
>

When true, Psalm will attempt to find all unused variables, the equivalent of running with --find-unused-variables. Defaults to false.

findUnusedCode

<psalm
  findUnusedCode="[bool]"
>

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

<psalm
  forceJit="[bool]"
>

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

<psalm
  noCache="[bool]"
>

When true, Psalm will disable usage of the cache, the equivalent of running with --no-cache. Defaults to false.

arrayCache

<psalm
  arrayCache="[bool]"
>

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

<psalm
  disallowLiteralKeysOnUnshapedArrays="[bool]"
>

When true, Psalm will emit issues when using literal keys on unshaped arrays (useful to enforce usage of shaped arrays). Defaults to false.

allFunctionsGlobal

<psalm
  allFunctionsGlobal="[bool]"
>

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

<psalm
  allConstantsGlobal="[bool]"
>

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

<psalm
  findUnusedPsalmSuppress="[bool]"
>

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

<psalm
  ensureArrayStringOffsetsExist="[bool]"
>

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

<psalm
  ensureArrayIntOffsetsExist="[bool]"
>

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

<psalm
  ensureOverrideAttribute="[bool]"
>

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

<psalm
  phpVersion="[string]"
>

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

<psalm
  skipChecksOnUnresolvableIncludes="[bool]"
>

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

<psalm
  sealAllMethods="[bool]"
>

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

<psalm
  sealAllProperties="[bool]"
>

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

<psalm
  runTaintAnalysis="[bool]"
>

When true (the default), Psalm will run Taint Analysis on your codebase. This config is the same as if you were running Psalm with --taint-analysis.

reportInfo

<psalm
  reportInfo="[bool]"
>

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

<psalm
  allowNamedArgumentCalls="[bool]"
>

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

<psalm
   triggerErrorExits="[string]"
>

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 Copy Section

autoloader

<psalm
  autoloader="[string]"
>

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

<psalm
  throwExceptionOnError="[bool]"
>

Useful in testing, this makes Psalm throw a regular-old exception when it encounters an error. Defaults to false.

hideExternalErrors

<psalm
  hideExternalErrors="[bool]"
>

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

<psalm
  hideAllErrorsExceptPassedFiles="[bool]"
>

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

<psalm
  cacheDirectory="[string]"
>

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

<psalm
  allowFileIncludes="[bool]"
>

Whether or not to allow require/include calls in your PHP. Defaults to true.

ignoreIncludeSideEffects

<psalm
  ignoreIncludeSideEffects="[bool]"
>

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

<psalm
  respectIncludeOnce="[bool]"
>

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

<psalm
  serializer="['igbinary'|'default']"
>

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

<psalm
  compressor="['lz4'|'deflate'|'off']"
>

Allows you to hard-code a compressor for Psalm's cache. By default, Psalm uses ext-zlib deflate, if it's enabled.

threads

<psalm
        threads="[int]"
>

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

<psalm
        scanThreads="[int]"
>

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

<psalm
  maxStringLength="1000"
>

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

<psalm
  maxShapedArraySize="100"
>

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

<psalm
  longScanWarning="10.0"
>

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

<psalm
  restrictReturnTypes="true"
>

Emits LessSpecificReturnType when the declared return type is not as tight as
the inferred return type.

This code:

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:

/**
 * @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":

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 when a baseline entry
is not being used to suppress an issue. Defaults to true.

findUnusedIssueHandlerSuppression

Emits UnusedIssueHandlerSuppression when a suppressed issue handler
is not being used to suppress an issue. Defaults to true.

Project settings Copy Chapter

<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.

<projectFiles>
  <directory name="src" />
  <ignoreFiles>
    <directory name="src/Stubs" />
  </ignoreFiles>
  <ignoreFiles allowMissingFiles="true">
    <directory name="path-that-may-not-exist" />
  </ignoreFiles>
</projectFiles>

<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 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.

<enableExtensions>
  <extension name="decimal"/>
  <extension name="pdo"/>
</enableExtensions>

<disableExtensions>

Optional. A list of extensions to disable. By default, only extensions required by your composer.json will be enabled.

<disableExtensions>
  <extension name="gmp"/>
</disableExtensions>

<plugins>

Optional. A list of `` entries. See the Plugins 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 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, reportMixedIssues and the baseline say.

<unsuppressibleIssues>
  
  <issue name="TaintedInput" />
  <issue name="PossiblyNullReference" />
  
  <issue name="Vendor\Plugin\Issue\SomeIssue" />
</unsuppressibleIssues>

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 reports it, and a baseline entry for one is never used either: --set-baseline and --update-baseline leave them out, and 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 <class name="Your\Namespace\ClassName" />

<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 <class name="Your\Namespace\ClassName" />. 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.
List out each file with <file name="path/to/file.php" />. 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".

<stubs>
  <file name="path/to/file.php" />
  <file name="path/to/abstract-class.php" preloadClasses="true" />
</stubs>

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 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.

<ignoreExceptions>
  <class name="fully\qualified\path\Exc" onlyGlobalScope="true" />
  <classAndDescendants name="fully\qualified\path\OtherExc" />
</ignoreExceptions>

<globals>

Optional. If your codebase uses global variables that are accessed with the global keyword, you can declare their type. e.g.

<globals>
  <var name="globalVariableName" type="type" />
</globals>

Some frameworks and libraries expose functionalities through e.g. $GLOBALS[DB]->query($query).
The following configuration declares custom types for super-globals ($GLOBALS, $_GET, ...).

<globals>
  <var name="GLOBALS" type="array{DB: MyVendor\DatabaseConnection, VIEW: MyVendor\TemplateView}" />
  <var name="_GET" type="array{data: array<string, string>}" />
</globals>

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 issue type.

<forbiddenFunctions>
  <function name="var_dump" />
  <function name="dd" />
</forbiddenFunctions>

<forbiddenConstants>

Optional. Allows you to specify a list of constants that should emit the ForbiddenCode issue type.

<forbiddenConstants>
  <constant name="FILTER_VALIDATE_URL" />
</forbiddenConstants>

<taintAnalysis>

Optional. Settings of the security analysis:

• ``: the files and directories whose taint paths are not reported (see
  Avoiding files in taint paths).
• <taints>: 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 <alias>: a taint added to input is
  user input, which the built-in sources give (see
  Custom taints declared in the configuration).

<taintAnalysis>
  <taints>
    <taint name="file_upload">
      <alias name="input" />
    </taint>
    <taint name="session_id" />
  </taints>
</taintAnalysis>

Accessing Psalm configuration in plugins Copy Chapter

Plugins can access or modify the global configuration in plugins using
singleton Psalm\Config.

$config = \Psalm\Config::getInstance();
if (!isset($config->globals['$GLOBALS'])) {
    $config->globals['$GLOBALS'] = 'array{data: array<string, string>}';
}

Running Psalm Dealing With Code Issues (`docs/running_psalm/dealing_with_code_issues.md`) Copy Section

Dealing with code issues

Psalm has a large number of code issues. 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 Copy Chapter

There are two ways to suppress an issue – via the Psalm config or via a function docblock.

Config suppression Copy Section

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.

<issueHandlers>
  <MissingPropertyType errorLevel="suppress" /> 

  <InvalidReturnType>
    <errorLevel type="suppress">
      <directory name="some_bad_directory" /> 
      <file name="some_bad_file.php" />  
    </errorLevel>
  </InvalidReturnType>
  <UndefinedMethod>
    <errorLevel type="suppress">
      <referencedMethod name="Bar\Bat::bar" /> 
      <file name="some_bad_file.php" />
    </errorLevel>
  </UndefinedMethod>
  <UndefinedClass>
    <errorLevel type="suppress">
      <referencedClass name="Bar\Bat\Baz" />
    </errorLevel>
  </UndefinedClass>
  <PropertyNotSetInConstructor>
    <errorLevel type="suppress">
        <referencedProperty name="Symfony\Component\Validator\ConstraintValidator::$context" />
    </errorLevel>
  </PropertyNotSetInConstructor>
  <UndefinedGlobalVariable>
    <errorLevel type="suppress">
      <referencedVariable name="$fooBar" /> 
    </errorLevel>
  </UndefinedGlobalVariable>
  <PluginIssue name="IssueNameEmittedByPlugin" errorLevel="info" /> 
</issueHandlers>

Docblock suppression Copy Section

You can also use @psalm-suppress IssueName on a function's docblock to suppress Psalm issues e.g.

<?php
/**
 * @psalm-suppress InvalidReturnType
 */
function (int $a) : string {
  return $a;
}

You can also suppress issues at the line level e.g.

<?php
/**
 * @psalm-suppress InvalidReturnType
 */
function (int $a) : string {
  /**
   * @psalm-suppress InvalidReturnStatement
   */
  return $a;
}

If you wish to suppress all issues, you can use @psalm-suppress all instead of multiple annotations.

The issues listed in `` can't be suppressed, neither this way nor with `` or a baseline.

Using a baseline file Copy Chapter

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 version="1.0"?>
<psalm
       ...
       errorBaseline="./path/to/your-baseline.xml"
>
   ...
</psalm>

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 Copy Chapter

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
namespace Foo\Bar;

use Psalm\Plugin\EventHandler\AfterClassLikeVisitInterface;
use Psalm\Plugin\EventHandler\Event\AfterClassLikeVisitEvent;
use ReflectionClass;

/**
 * Suppress issues dynamically based on interface implementation
 */
class DynamicallySuppressClassIssueBasedOnInterface implements AfterClassLikeVisitInterface
{
    public static function afterClassLikeVisit(AfterClassLikeVisitEvent $event)
    {
        $storage = $event->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`) Copy Section

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 Copy Section

Special categories Copy Section

• 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 Copy Chapter

These issues have very low false-positive rates and indicate definite problems. They cannot be suppressed by changing the error level.

• AbstractMethodCall
• ComplexFunction
• ComplexMethod
• ConfigIssue
• ConstantDeclarationInTrait
• DuplicateArrayKey
• DuplicateClass
• DuplicateConstant
• DuplicateEnumCase
• DuplicateEnumCaseValue
• DuplicateFunction
• DuplicateMethod
• DuplicateParam
• DuplicateProperty
• EmptyArrayAccess
• ExtensionRequirementViolation
• ImplementationRequirementViolation
• ImpureByReferenceAssignment
• ImpureFunctionCall
• ImpureGlobalVariable
• ImpureMethodCall
• ImpurePropertyAssignment
• ImpurePropertyFetch
• ImpureStaticProperty
• ImpureStaticVariable
• ImpureVariable
• InaccessibleClassConstant
• InaccessibleMethod
• InaccessibleProperty
• InterfaceInstantiation
• InvalidAttribute
• InvalidEnumBackingType
• InvalidEnumCaseValue
• InvalidEnumMethod
• InvalidExtendClass
• InvalidGlobal
• InvalidInterfaceImplementation
• InvalidParamDefault
• InvalidParent
• InvalidPassByReference
• InvalidScope
• InvalidStaticInvocation
• InvalidThrow
• LoopInvalidation
• MethodSignatureMustOmitReturnType
• MethodSignatureMustProvideReturnType
• MissingAbstractPureAnnotation
• MissingDependency
• MissingFile
• MissingImmutableAnnotation
• MissingInterfaceImmutableAnnotation
• MissingPureAnnotation
• MissingTemplateParam
• MissingThrowsDocblock
• NoEnumProperties
• NoValue
• NonInvariantPropertyType
• NonStaticSelfCall
• NullArrayAccess
• NullFunctionCall
• NullIterator
• NullPropertyAssignment
• NullPropertyFetch
• NullReference
• OverriddenPropertyAccess
• ParadoxicalCondition
• ParentNotFound
• TooFewArguments
• UndefinedAttributeClass
• UndefinedClass
• UndefinedConstant
• UndefinedDocblockClass
• UndefinedFunction
• UndefinedGlobalVariable
• UndefinedInterface
• UndefinedTrait
• UndefinedVariable
• UnimplementedAbstractMethod
• UnimplementedInterfaceMethod
• UnrecognizedExpression
• UnrecognizedStatement
• UnresolvableConstant
• UnsupportedPropertyReferenceUsage
• UnusedBaselineEntry
• UnusedFunctionCall
• UnusedIssueHandlerSuppression
• UnusedMethodCall

Errors that only appear at level 1 Copy Chapter

At the default level (2), these are reported as info. Set errorLevel="1" to treat them as errors.

• ImmutableDependency
• IncompatibleTypeParameters
• IntMaskComparison
• InvalidClassConstantType
• LessSpecificClassConstantType
• LessSpecificReturnType
• MixedArgument
• MixedArgumentTypeCoercion
• MixedArrayAccess
• MixedArrayAssignment
• MixedArrayOffset
• MixedArrayTypeCoercion
• MixedAssignment
• MixedClone
• MixedFunctionCall
• MixedMethodCall
• MixedOperand
• MixedPropertyAssignment
• MixedPropertyFetch
• MixedPropertyTypeCoercion
• MixedReturnStatement
• MixedReturnTypeCoercion
• MixedStringOffsetAssignment
• MutableDependency
• PossiblyNullOperand
• RedundantFlag
• RedundantIdentityWithTrue
• Trace

Errors at level 2 and below Copy Chapter

These issues become info (non-blocking) at level 3 and higher.

• ClassMustBeFinal
• DeprecatedClass
• DeprecatedConstant
• DeprecatedFunction
• DeprecatedInterface
• DeprecatedMethod
• DeprecatedProperty
• DeprecatedTrait
• DirectConstructorCall
• DocblockTypeContradiction
• InvalidDocblockParamName
• InvalidFalsableReturnType
• InvalidStringClass
• MismatchingDocblockPropertyType
• MissingClassConstType
• MissingClosureParamType
• MissingClosureReturnType
• MissingConstructor
• MissingParamType
• MissingPropertyType
• MissingReturnType
• NullOperand
• PrivateFinalMethod
• PropertyNotSetInConstructor
• RawObjectIteration
• RedundantCastGivenDocblockType
• RedundantConditionGivenDocblockType
• RedundantFunctionCallGivenDocblockType
• ReferenceConstraintViolation
• RiskyTruthyFalsyComparison
• UndefinedTrace
• UnresolvableInclude
• UnsafeGenericInstantiation
• UnsafeInstantiation
• UnsupportedReferenceUsage

Errors at level 3 and below Copy Chapter

These issues become info (non-blocking) at level 4 and higher.

• ArgumentTypeCoercion
• LessSpecificReturnStatement
• MoreSpecificReturnType
• NonInvariantDocblockPropertyType
• PossiblyFalseArgument
• PossiblyFalseIterator
• PossiblyFalseOperand
• PossiblyFalsePropertyAssignmentValue
• PossiblyFalseReference
• PossiblyInvalidArgument
• PossiblyInvalidArrayAccess
• PossiblyInvalidArrayAssignment
• PossiblyInvalidArrayOffset
• PossiblyInvalidCast
• PossiblyInvalidClone
• PossiblyInvalidFunctionCall
• PossiblyInvalidIterator
• PossiblyInvalidMethodCall
• PossiblyInvalidOperand
• PossiblyInvalidPropertyAssignment
• PossiblyInvalidPropertyAssignmentValue
• PossiblyInvalidPropertyFetch
• PossiblyNullArgument
• PossiblyNullArrayAccess
• PossiblyNullArrayAssignment
• PossiblyNullArrayOffset
• PossiblyNullFunctionCall
• PossiblyNullIterator
• PossiblyNullPropertyAssignment
• PossiblyNullPropertyAssignmentValue
• PossiblyNullPropertyFetch
• PossiblyNullReference
• PossiblyUndefinedArrayOffset
• PossiblyUndefinedGlobalVariable
• PossiblyUndefinedMethod
• PossiblyUndefinedVariable
• PropertyTypeCoercion
• RiskyCast

Errors at level 4 and below Copy Chapter

These issues become info (non-blocking) at level 5 and higher.

• FalseOperand
• ForbiddenCode
• IfThisIsMismatch
• ImplementedParamTypeMismatch
• ImplementedReturnTypeMismatch
• ImplicitToStringCast
• InheritorViolation
• InternalClass
• InternalMethod
• InternalProperty
• InvalidDocblock
• InvalidLiteralArgument
• InvalidOperand
• InvalidScalarArgument
• InvalidToString
• MismatchingDocblockParamType
• MismatchingDocblockReturnType
• MissingDocblockType
• NoInterfaceProperties
• PossibleRawObjectIteration
• PossiblyInvalidDocblockTag
• RedundantCast
• RedundantCondition
• RedundantFunctionCall
• RedundantPropertyInitializationCheck
• ReferenceReusedFromConfusingScope
• StringIncrement
• TooManyArguments
• TypeDoesNotContainNull
• TypeDoesNotContainType
• UndefinedMagicMethod
• UndefinedMagicPropertyAssignment
• UndefinedMagicPropertyFetch

Errors at level 5 and below Copy Chapter

These issues become info (non-blocking) at level 6 and higher.

• ConstructorSignatureMismatch
• FalsableReturnStatement
• InvalidNullableReturnType
• LessSpecificImplementedReturnType
• MoreSpecificImplementedParamType
• NullableReturnStatement
• UndefinedInterfaceMethod
• UndefinedThisPropertyAssignment

Errors at level 6 and below Copy Chapter

These issues become info (non-blocking) at level 7 and higher.

• AmbiguousConstantInheritance
• InvalidArgument
• InvalidArrayAccess
• InvalidArrayAssignment
• InvalidArrayOffset
• InvalidCast
• InvalidCatch
• InvalidClass
• InvalidClone
• InvalidConstantAssignmentValue
• InvalidFunctionCall
• InvalidIterator
• InvalidMethodCall
• InvalidNamedArgument
• InvalidPropertyAssignment
• InvalidPropertyAssignmentValue
• InvalidPropertyFetch
• InvalidReturnStatement
• InvalidReturnType
• InvalidTemplateParam
• NullArgument
• NullArrayOffset
• OverriddenFinalConstant
• OverriddenFinalProperty
• OverriddenInterfaceConstant
• TooManyTemplateParams
• TraitMethodSignatureMismatch
• UndefinedMethod
• UndefinedPropertyAssignment
• UndefinedPropertyFetch
• UndefinedThisPropertyFetch

Errors at level 7 and below Copy Chapter

These issues become info (non-blocking) at level 8.

• AbstractInstantiation
• AssignmentToVoid
• CircularReference
• ConflictingReferenceConstraint
• ContinueOutsideLoop
• InvalidOverride
• InvalidTraversableImplementation
• InvalidTypeImport
• MethodSignatureMismatch
• NamedArgumentNotAllowed
• NonVariableReferenceReturn
• OverriddenMethodAccess
• ParamNameMismatch
• ReservedWord
• UnhandledMatchCondition
• UninitializedProperty

Feature-specific errors Copy Chapter

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
• MissingOverrideAttribute
• PossiblyUndefinedIntArrayOffset
• PossiblyUndefinedStringArrayOffset
• PossiblyUnusedMethod
• PossiblyUnusedParam
• PossiblyUnusedProperty
• PossiblyUnusedReturnValue
• TaintedCallable
• TaintedCookie
• TaintedCustom
• TaintedEval
• TaintedExtract
• TaintedFile
• TaintedHeader
• TaintedHtml
• TaintedInclude
• TaintedInput
• TaintedLdap
• TaintedLlmPrompt
• TaintedNosql
• TaintedSSRF
• TaintedShell
• TaintedSleep
• TaintedSql
• TaintedSystemSecret
• TaintedTextWithQuotes
• TaintedUnserialize
• TaintedUrlComponent
• TaintedUrlPath
• TaintedUserSecret
• TaintedXpath
• UncaughtThrowInGlobalScope
• UnevaluatedCode
• UnnecessaryVarAnnotation
• UnusedClass
• UnusedClosureParam
• UnusedConstructor
• UnusedDocblockParam
• UnusedForeachValue
• UnusedMethod
• UnusedParam
• UnusedProperty
• UnusedPsalmSuppress
• UnusedReturnValue
• UnusedVariable

Running Psalm Installation (`docs/running_psalm/installation.md`) Copy Section

Installation

The latest version of Psalm requires PHP >= 8.2 and Composer.

composer require --dev vimeo/psalm

Generate a config file:

./vendor/bin/psalm --init

Psalm will scan your project and figure out an appropriate error level for your codebase.

Then run Psalm:

./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.

Docker image Copy Chapter

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

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 » 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.

Installing plugins Copy Chapter

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.
Install them with composer require --dev && vendor/bin/psalm-plugin enable

Read more about plugins in Using Plugins chapter.

Using the Phar Copy Chapter

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:

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:

composer require --dev psalm/phar

Running Psalm Issues (`docs/running_psalm/issues.md`) Copy Section

Issue types

• AbstractInstantiation
• AbstractMethodCall
• AmbiguousConstantInheritance
• ArgumentTypeCoercion
• AssignmentToVoid
• CheckType
• CircularReference
• ClassMustBeFinal
• ComplexFunction
• ComplexMethod
• ConfigIssue
• ConflictingReferenceConstraint
• ConstantDeclarationInTrait
• ConstructorSignatureMismatch
• ContinueOutsideLoop
• DeprecatedClass
• DeprecatedConstant
• DeprecatedFunction
• DeprecatedInterface
• DeprecatedMethod
• DeprecatedProperty
• DeprecatedTrait
• DirectConstructorCall
• DocblockTypeContradiction
• DuplicateArrayKey
• DuplicateClass
• DuplicateConstant
• DuplicateEnumCase
• DuplicateEnumCaseValue
• DuplicateFunction
• DuplicateMethod
• DuplicateParam
• DuplicateProperty
• EmptyArrayAccess
• ExtensionRequirementViolation
• FalsableReturnStatement
• FalseOperand
• ForbiddenCode
• IfThisIsMismatch
• ImmutableDependency
• ImplementationRequirementViolation
• ImplementedParamTypeMismatch
• ImplementedReturnTypeMismatch
• ImplicitToStringCast
• ImpureByReferenceAssignment
• ImpureFunctionCall
• ImpureGlobalVariable
• ImpureMethodCall
• ImpurePropertyAssignment
• ImpurePropertyFetch
• ImpureStaticProperty
• ImpureStaticVariable
• ImpureVariable
• InaccessibleClassConstant
• InaccessibleMethod
• InaccessibleProperty
• IncompatibleTypeParameters
• InheritorViolation
• InterfaceInstantiation
• InternalClass
• InternalMethod
• InternalProperty
• IntMaskComparison
• InvalidArgument
• InvalidArrayAccess
• InvalidArrayAssignment
• InvalidArrayOffset
• InvalidAttribute
• InvalidCast
• InvalidCatch
• InvalidClass
• InvalidClassConstantType
• InvalidClone
• InvalidConstantAssignmentValue
• InvalidDocblock
• InvalidDocblockParamName
• InvalidEnumBackingType
• InvalidEnumCaseValue
• InvalidEnumMethod
• InvalidExtendClass
• InvalidFalsableReturnType
• InvalidFunctionCall
• InvalidGlobal
• InvalidInterfaceImplementation
• InvalidIterator
• InvalidLiteralArgument
• InvalidMethodCall
• InvalidNamedArgument
• InvalidNullableReturnType
• InvalidOperand
• InvalidOverride
• InvalidParamDefault
• InvalidParent
• InvalidPassByReference
• InvalidPropertyAssignment
• InvalidPropertyAssignmentValue
• InvalidPropertyFetch
• InvalidReturnStatement
• InvalidReturnType
• InvalidScalarArgument
• InvalidScope
• InvalidStaticInvocation
• InvalidStringClass
• InvalidTemplateParam
• InvalidThrow
• InvalidToString
• InvalidTraversableImplementation
• InvalidTypeImport
• LessSpecificClassConstantType
• LessSpecificImplementedReturnType
• LessSpecificReturnStatement
• LessSpecificReturnType
• LiteralKeyUnshapedArray
• LoopInvalidation
• MethodSignatureMismatch
• MethodSignatureMustOmitReturnType
• MethodSignatureMustProvideReturnType
• MismatchingDocblockParamType
• MismatchingDocblockPropertyType
• MismatchingDocblockReturnType
• MissingAbstractPureAnnotation
• MissingClassConstType
• MissingClosureParamType
• MissingClosureReturnType
• MissingConstructor
• MissingDependency
• MissingDocblockType
• MissingFile
• MissingImmutableAnnotation
• MissingInterfaceImmutableAnnotation
• MissingOverrideAttribute
• MissingParamType
• MissingPropertyType
• MissingPureAnnotation
• MissingReturnType
• MissingTemplateParam
• MissingThrowsDocblock
• MixedArgument
• MixedArgumentTypeCoercion
• MixedArrayAccess
• MixedArrayAssignment
• MixedArrayOffset
• MixedArrayTypeCoercion
• MixedAssignment
• MixedClone
• MixedFunctionCall
• MixedMethodCall
• MixedOperand
• MixedPropertyAssignment
• MixedPropertyFetch
• MixedPropertyTypeCoercion
• MixedReturnStatement
• MixedReturnTypeCoercion
• MixedStringOffsetAssignment
• MoreSpecificImplementedParamType
• MoreSpecificReturnType
• MutableDependency
• NamedArgumentNotAllowed
• NoEnumProperties
• NoInterfaceProperties
• NonInvariantDocblockPropertyType
• NonInvariantPropertyType
• NonStaticSelfCall
• NonVariableReferenceReturn
• NoValue
• NullableReturnStatement
• NullArgument
• NullArrayAccess
• NullArrayOffset
• NullFunctionCall
• NullIterator
• NullOperand
• NullPropertyAssignment
• NullPropertyFetch
• NullReference
• OverriddenFinalConstant
• OverriddenFinalProperty
• OverriddenInterfaceConstant
• OverriddenMethodAccess
• OverriddenPropertyAccess
• ParadoxicalCondition
• ParamNameMismatch
• ParentNotFound
• ParseError
• PluginIssue
• PossibleRawObjectIteration
• PossiblyFalseArgument
• PossiblyFalseIterator
• PossiblyFalseOperand
• PossiblyFalsePropertyAssignmentValue
• PossiblyFalseReference
• PossiblyInvalidArgument
• PossiblyInvalidArrayAccess
• PossiblyInvalidArrayAssignment
• PossiblyInvalidArrayOffset
• PossiblyInvalidCast
• PossiblyInvalidClone
• PossiblyInvalidDocblockTag
• PossiblyInvalidFunctionCall
• PossiblyInvalidIterator
• PossiblyInvalidMethodCall
• PossiblyInvalidOperand
• PossiblyInvalidPropertyAssignment
• PossiblyInvalidPropertyAssignmentValue
• PossiblyInvalidPropertyFetch
• PossiblyNullArgument
• PossiblyNullArrayAccess
• PossiblyNullArrayAssignment
• PossiblyNullArrayOffset
• PossiblyNullFunctionCall
• PossiblyNullIterator
• PossiblyNullOperand
• PossiblyNullPropertyAssignment
• PossiblyNullPropertyAssignmentValue
• PossiblyNullPropertyFetch
• PossiblyNullReference
• PossiblyUndefinedArrayOffset
• PossiblyUndefinedGlobalVariable
• PossiblyUndefinedIntArrayOffset
• PossiblyUndefinedMethod
• PossiblyUndefinedStringArrayOffset
• PossiblyUndefinedVariable
• PossiblyUnusedMethod
• PossiblyUnusedParam
• PossiblyUnusedProperty
• PossiblyUnusedReturnValue
• PrivateFinalMethod
• PropertyNotSetInConstructor
• PropertyTypeCoercion
• RawObjectIteration
• RedundantCast
• RedundantCastGivenDocblockType
• RedundantCondition
• RedundantConditionGivenDocblockType
• RedundantFlag
• RedundantFunctionCall
• RedundantFunctionCallGivenDocblockType
• RedundantIdentityWithTrue
• RedundantPropertyInitializationCheck
• ReferenceConstraintViolation
• ReferenceReusedFromConfusingScope
• ReservedWord
• RiskyCast
• RiskyTruthyFalsyComparison
• StringIncrement
• TaintedCallable
• TaintedCookie
• TaintedCustom
• TaintedEval
• TaintedExtract
• TaintedFile
• TaintedHeader
• TaintedHtml
• TaintedInclude
• TaintedInput
• TaintedLdap
• TaintedLlmPrompt
• TaintedNosql
• TaintedShell
• TaintedSleep
• TaintedSql
• TaintedSSRF
• TaintedSystemSecret
• TaintedTextWithQuotes
• TaintedUnserialize
• TaintedUrlComponent
• TaintedUrlPath
• TaintedUserSecret
• TaintedXpath
• TooFewArguments
• TooManyArguments
• TooManyTemplateParams
• Trace
• TraitMethodSignatureMismatch
• TypeDoesNotContainNull
• TypeDoesNotContainType
• UncaughtThrowInGlobalScope
• UndefinedAttributeClass
• UndefinedClass
• UndefinedConstant
• UndefinedDocblockClass
• UndefinedFunction
• UndefinedGlobalVariable
• UndefinedInterface
• UndefinedInterfaceMethod
• UndefinedMagicMethod
• UndefinedMagicPropertyAssignment
• UndefinedMagicPropertyFetch
• UndefinedMethod
• UndefinedPropertyAssignment
• UndefinedPropertyFetch
• UndefinedThisPropertyAssignment
• UndefinedThisPropertyFetch
• UndefinedTrace
• UndefinedTrait
• UndefinedVariable
• UnevaluatedCode
• UnhandledMatchCondition
• UnimplementedAbstractMethod
• UnimplementedInterfaceMethod
• UninitializedProperty
• UnnecessaryVarAnnotation
• UnrecognizedExpression
• UnrecognizedStatement
• UnresolvableConstant
• UnresolvableInclude
• UnsafeGenericInstantiation
• UnsafeInstantiation
• UnsupportedPropertyReferenceUsage
• UnsupportedReferenceUsage
• UnusedBaselineEntry
• UnusedClass
• UnusedClosureParam
• UnusedConstructor
• UnusedDocblockParam
• UnusedForeachValue
• UnusedFunctionCall
• UnusedIssueHandlerSuppression
• UnusedMethod
• UnusedMethodCall
• UnusedParam
• UnusedProperty
• UnusedPsalmSuppress
• UnusedReturnValue
• UnusedVariable

Running Psalm Language Server (`docs/running_psalm/language_server.md`) Copy Section

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 Copy Chapter

Emacs Copy Section

I got it working with 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 Copy Section

Native Support

As of PhpStorm 2020.3 support for psalm is supported and on by default, you can read more about that here

With LSP

Alternatively, psalm works with gtache/intellij-lsp plugin (Jetbrains-approved version, latest version).

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\<homedir>\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 Copy Section

I use the excellent Sublime LSP plugin with the following config(Package Settings > LSP > Settings):

"clients": {
        "psalm": {
            "command": ["php", "vendor/bin/psalm-language-server"],
            "selector": "source.php | embedding.php",
            "enabled": true
        }
    }

Vim & Neovim Copy Section

ALE

ALE has support for Psalm (since v2.3.0).

let g:ale_linters = { 'php': ['php', 'psalm'] }

vim-lsp

I also got it working with vim-lsp

This is the config I used (for 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.

Add settings to coc-settings.json:

"languageserver": {
    "psalmls": {
      "command": "vendor/bin/psalm-language-server",
      "filetypes": ["php"],
      "rootPatterns": ["psalm.xml", "psalm.xml.dist"],
      "requireRootPattern": true
    }
  }

VS Code Copy Section

Get the Psalm plugin here (Requires VS Code 1.26+):

Running the server in a docker container Copy Chapter

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:

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`) Copy Section

Security analysis annotations

`@psalm-taint-source ` Copy Chapter

See Custom taint sources.

`@psalm-taint-sink ` Copy Chapter

See Custom taint sinks.

`@psalm-taint-escape ` Copy Chapter

See Escaping tainted output.

`@psalm-taint-unescape ` Copy Chapter

See Unescaping statements.

Taint type complements Copy Chapter

Wherever these annotations take a <taint-type>, ~(<taint-type>|<taint-type>) (or ~<taint-type> 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 // --taint-analysis

/**
 * Taken from the request line, which can't hold a line break: any input but a header injection
 *
 * @psalm-taint-source ~(header|user_secret|system_secret)
 */
function getRequestPath(): string {}

The taints the native types of a value can't hold are still removed from it: a string returned by
getRequestPath() above can't be a NoSQL query.

`@psalm-taint-specialize` Copy Chapter

See Specializing taints in functions and Specializing taints in classes.

`@psalm-flow [proxy ] ( , [ , ] ) [ -> return ]` Copy Chapter

See Taint Flow.

Each <arg> is a parameter, like $value. With -> return, an <arg> 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` Copy Chapter

See Keyed stores

Security Analysis Avoiding False Negatives (`docs/security_analysis/avoiding_false_negatives.md`) Copy Section

Avoiding false-negatives

Unescaping statements Copy Chapter

Post-processing previously escaped/encoded statements can cause insecure scenarios.
@psalm-taint-unescape <taint-type> allows to declare those components insecure explicitly.

<?php

/**
 * @psalm-taint-unescape html
 */
function decode(string $str): string
{
    return str_replace(
        ['&lt;', '&gt;', '&quot;', '&apos;'],
        ['<', '>', '"', '"'],
        $str
    );
}

$safe = htmlspecialchars($_GET['text']);
echo decode($safe);

Security Analysis Avoiding False Positives (`docs/security_analysis/avoiding_false_positives.md`) Copy Section

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 Copy Chapter

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 <taint-type> annotation:

<?php

function echoVar(string $str) : void {
    /**
     * @psalm-taint-escape html
     */
    $str = str_replace(['<', '>'], '', $str);
    echo $str;
}

echoVar($_GET["text"]);

Types Copy Chapter

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<string, int> 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

/** @psalm-taint-source input */
function getParam(string $name): string {
    return (string) ($_GET[$name] ?? '');
}

function getId(string $name): int {
    return (int) getParam($name);
}

$collection->find(['name' => getParam('name')]); // a string can't inject query operators
echo '<b>' . getId('id') . '</b>'; // 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

/** @psalm-assert-if-true literal-string $city */
function isKnownCity(string $city): bool {
    return in_array($city, getCityKeysFromDatabase(), true);
}

$city = getParam('city');
if (isKnownCity($city)) {
    $organization->city = $city; // stored without any taint
}

Conditionally escaping tainted input Copy Chapter

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
/**
 * @param string $str
 * @param bool $escape
 * @psalm-taint-escape ($escape is true ? 'html'|'has_quotes' : null)
 */
function processVar(string $str, bool $escape = true) : string {
    if ($escape) {
      $str = htmlspecialchars($str, ENT_QUOTES);
    }
    return $str;
}

echo processVar($_GET['text'], false); // detects tainted HTML
echo processVar($_GET['text'], true); // considered secure

Sanitizing HTML user input Copy Chapter

Whenever possible, applications should be designed to accept & store user input as discrete text fields, rather than blocks of HTML. This allows user input to be fully escaped via htmlspecialchars or htmlentities. In cases where HTML user input is required (e.g. rich text editors like TinyMCE), a library designed specifically to filter out risky HTML is highly recommended. For example, HTML Purifier could be used as follows:

<?php

/**
 * @psalm-taint-escape html
 * @psalm-taint-escape has_quotes
 */
function sanitizeHTML($html){
    $purifier = new HTMLPurifier();
    return $purifier->purify($html);
}

Specializing taints in functions Copy Chapter

For functions, methods and classes you can use the @psalm-taint-specialize annotation.

<?php

function takesInput(string $s) : string {
    error_log("Got input");
    return $s;
}

echo htmlentities(takesInput($_GET["name"]));
echo takesInput("hello"); // Psalm detects tainted HTML here

Adding a @psalm-taint-specialize annotation solves the problem, by telling Psalm that each invocation of the function should be treated separately.

<?php

/**
 * @psalm-taint-specialize
 */
function takesInput(string $s) : string {
    error_log("Got input");
    return $s;
}

echo htmlentities(takesInput($_GET["name"]));
echo takesInput("hello"); // No error

A specialized function or method will still track tainted input:

<?php

/**
 * @psalm-taint-specialize
 */
function takesInput(string $s) : string {
    return $s;
}

echo takesInput($_GET["name"]); // Psalm detects tainted input
echo takesInput("hello"); // No error

Here we’re telling Psalm that a function’s taintedness is wholly dependent on the input to the function.

If you're familiar with immutability in Psalm then this general idea should be familiar, since a pure function is one where the output is wholly dependent on its input. Unsurprisingly, all functions marked @psalm-pure also specialize the taintedness of their output based on input:

<?php

/**
 * @psalm-pure
 */
function takesInput(string $s) : string {
    return $s;
}

echo htmlentities(takesInput($_GET["name"]));
echo takesInput("hello"); // No error

Since each invocation is treated separately, a sink the input reaches through a specialized function – in its body or in a function it calls – is reported for every call that passes tainted input to it:

<?php

/**
 * @psalm-taint-specialize
 */
function run(string $command) : void {
    exec($command); // Reported twice: once for each call below
}

run($_GET["first"]);
run($_GET["second"]);

Psalm also infers the purity of functions without a purity annotation, so an unannotated function is specialized too when it turns out to be pure, as would be the first takesInput above without the error_log call. Since a method could be overridden by an impure one, this only applies to methods that cannot be overridden: private or final methods, and methods of final classes.

Specializing taints in classes Copy Chapter

Just as taints can be specialized in function calls, tainted properties can also be specialized to a given class.

<?php

class User {
    public string $name;

    public function __construct(string $name) {
        $this->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

/**
 * @psalm-taint-specialize
 */
class User {
    public string $name;

    public function __construct(string $name) {
        $this->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

/**
 * @psalm-taint-specialize
 */
class User {
    public function __construct(public string $name) {}

    public function withName(string $name): static {
        $new = clone $this;
        $new->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 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

/**
 * @psalm-immutable
 */
class User {
    public string $name;

    public function __construct(string $name) {
        $this->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 Copy Chapter

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:

<taintAnalysis>
        <ignoreFiles>
            <directory name="tests"/>
        </ignoreFiles>
    </taintAnalysis>

Security Analysis Custom Taint Sinks (`docs/security_analysis/custom_taint_sinks.md`) Copy Section

Custom Taint Sinks

The @psalm-taint-sink <taint-type> annotation allows you to define a taint sink.

Any tainted value matching the given taint type will be reported as an error by Psalm.

Example Copy Section

Here the PDOWrapper class has an exec method that should not receive tainted SQL, so we can prevent its insertion:

<?php

class PDOWrapper {
    /**
     * @psalm-taint-sink sql $sql
     */
    public function exec(string $sql) : void {}
}

Values of an array Copy Section

Append [*] to the parameter name to make only the values of the array given to the parameter a sink, not its keys:

<?php

final class TemplateLoader {
    /**
     * @param array<string, string> $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`) Copy Section

Custom Taint Sources

You can define your own taint sources with an annotation or a plugin.

Taint source annotation Copy Chapter

You can use the annotation @psalm-taint-source <taint-type> 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.

<?php
/**
 * @psalm-taint-source input
 */
function getQueryParam(string $name) : string {}

Custom taints declared in the configuration Copy Chapter

Custom taints can be declared in psalm.xml, so that the annotations can name them without a plugin registering
them:

<taintAnalysis>
  <taints>
    <taint name="file_upload">
      <alias name="input" />
    </taint>
    <taint name="session_id" />
  </taints>
</taintAnalysis>

A taint added to the alias input with <alias name="input" /> 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 <alias>, 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 Copy Chapter

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`) Copy Section

Taint Flow

Optimized Taint Flow Copy Chapter

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 Copy Section

<?php // --taint-analysis
/**
 * @psalm-flow proxy exec($value)
 */
function process(string $value): void {}

process($_GET['malicious'] ?? '');

The example above states, that the function process($value) is a proxy of the native PHP
function exec($value) - which is potentially vulnerable to code execution (TaintedShell).

Examples

• @psalm-flow proxy exec($value) referencing the global/scoped function exec
• @psalm-flow proxy MyClass::mySinkMethod($value) referencing a function/method of the class MyClass

Return value hint Copy Section

<?php // --taint-analysis
/**
 * @psalm-flow ($value, $items) -> 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 Copy Section

<?php // --taint-analysis
interface Message
{
    /**
     * @psalm-taint-specialize
     * @psalm-flow ($this) -> 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 Copy Section

<?php // --taint-analysis
interface Cache
{
    /**
     * @template T
     * @param callable(): T $compute
     * @return T
     * @psalm-taint-specialize
     * @psalm-flow ($compute()) -> return
     */
    public function get(string $key, callable $compute): mixed;
}

function show(Cache $cache): void
{
    echo $cache->get('key', fn(): string => $_GET['malicious'] ?? '');
}