Psalm

https://github.com/vimeo/psalm
Admin
Psalm is a static analysis tool for finding errors in PHP applications through comprehensive type...
Tokens:384,174
Snippets:3,159
Trust Score:9.8
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Associative array examples

Source: https://github.com/vimeo/psalm/wiki/Typing-in-Psalm

Examples of associative arrays with integer and string keys.

```php
$a = [0 => 'hello', 5 => 'goodbye'];
$b = ['a' => 'AA', 'b' => 'BB', 'c' => 'CC']
```

--------------------------------

### Install Psalm with Composer

Source: https://github.com/vimeo/psalm/wiki/Installation

Adds Psalm as a development dependency and installs it. Requires PHP >= 5.4 and Composer.

```bash
> composer require --dev "vimeo/psalm:dev-master"
> composer install
```

--------------------------------

### Install a Psalm plugin via Composer

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/plugins/using_plugins.md

Install a plugin package as a dev dependency.

```bash
composer require --dev <plugin-vendor/plugin-package>
```

--------------------------------

### List array example

Source: https://github.com/vimeo/psalm/wiki/Typing-in-Psalm

Example of a list array in PHP.

```php
$a = [1, 2, 3, 4, 5];
```

--------------------------------

### Install Psalm via Composer

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/installation.md

Use Composer to install Psalm as a development dependency. Requires PHP >= 8.2 and Composer.

```bash
composer require --dev vimeo/psalm
```

--------------------------------

### Install Psalm Phar via Composer

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/installation.md

Alternative method to install the Psalm Phar using Composer.

```bash
composer require --dev psalm/phar
```

--------------------------------

### PHP example of class-level contract inference

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/purity_model.md

Shows how Psalm suggests class-level contracts based on subclass needs. The abstract Shape class gets no suggestion because only impure covers Circle, while Base gets a suggestion because Child's contract allows it.

```php
<?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++;
    }
}
```

--------------------------------

### Makeshift struct array example

Source: https://github.com/vimeo/psalm/wiki/Typing-in-Psalm

Example of an array used as a makeshift struct.

```php
$a = ['name' => 'Psalm', 'type' => 'tool'];
```

--------------------------------

### @psalm-readonly-allow-private-mutation shorthand example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Shows the shorthand for combining @readonly and @psalm-allow-private-mutation on a property. The behavior is identical to the previous example.

```php
<?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
```

--------------------------------

### Keyed array examples

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/plugins/plugins_type_system.md

Shows two examples of keyed arrays (object-like arrays) with known keys. The first is a simple keyed array, the second demonstrates optional keys and mixed value types.

```php
$x = ["a" => 1, "b" => 2]; // is TKeyedArray, array{a: int, b: int}
$y = rand(0, 1) ? ["a" => null] : ["a" => 1, "b" => "b"]; // is TKeyedArray with optional keys/values, array{a: ?int, b?: string}
```

--------------------------------

### T[K] key access example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/type_syntax/utility_types.md

Shows how to use T[K] to get the value corresponding to a specified key in an array. The function uses template types T and TKey, and the @psalm-trace annotation reveals the inferred type.

```php
<?php

/**
 * @template T of array
 * @template TKey of string
 * @param T $arr
 * @param TKey $k
 * @return T[TKey]
 */
function a(array $arr, string $k): mixed {
  assert(isset($arr[$k]));
  return $arr[$k];
}

$a = a(['test' => 123], 'test');
/** @psalm-trace $a */; // 123
```

--------------------------------

### @psalm-seal-properties example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Disallows getting and setting properties not listed in @property annotations. Automatically enabled with sealAllProperties config option.

```php
<?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
```

--------------------------------

### MismatchingDocblockReturnType example (valid)

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/MismatchingDocblockReturnType.md

This example is fine because the @return B docblock matches the declared return type A, since B extends A and is a subtype.

```php
<?php

class A {}
class B extends A {}
/**
 * @return B // emitted here
 */
function foo() : A {
    return new B();
}
```

--------------------------------

### TaintedShell example: user input passed to exec

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/TaintedShell.md

Shows a potential command injection where a GET parameter is used as a command for exec(). The issue is reported because the input is tainted and can be controlled by the user.

```php
<?php

$command = $_GET["command"];

runCode($command);

function runCode(string $command) {
    exec($command);
}
```

--------------------------------

### Callable array examples

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/type_syntax/array_types.md

Shows how to define an array holding a callable, as supported by PHP's native call_user_func() and friends. The first example uses a class name and method name, the second uses an object and method name.

```php
<?php

$callable = ['myClass', 'aMethod'];
$callable = [$object, 'aMethod'];
```

--------------------------------

### AbstractInstantiation example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/AbstractInstantiation.md

Shows an abstract class A and an attempt to instantiate it, which triggers the AbstractInstantiation error.

```php
<?php

abstract class A {}
new A();
```

--------------------------------

### Equality assertion example with equalsFive

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/assertion_syntax.md

Demonstrates the behavior of equality assertions: the negation has no meaning, and calling the function is not a RedundantCondition. The example shows a function that asserts equality to 5 and its usage in an if/else.

```php
<?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
  }
}
```

--------------------------------

### Capabilities example: Counter class and functions

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/purity_model.md

Shows @psalm-capabilities annotations on methods and functions, including errors for missing capabilities. The example includes a class with a static property and a private property, and two functions that read or write a static property.

```php
<?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;
}
```

--------------------------------

### MixedPropertyAssignment example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/MixedPropertyAssignment.md

This example triggers the MixedPropertyAssignment error by assigning a property to a mixed parameter. The function accepts a mixed value and attempts to set a property on it, which Psalm cannot infer.

```php
<?php

/** @param mixed $a */
function foo($a) : void {
    $a->foo = "bar";
}
```

--------------------------------

### Redundant function calls example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/RedundantFunctionCall.md

Shows a PHP example where array_values and strtolower are called redundantly on data that is already in the expected form.

```php
<?php

$a = ['already', 'a', 'list'];

$redundant = array_values($a);
$alreadyLower = strtolower($redundant[0]);
```

--------------------------------

### MismatchingDocblockReturnType example (incorrect)

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/MismatchingDocblockReturnType.md

This example triggers the MismatchingDocblockReturnType error because the @return B docblock does not match the declared return type A, and B is not a subtype of A.

```php
<?php

class A {}
class B {}
/**
 * @return B // emitted here
 */
function foo() : A {
    return new A();
}
```

--------------------------------

### NullReference example: calling method on null

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/NullReference.md

Shows a null variable being used as an object, which triggers the NullReference issue. The example assigns null to $a and then calls ->foo() on it.

```php
<?php

$a = null;
$a->foo();
```

--------------------------------

### Non-keyed array example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/plugins/plugins_type_system.md

Shows an array with unknown keys, treated as a mapping between types. The example builds an array with string keys and integer values, resulting in array<string,int>.

```php
$a = [];
foreach (range(1,1) as $_) $a[(string)rand(0,1)] = rand(0,1); // array<string,int>
```

--------------------------------

### Implement Psalm\Plugin\EventHandler\AfterStatementAnalysisInterface

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/plugins/authoring_plugins.md

Example of a plugin class implementing the AfterStatementAnalysisInterface. This is a minimal skeleton for a plugin entry point.

```php
<?php
class SomePlugin implements \Psalm\Plugin\EventHandler\AfterStatementAnalysisInterface
{
}
```

--------------------------------

### PHP example triggering UndefinedPropertyFetch

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UndefinedPropertyFetch.md

This example defines a class A with no properties, instantiates it, and attempts to echo the undefined property $foo, which causes Psalm to emit the UndefinedPropertyFetch error.

```php
<?php

class A {}
$a = new A();
echo $a->foo;
```

--------------------------------

### @mixin example with class A and B

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Demonstrates @mixin annotation on class B to proxy methods and properties of class A. The example shows that $b->doA() and $b->a work due to the mixin.

```php
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
```

--------------------------------

### Global state example: Config class and tamper function

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/purity_model.md

Shows how objects reached from global state require write-globals for property writes. The example includes a class with a static property and a function that reads it, plus a function that attempts to modify a property on the returned object, producing an error.

```php
<?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
    }
}
```

--------------------------------

### Deep scanned file example (src/A.php)

Source: https://github.com/vimeo/psalm/blob/master/docs/contributing/how_psalm_works.md

This PHP file is used as an example of a file that Psalm will deep scan when analyzing the src directory. It extends a vendor class and uses another vendor class as a parameter type, illustrating the dependencies that deep scanning captures.

```php
<?php
use Vendor\VendorClass;
use Vendor\OtherVendorClass;

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

--------------------------------

### NullPropertyFetch example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/NullPropertyFetch.md

Shows a PHP snippet that triggers the NullPropertyFetch error by fetching a property on a null value.

```php
<?php

$a = null;
echo $a->foo;
```

--------------------------------

### Run psalm-review via main psalm entry point

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/command_line_usage.md

Alternative way to run psalm-review using the main psalm entry point, useful when working with the phar. The report.json is generated using vendor/bin/psalm --report=report.json.

```bash
./vendor/bin/psalm.phar --review report.json [code|phpstorm|code-server] [ inv|rev|[~-]IssueType1 ] [ [~-]IssueType2 ] ...
```

--------------------------------

### Generate Psalm config file

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/installation.md

Run Psalm's init command to scan the project and generate a configuration file with an appropriate error level.

```bash
./vendor/bin/psalm --init
```

--------------------------------

### Example of referencing undefined class A

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UndefinedClass.md

Shows a PHP snippet that triggers the UndefinedClass issue by instantiating a class 'A' that does not exist.

```php
<?php

$a = new A();
```

--------------------------------

### Example of SECURITY report output

Source: https://github.com/vimeo/psalm/blob/master/docs/security_analysis/index.md

Shows how security issues appear in human-readable reports under a SECURITY header.

```text
SECURITY: TaintedHtml - src/index.php:2:1 - Detected tainted HTML
```

--------------------------------

### Split configuration using XInclude (psalm.xml and files.xml)

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/configuration.md

Shows how to split the Psalm configuration into multiple files using XInclude. The main psalm.xml includes files.xml, which defines the project files.

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

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

--------------------------------

### PHP example of undefined property assignment

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UndefinedPropertyAssignment.md

Shows a class A with no properties, then assigns 'foo' to an instance, triggering the UndefinedPropertyAssignment error.

```php
<?php

class A {}
$a = new A();
$a->foo = "bar";
```

--------------------------------

### Pure method accessing static property

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/ImpureStaticProperty.md

This example triggers the 'ImpureStaticProperty' error. The method 'get' is marked as pure with the @psalm-pure annotation, but it returns the static property 'self::$value', which is not allowed in a pure context.

```php
<?php

class ValueHolder {
    public static ?string $value = null;

    /**
     * @psalm-pure
     */
    public static function get(): ?string {
        return self::$value;
    }
}
```

--------------------------------

### Run documentation tests

Source: https://github.com/vimeo/psalm/blob/master/docs/contributing/adding_issues.md

Execute the documentation test suite to verify all required steps are completed.

```bash
$ vendor/bin/phpunit tests/DocumentationTest.php

```

--------------------------------

### Vulnerable PHP example with inline JavaScript echo

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/TaintedTextWithQuotes.md

Shows a PHP script that echoes a user-controlled parameter inside a script tag without sanitization, leading to potential XSS. Passing `');alert('injection');//` as a GET param triggers the alert.

```php
<?php
$param = strip_tags($_GET['param']);
?>

<script>
    console.log('<?=$param?>')
</script>
```

--------------------------------

### PHP example of UnimplementedInterfaceMethod

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UnimplementedInterfaceMethod.md

Shows a class 'A' that implements interface 'I' but does not implement the required method 'foo()', causing the error.

```php
<?php

interface I {
    public function foo() : void;
}
class A implements I {}
```

--------------------------------

### Download and run Psalm Phar

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/installation.md

Download the Psalm Phar from GitHub, make it executable, and check its version.

```bash
wget https://github.com/vimeo/psalm/releases/latest/download/psalm.phar
chmod +x psalm.phar
./psalm.phar --version
```

--------------------------------

### Example of uninitialized property in constructor

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PropertyNotSetInConstructor.md

Shows a class with a non-null property `$foo` that is not set in the constructor, triggering the PropertyNotSetInConstructor issue.

```php
<?php

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

    public function __construct() {}
}
```

--------------------------------

### Example array literal

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/type_syntax/array_types.md

An example array literal that Psalm will type internally as an array shape.

```php
<?php
["hello", "world", "foo" => new stdClass, 28 => false];
```

--------------------------------

### Run Psalm on the entire project

Source: https://github.com/vimeo/psalm/wiki/Running-Psalm

Executes Psalm from the project root, scanning all files referenced by <inspectFiles> in the config file.

```bash
./vendor/bin/psalm
```

--------------------------------

### NullArrayAccess example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/NullArrayAccess.md

Shows a null variable being accessed as an array, which triggers the NullArrayAccess error.

```php
<?php

$arr = null;
echo $arr[0];
```

--------------------------------

### PHP example of TaintedLlmPrompt vulnerability

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/TaintedLlmPrompt.md

Shows a class LlmAgent with a prompt method annotated as a taint sink for llm_prompt. The example then creates an agent and calls prompt with user-controlled input from $_GET, which triggers the TaintedLlmPrompt issue.

```php
<?php

class LlmAgent {
    /** @psalm-taint-sink llm_prompt $prompt */
    public function prompt(string $prompt): string {
        return "";
    }
}

$agent = new LlmAgent();
$agent->prompt((string) $_GET["question"]);
```

--------------------------------

### PHP example triggering PossiblyNullPropertyAssignment

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PossiblyNullPropertyAssignment.md

This example shows a class A with a nullable property $foo and a function that accepts a nullable object of type A. Assigning to $foo on the possibly null object triggers the error.

```php
<?php

class A {
    /** @var ?string */
    public $foo;
}
function foo(?A $a) : void {
    $a->foo = "bar";
}
```

--------------------------------

### Run Psalm in Docker

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/installation.md

Run Psalm using the official Docker image, which is faster than normal PHP. Mounts the current directory and runs Psalm with --no-cache.

```bash
docker run -v $PWD:/app --rm -it ghcr.io/danog/psalm:latest /composer/vendor/bin/psalm --no-cache
```

--------------------------------

### Example of FalseOperand error

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/FalseOperand.md

This example triggers the 'FalseOperand' error by using `false` in a concatenation operation with `echo`.

```php
<?php

echo 5 . false; 
```

--------------------------------

### Example of PossiblyUndefinedGlobalVariable

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PossiblyUndefinedGlobalVariable.md

This example triggers the error because $a is only assigned inside an if block with a random condition, so it may be undefined when echoed.

```php
<?php

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

```

--------------------------------

### PossiblyNullArrayAssignment example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PossiblyNullArrayAssignment.md

Shows a variable initialized to null and then used as an array for assignment, triggering the error.

```php
<?php

$a = null;
$a[0][] = 1;

```

--------------------------------

### MismatchingDocblockParamType example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/MismatchingDocblockParamType.md

Example of a function with a docblock @param int that does not match the string typehint, causing the MismatchingDocblockParamType error.

```php
<?php

/**
 * @param int $b
 */
function foo(string $b) : void {}
```

--------------------------------

### Example of DeprecatedClass issue

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/DeprecatedClass.md

Shows a class marked with @deprecated and its instantiation, which triggers the DeprecatedClass issue.

```php
<?php

/** @deprecated */
class A {}
new A();
```

--------------------------------

### Generate baseline file with --set-baseline

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/dealing_with_code_issues.md

Run this command to generate a baseline file named psalm-baseline.xml containing current errors. This file should be committed for use in other environments like CI.

```bash
vendor/bin/psalm --set-baseline
```

--------------------------------

### PHP example triggering UndefinedGlobalVariable

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UndefinedGlobalVariable.md

This example references the variable $a without defining it, which causes Psalm to emit the UndefinedGlobalVariable issue.

```php
<?php

echo $a;
```

--------------------------------

### Show all local Psalm plugins

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/plugins/using_plugins.md

Display a list of all local plugins, both enabled and disabled.

```bash
vendor/bin/psalm-plugin show
```

--------------------------------

### @psalm-suppress inline example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Suppresses issues inline, applying to the following statement. The example suppresses PossiblyNullOperand for the echo statement.

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

--------------------------------

### Run Psalter via its binary

Source: https://github.com/vimeo/psalm/blob/master/docs/manipulating_code/fixing.md

Invoke Psalter directly using its own binary. The [args] placeholder represents command-line arguments.

```bash
vendor/bin/psalter [args]
```

--------------------------------

### UnsafeInstantiation example with new static

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UnsafeInstantiation.md

Shows a class A with a method getInstance returning new static(), which triggers the UnsafeInstantiation issue because the constructor is not final.

```php
<?php

class A {
    public function getInstance() : self
    {
        return new static();
    }
}
```

--------------------------------

### UndefinedTrait example: using undefined trait T

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UndefinedTrait.md

This example triggers the UndefinedTrait error because trait T is not defined. The class A attempts to use T, which does not exist.

```php
<?php

class A {
    use T;
}
```

--------------------------------

### Standalone CLI usage for hack-conformance scripts

Source: https://github.com/vimeo/psalm/blob/master/bin/hack-conformance/README.md

Shows all commands for the standalone CLI tools: run.php for behavior conformance (requires docker), transpile.php for regenerating tests, and track-upstream.php for upstream drift. Includes flags like --verbose, --json, --check, and --write, with exit code 3 for no HHVM.

```sh
# Behaviour conformance (requires docker; pulls the image if missing):
php bin/hack-conformance/run.php            # ok/FAIL per fixture
php bin/hack-conformance/run.php --verbose  # also print HHVM output
php bin/hack-conformance/run.php --json     # machine-readable (what the test consumes)

# Regenerate tests/HackConformanceTranspiledTest.php after changing a fixture
# (requires docker; pulls the image if missing):
php bin/hack-conformance/transpile.php
php bin/hack-conformance/transpile.php --check                       # is it up to date? (exit 3: no HHVM)
php bin/hack-conformance/transpile.php type_variables/array_access.hack  # print one fixture's PHP

# Upstream drift (requires git):
php bin/hack-conformance/track-upstream.php          # report changes
php bin/hack-conformance/track-upstream.php --write  # accept current snapshot
```

--------------------------------

### Example of MissingReturnType issue

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/MissingReturnType.md

Shows a function without a return type, which triggers the MissingReturnType issue.

```php
<?php

function foo() {
    return "foo";
}
```

--------------------------------

### Using a docblock typehint

Source: https://github.com/vimeo/psalm/wiki/Home

Example of using a docblock to specify the type of a variable, which Psalm respects. Here, $a is treated as a string.

```php
/** @var string **/
$a = some_function();
```

--------------------------------

### List type usage example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/type_syntax/array_types.md

Compares array<int, string> and list<string> parameters, showing how Psalm warns on non-zero-based arrays.

```php
<?php
/**
 * @param array<int, string> $arr
 */
function takesArray(array $arr) : void {
  if ($arr) {
     // this index may not be set
    echo $arr[0];
  }
}

/**
 * @psalm-param list<string> $arr
 */
function takesList(array $arr) : void {
  if ($arr) {
    // list indexes always start from zero,
    // so a non-empty list will have an element here
    echo $arr[0];
  }
}

takesArray(["hello"]); // this is fine
takesArray([1 => "hello"]); // would trigger bug, without warning

takesList(["hello"]); // this is fine
takesList([1 => "hello"]); // triggers warning in Psalm
```

--------------------------------

### Using a function call inside if - failing example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PossiblyNullArgument.md

This example fails because Psalm cannot guarantee that subsequent calls to `$cat->getName()` return the same result.

```php
<?php

if (is_string($cat->getName()) {
    foo($cat->getName());
}
```

--------------------------------

### Psalm XML configuration to enable Trace issue

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Shows how to configure Psalm to report the Trace issue as an error, which is necessary to see the output of @psalm-trace.

```xml
<!-- psalm.xml -->
<issueHandlers>
  <Trace errorLevel="error"/>
</issueHandlers>
```

--------------------------------

### Example of ForbiddenCode: var_dump

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/ForbiddenCode.md

Psalm emits ForbiddenCode when it encounters a var_dump call, as shown in this PHP snippet. This is a simple example that triggers the issue.

```php
<?php

var_dump("bah");
```

--------------------------------

### Generate baseline file with custom name using --set-baseline=your-baseline.xml

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/dealing_with_code_issues.md

Run this command to generate a baseline file with a custom name. The file will contain current errors and should be committed for use in other environments.

```bash
vendor/bin/psalm --set-baseline=your-baseline.xml
```

--------------------------------

### Example of UncaughtThrowInGlobalScope

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UncaughtThrowInGlobalScope.md

This example shows a function that can throw an exception (due to the @throws annotation) and a call to it in the global scope without a try-catch, which triggers the issue.

```php
<?php

/**
 * @throws \Exception
 */
function foo() : int {
    return random_int(0, 1);
}
foo();
```

--------------------------------

### Example of PossiblyInvalidOperand with array or integer addition

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PossiblyInvalidOperand.md

This example triggers the error because $b can be either an array or an integer, and using it in an addition operation is potentially invalid.

```php
<?php

function foo() : void {
    $b = rand(0, 1) ? [] : 4;
    echo $b + 5;
}
```

--------------------------------

### Use baseline file with --use-baseline=your-baseline.xml

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/dealing_with_code_issues.md

Run this command to use a previously generated baseline file when running Psalm. This suppresses errors listed in the baseline.

```bash
vendor/bin/psalm --use-baseline=your-baseline.xml
```

--------------------------------

### Enable extensions with enableExtensions

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/configuration.md

Lists extensions to enable. By default, only extensions required by composer.json are enabled.

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

--------------------------------

### MixedArrayAccess example: accessing array offset on unknown type

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/MixedArrayAccess.md

This example triggers MixedArrayAccess because $GLOBALS['foo'] has an unknown type, and accessing [0] on it is unsafe.

```php
<?php

echo $GLOBALS['foo'][0];
```

--------------------------------

### PHP example triggering NullPropertyAssignment

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/NullPropertyAssignment.md

Assigns a property to a null variable, which triggers the NullPropertyAssignment error in Psalm.

```php
<?php

$a = null;
$a->foo = "bar";
```

--------------------------------

### Wrong class casing example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/InvalidClass.md

Shows a class defined as 'Foo' but instantiated as 'foo', triggering the InvalidClass error.

```php
<?php

class Foo {}
(new foo());
```

--------------------------------

### Variable template example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/type_syntax/utility_types.md

Shows the simplified variable template syntax using $a, $b, and $choose directly in the return type. The @psalm-trace annotations show the inferred types for different inputs.

```php
<?php

/**
 * @return ($choose is true ? $a : $b)
 */
function pick(string $a, string $b, bool $choose): string {
  return $choose ? $a : $b;
}

$a = pick('a', 'b', true);
/** @psalm-trace $a */; // 'a'

$a = pick('a', 'b', false);
/** @psalm-trace $a */; // 'b'
```

--------------------------------

### EmptyArrayAccess example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/EmptyArrayAccess.md

Attempting to access index 0 of an empty array triggers the EmptyArrayAccess error in Psalm.

```php
<?php

$a = [];
$b = $a[0];
```

--------------------------------

### Interface instantiation example in PHP

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/InterfaceInstantiation.md

Shows the error-triggering code: defining an interface 'I' and then using 'new I()'. This violates the rule that interfaces cannot be instantiated.

```php
<?php

interface I {}
new I();
```

--------------------------------

### ImpureVariable example: referencing $this in a pure method

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/ImpureVariable.md

This example shows a pure method that returns $this, which is impure because it references the object instance. This triggers the ImpureVariable error.

```php
<?php

class A {
    public int $a = 5;

    /**
     * @psalm-pure
     */
    public function foo() : self {
        return $this;
    }
}
```

--------------------------------

### PossiblyInvalidCast example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PossiblyInvalidCast.md

Example of a possibly invalid cast where a conditional expression returns either class A (no __toString) or class B (with __toString), and the result is cast to string.

```php
<?php

class A {}
class B {
    public function __toString() {
        return 'hello';
    }
}
$c = (string) (rand(0, 1) ? new A() : new B());

```

--------------------------------

### NullFunctionCall example: using null as a callable

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/NullFunctionCall.md

This example triggers the NullFunctionCall error by assigning null to a variable and then calling it as a function. The error is emitted because null is not callable.

```php
<?php

$arr = null;
echo $arr();
```

--------------------------------

### UnusedVariable example with --find-dead-code

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UnusedVariable.md

Shows a function where variable $a is unused, triggering the UnusedVariable issue when --find-dead-code is enabled.

```php
<?php

function foo() : void {
    $a = 5;
    $b = 4;
    echo $b;
}
```

--------------------------------

### Run Psalter via Psalm's binary

Source: https://github.com/vimeo/psalm/blob/master/docs/manipulating_code/fixing.md

Invoke Psalter through Psalm's binary using the --alter flag. The [args] placeholder represents command-line arguments.

```bash
vendor/bin/psalm --alter [args]
```

--------------------------------

### Example of UnusedDocblockParam with renamed parameter

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UnusedDocblockParam.md

This example triggers the UnusedDocblockParam error because the docblock specifies $legacy_param, but the function signature only has $newParam. The docblock parameter is unused and should be updated or removed.

```php
<?php

/**
 * @param string $legacy_param was renamed to $newParam
 */
function f(string $newParam): string {
    return strtolower($newParam);
}
```

--------------------------------

### Using class-string-map<T of Foo, T> with bounded template

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/type_syntax/utility_types.md

Shows a class A with a static map using class-string-map<T of Foo, T> and a get method that returns instances of the given class string, with psalm-trace showing correct types.

```php
<?php

/**
 * @psalm-consistent-constructor
 */
class Foo {}

/**
 * @psalm-consistent-constructor
 */
class Bar extends Foo {}

class A {
  /** @var class-string-map<T of Foo, T> */
  private static array $map = [];

  /**
   * @template U of Foo
   * @param class-string<U> $class
   * @return U
   */
  public static function get(string $class) : Foo {
    if (isset(self::$map[$class])) {
      return self::$map[$class];
    }

    self::$map[$class] = new $class();
    return self::$map[$class];
  }
}

$foo = A::get(Foo::class);
$bar = A::get(Bar::class);

/** @psalm-trace $foo */; // Foo
/** @psalm-trace $bar */; // Bar
```

--------------------------------

### Example of PossiblyInvalidClone with union type

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PossiblyInvalidClone.md

This example triggers the error by cloning a value that could be a string, which is not cloneable. The function accepts a parameter typed as 'A|string' and attempts to clone it.

```php
<?php

class A {}

/**
 * @param A|string $a
 */
function foo($a) {
    return clone $a;
}
```

--------------------------------

### Enable a Psalm plugin

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/plugins/using_plugins.md

Enable a specific plugin using the psalm-plugin tool.

```bash
vendor/bin/psalm-plugin enable plugin-vendor/plugin-package
```

--------------------------------

### Invalid Traversable Implementation Example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/InvalidTraversableImplementation.md

This example shows a class that directly implements Traversable, which is invalid and will cause a fatal error. The class should instead implement IteratorAggregate or Iterator.

```php
<?php

/**
 * @implements Traversable<mixed, mixed>
 */
final class C implements Traversable {} // will cause fatal error
```

--------------------------------

### InvalidCast example: casting object to string

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/InvalidCast.md

Shows a PHP example that triggers Psalm's InvalidCast issue. An object of class A is cast to a string, which is not a valid cast.

```php
<?php

class A {}
$a = new A();
$b = (string)$a;
```

--------------------------------

### @psalm-yield example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Specifies the type of value sent back to a generator when an annotated object is yielded. The example shows a Promise interface with a covariant template and a generator that yields it.

```php
<?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);
};
```

--------------------------------

### Example of a function that could be pure

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/MissingPureAnnotation.md

A simple function that only adds 1 to its input. Psalm infers it could be pure and suggests adding @psalm-pure.

```php
<?php

function couldBePure(int $a): int {
    return $a+1;
}
```

--------------------------------

### @psalm-check-type-exact example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Checks the exact type of a variable without allowing subtypes. The example shows a mismatch error because the variable is assigned an integer but the annotation expects int.

```php
<?php

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

--------------------------------

### Run Psalm with a custom config file

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/configuration.md

Command to run Psalm using a different configuration file via the --config option.

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

--------------------------------

### PHP example triggering NullArrayOffset

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/NullArrayOffset.md

Accessing an array offset with null causes this Psalm issue. The example shows an array with string keys and an attempt to access it using null.

```php
<?php

$arr = ['' => 5, 'foo' => 1];
echo $arr[null];
```

--------------------------------

### InvalidOperand example: concatenating an object with a string

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/InvalidOperand.md

This example triggers the InvalidOperand error by using an object of class A in a string concatenation operation. The object is not a valid operand for the concatenation operator.

```php
<?php

class A {}
echo (new A) . ' ';
```

--------------------------------

### Example of calling a deprecated method

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/DeprecatedMethod.md

Shows a class A with a method foo marked with @deprecated, and a call to that method. This triggers the DeprecatedMethod issue.

```php
<?php

class A {
    /** @deprecated */
    public function foo() : void {}
}
(new A())->foo();
```

--------------------------------

### InvalidIterator example: foreach over non-iterable integer

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/InvalidIterator.md

Attempting to iterate over an integer with foreach triggers the InvalidIterator issue. The example assigns 5 to $a and then tries to loop over it, which is invalid because integers are not iterable.

```php
<?php

$a = 5;
foreach ($a as $b) {}
```

--------------------------------

### Example of UndefinedTrace with @psalm-trace

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UndefinedTrace.md

This example triggers the UndefinedTrace error because the variable $x is not defined before the @psalm-trace annotation. The annotation attempts to trace an undefined variable, causing Psalm to report the issue.

```php
<?php

/** @psalm-trace $x */
echo 'Hello World!';

```

--------------------------------

### Example of PossiblyUndefinedMethod error

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/PossiblyUndefinedMethod.md

This example triggers the error because the variable $a can be either an instance of class A (which has bar()) or class B (which does not). Calling $a->bar() is unsafe since the method may not exist.

```php
<?php

class A {
    public function bar() : void {}
}
class B {}

$a = rand(0, 1) ? new A : new B;
$a->bar();
```

--------------------------------

### @psalm-require-extends trait requirement example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Defines a trait that requires the using class to extend a specific base class. The example shows a valid use and an invalid use that triggers an error.

```php
<?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;
}
```

--------------------------------

### Run psalm-review with report.json

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/command_line_usage.md

Runs the psalm-review tool to manually review issues from a JSON report in an IDE. The IDE argument is optional when running inside a supported IDE's integrated terminal; otherwise it must be specified. Extra arguments filter issues by type or invert with ~ or -, and rev/inv start from the end.

```bash
./vendor/bin/psalm-review report.json [code|phpstorm|code-server] [ inv|rev|[~-]IssueType1 ] [ [~-]IssueType2 ] ...
```

--------------------------------

### Generate stubs with composer require and psalm --generate-stubs

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/plugins/authoring_plugins.md

First, dev-require the library you want to tweak types for, then generate stubs using the Psalm CLI command. The generated file should be edited to remove unrelated content and improve docblocks.

```bash
composer require --dev cakephp/chronos
```

```bash
vendor/bin/psalm --generate-stubs=stubs/chronos.phpstub
```

--------------------------------

### Unused @psalm-suppress annotation example

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UnusedPsalmSuppress.md

Shows a @psalm-suppress annotation for InvalidArgument that is unused because the call to strlen() does not trigger that issue. This example is used to illustrate when the UnusedPsalmSuppress issue is emitted when --find-unused-psalm-suppress is enabled.

```php
<?php

/** @psalm-suppress InvalidArgument */
echo strlen("hello");
```

--------------------------------

### Example of UndefinedInterface with class and interface

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/UndefinedInterface.md

This example triggers the UndefinedInterface error because interface I extends class C, but C is a class, not an interface. The code defines a class C and an interface I that extends C.

```php
<?php

class C {}

interface I extends C {}
```

--------------------------------

### PHP example of NonStaticSelfCall

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/NonStaticSelfCall.md

Shows a class A with a non-static method foo() and a static method bar() that calls self::foo(), triggering the NonStaticSelfCall issue.

```php
<?php

class A {
    public function foo(): void {}

    public static function bar(): void {
        self::foo();
    }
}
```

--------------------------------

### TooManyTemplateParams example: @template-implements with extra type

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/TooManyTemplateParams.md

This example triggers the TooManyTemplateParams error by using @template-implements with three types for IteratorAggregate, which only accepts one. The class implements IteratorAggregate and yields a value in getIterator().

```php
<?php

/**
 * @template-implements IteratorAggregate<int, string, int>
 */
class SomeIterator implements IteratorAggregate
{
    public function getIterator() {
        yield 5;
    }
}
```

--------------------------------

### Vulnerable cURL request with user input

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/TaintedSSRF.md

Shows a PHP example where user-controlled input from $_GET['url'] is passed directly to CURLOPT_URL, leading to a potential SSRF vulnerability. This is the example provided in the documentation.

```php
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $_GET['url']);

curl_exec($ch);
```

--------------------------------

### Vim vim-lsp configuration for Psalm

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/language_server.md

Vim configuration using vim-lsp to register the Psalm language server. The server is allowed for PHP files and uses the local vendor binary.

```vim
au User lsp_setup call lsp#register_server({
     \ 'name': 'psalm-language-server',
     \ 'cmd': {server_info->[expand('vendor/bin/psalm-language-server')]},
     \ 'allowlist': ['php'],
     \ })
```

--------------------------------

### @psalm-check-type annotation example

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/supported_annotations.md

Shows how to verify that an inferred type matches an expected type. The first check passes, the second fails with a message.

```php
<?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'
```

--------------------------------

### Example of TaintedHtml vulnerability

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/TaintedHtml.md

Shows a PHP script where user input from $_GET is echoed without sanitization, triggering the TaintedHtml issue. The example demonstrates how unescaped user input can lead to XSS.

```php
<?php

$name = $_GET["name"];

printName($name);

function printName(string $name) {
    echo $name;
}
```

--------------------------------

### Example of TaintedEval vulnerability

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/TaintedEval.md

Shows a PHP example where user input from $_GET is passed to an eval call, triggering the TaintedEval security issue. This demonstrates the dangerous pattern of executing untrusted input.

```php
<?php

$name = $_GET["name"];

evalCode($name);

function evalCode(string $name) {
    eval($name);
}
```

--------------------------------

### InvalidCatch Example: Catching Non-Throwable Class A

Source: https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/InvalidCatch.md

This example demonstrates an InvalidCatch issue. Class A does not extend Exception or implement Throwable, so catching it in a try-catch block triggers Psalm's InvalidCatch error.

```php
<?php

class A {}
try {
    $worked = true;
}
catch (A $e) {}
```

--------------------------------

### Using class-string-map<T, T> with unbounded template

Source: https://github.com/vimeo/psalm/blob/master/docs/annotating_code/type_syntax/utility_types.md

Shows a class A with a static map using class-string-map<T, T> for unrelated classes, and a get method that returns instances of the given class string, with psalm-trace showing correct types.

```php
<?php

/**
 * @psalm-consistent-constructor
 */
class Foo {}

/**
 * @psalm-consistent-constructor
 */
class Bar {}

/**
 * @psalm-consistent-constructor
 */
class Baz {}

class A {
  /** @var class-string-map<T, T> */
  private static array $map = [];

  /**
   * @template U
   * @param class-string<U> $class
   * @return U
   */
  public static function get(string $class) : object {
    if (isset(self::$map[$class])) {
      return self::$map[$class];
    }

    self::$map[$class] = new $class();
    return self::$map[$class];
  }
}

$foo = A::get(Foo::class);
$bar = A::get(Bar::class);
$baz = A::get(Baz::class);

/** @psalm-trace $foo */; // Foo
/** @psalm-trace $bar */; // Bar
/** @psalm-trace $baz */; // Baz
```
Tokens:
Raw