Psalm

https://psalm.dev/docs
Admin
Psalm is a static analysis tool for PHP that finds type-related bugs and security vulnerabilities...
Tokens:86,562
Snippets:1,795
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install plugins with Composer

Source: https://psalm.dev/docs/running_psalm/installation

Installs a Psalm plugin using Composer and enables it.

```bash
composer require --dev <plugin/package> && vendor/bin/psalm-plugin enable <plugin/package>

```

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

### Install Psalm using Composer

Source: https://psalm.dev/docs/running_psalm/installation

Installs the latest version of Psalm using Composer.

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

```

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

### Install Psalm Phar using Composer

Source: https://psalm.dev/docs/running_psalm/installation

Installs the Psalm Phar executable as a development dependency using Composer.

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

```

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

### UnresolvableConstant Example

Source: https://psalm.dev/docs/running_psalm/issues/UnresolvableConstant

Example demonstrating an unresolvable constant in Psalm.

```php
<?php

class Foo
{
    public const BAR = ['bar'];

    /**
     * @return value-of<self::BAT>
     */
    public function bar(): string
    {
        return self::BAR[0];
    }
}

```

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

### List example

Source: https://psalm.dev/docs/annotating_code/type_syntax/array_types

Example of a list in PHP.

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

```

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

### MixedPropertyFetch Example

Source: https://psalm.dev/docs/running_psalm/issues/MixedPropertyFetch

Example of MixedPropertyFetch issue in Psalm.

```php
<?php

/** @param mixed $a */
function foo($a) : void {
    echo $a->foo;
}

```

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

### UnusedProperty Example

Source: https://psalm.dev/docs/running_psalm/issues/UnusedProperty

Example demonstrating an unused private property.

```php
<?php

class A {
    /** @var string|null */
    private $foo;

    /** @var int|null */
    private $bar;

    public function getFoo(): ?string {
        return $this->foo;
    }
}

$a = new A();
echo $a->getFoo();


```

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

### Example for @seal-properties

Source: https://psalm.dev/docs/annotating_code/supported_annotations

Demonstrates how @seal-properties instructs Psalm to disallow getting and setting properties not explicitly defined.

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


```

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

### InternalClass example

Source: https://psalm.dev/docs/running_psalm/issues/InternalClass

Example demonstrating the InternalClass issue.

```php
<?php

namespace A {
    /**
     * @internal
     */
    class Foo { } 
}

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

```

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

### Installing Plugins

Source: https://psalm.dev/docs/running_psalm/plugins/using_plugins

To install a Psalm plugin, you can use Composer with the following command.

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

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

### projectFiles configuration example

Source: https://psalm.dev/docs/running_psalm/configuration

Example of configuring project files and directories to ignore.

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

```

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

### Example Plugin Implementation

Source: https://psalm.dev/docs/running_psalm/plugins/authoring_plugins

A basic example of a Psalm plugin implementing the AfterStatementAnalysisInterface.

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


```

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

### RedundantFlag Example

Source: https://psalm.dev/docs/running_psalm/issues/RedundantFlag

Example showing a redundant flag.

```php
<?php
$x = filter_input(INPUT_GET, 'hello', FILTER_VALIDATE_DOMAIN, array('options' => array('default' => 'world.com'), 'flags' => FILTER_NULL_ON_FAILURE));


```

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

### enableExtensions configuration example

Source: https://psalm.dev/docs/running_psalm/configuration

Example of enabling specific PHP extensions for Psalm.

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

```

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

### PossiblyNullPropertyFetch Example

Source: https://psalm.dev/docs/running_psalm/issues/PossiblyNullPropertyFetch

Example demonstrating the PossiblyNullPropertyFetch issue in Psalm.

```php
<?php

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


```

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

### DirectConstructorCall example

Source: https://psalm.dev/docs/running_psalm/issues/DirectConstructorCall

Example showing a direct call to __construct() which is incorrect.

```php
<?php
class A {
    public function __construct() {}
}
$a = new A;
$a->__construct(); // wrong


```

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

### UnusedMethodCall Example

Source: https://psalm.dev/docs/running_psalm/issues/UnusedMethodCall

Example demonstrating an unused method call.

```php
<?php

final class A {
    private string $foo;

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

    public function getFoo() : string {
        return $this->foo;
    }
}

$a = new A("hello");
$a->getFoo();


```

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

### stubs configuration example

Source: https://psalm.dev/docs/running_psalm/configuration

Example of configuring stub files for classes not visible to Psalm.

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

```

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

### Example output

Source: https://psalm.dev/docs

An example of Psalm's output when analyzing a PHP file.

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

```

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

```

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

### RawObjectIteration example

Source: https://psalm.dev/docs/running_psalm/issues/RawObjectIteration

Example of iterating over an object's properties.

```php
<?php

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

    /** @var string|null */
    public $bar;
}

function takesA(A $a) {
    foreach ($a as $property) {}
}


```

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

### UnusedMethod Example

Source: https://psalm.dev/docs/running_psalm/issues/UnusedMethod

Example demonstrating an unused private method.

```php
<?php

class A {
    public function __construct() {
        $this->foo();
    }
    private function foo() : void {}
    private function bar() : void {}
}
$a = new A();


```

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

### Example Sources

Source: https://psalm.dev/docs/security_analysis

Examples of user-controlled input that can be considered taint sources.

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

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

### IfThisIsMismatch Example

Source: https://psalm.dev/docs/running_psalm/issues/IfThisIsMismatch

Example demonstrating the IfThisIsMismatch issue in Psalm.

```php
<?php

/**
 * @template T
 */
class a {
    /**
     * @var T
     */
    private $data;
    /**
     * @param T $data
     */
    public function __construct($data) {
        $this->data = $data;
    }
    /**
     * @psalm-if-this-is a<int>
     */
    public function test(): void {
    }
}

$i = new a(123);
$i->test();

$i = new a("test");
// IfThisIsMismatch - Class is not a<int> as required by psalm-if-this-is
$i->test();

```

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

### RiskyCast Example

Source: https://psalm.dev/docs/running_psalm/issues/RiskyCast

Example of casting an array to an integer, which Psalm flags.

```php
<?php

$foo = (int) array( 'hello' );

```

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

### NullOperand Example

Source: https://psalm.dev/docs/running_psalm/issues/NullOperand

This example demonstrates the use of `null` in an operation, which triggers the NullOperand issue.

```php
<?php

echo null . 'hello';

?>
```

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

### UndefinedPropertyFetch Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedPropertyFetch

Example of getting a property on an object that does not have that property defined.

```php
<?php

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


```

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

### Run Psalm

Source: https://psalm.dev/docs/running_psalm/installation

Executes Psalm to scan the project for issues.

```bash
./vendor/bin/psalm --no-cache

```

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

### Associative array examples

Source: https://psalm.dev/docs/annotating_code/type_syntax/array_types

Examples of associative arrays in PHP.

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

```

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

### psalm-review with Phar

Source: https://psalm.dev/docs/running_psalm/command_line_usage

Running the psalm-review tool using the main psalm entry point, useful when working with the phar.

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

```

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

### Union Type Examples

Source: https://psalm.dev/docs/running_psalm/plugins/plugins_type_system

Examples of creating Union types with Atomic types.

```php
new Union([new TNamedObject('Foo\Bar\SomeClass')]); // equivalent to Foo\Bar\SomeClass in docblock
new Union([new TString(), new TInt()]); // equivalent to string|int in docblock
```

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

### DuplicateParam example

Source: https://psalm.dev/docs/running_psalm/issues/DuplicateParam

Example of a function with a duplicate parameter definition.

```php
<?php

function foo(int $b, string $b) {}

```
```

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

### Barebones configuration file

Source: https://psalm.dev/docs/running_psalm/configuration

A basic example of a Psalm configuration file.

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

```

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

### DuplicateMethod example

Source: https://psalm.dev/docs/running_psalm/issues/DuplicateMethod

Example of a class with a method defined twice.

```php
<?php

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


```

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

### OverriddenPropertyAccess Example

Source: https://psalm.dev/docs/running_psalm/issues/OverriddenPropertyAccess

Example showing a property with less accessibility in a child class than in its parent.

```php
<?php

class A {
    /** @var string|null */
    public $foo;
}
class B extends A {
    /** @var string|null */
    protected $foo;
}


```

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

### restrictReturnTypes example

Source: https://psalm.dev/docs/running_psalm/configuration

Example of how to use restrictReturnTypes to enforce stricter return type checking.

```xml
<psalm
  restrictReturnTypes="true"
>

```

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

### InvalidScalarArgument Example

Source: https://psalm.dev/docs/running_psalm/issues/InvalidScalarArgument

Example demonstrating when InvalidScalarArgument is emitted.

```php
<?php

function foo(int $i) : void {}
function bar(string $s) : void {
    if (is_numeric($s)) {
        foo($s);
    }
}


```

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

### Showing Local Plugins

Source: https://psalm.dev/docs/running_psalm/plugins/using_plugins

You can view a list of all local plugins, both enabled and disabled, by running the `show` command.

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

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

### disableExtensions configuration example

Source: https://psalm.dev/docs/running_psalm/configuration

Example of disabling specific PHP extensions for Psalm.

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

```

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

### MethodSignatureMustOmitReturnType example

Source: https://psalm.dev/docs/running_psalm/issues/MethodSignatureMustOmitReturnType

Example of a `__clone` method defined with a return type.

```php
<?php

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


```

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

### Download Psalm Phar

Source: https://psalm.dev/docs/running_psalm/installation

Downloads the Psalm Phar executable using wget and makes it executable.

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

```

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

### XML Example

Source: https://psalm.dev/docs/running_psalm/issues/UnusedIssueHandlerSuppression

This is an example of XML configuration for issue handlers.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<issueHandlers>
    <PossiblyNullOperand errorLevel="suppress"/>
</issueHandlers>


```

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

### Basic Example

Source: https://psalm.dev/docs/running_psalm/issues/MixedArgumentTypeCoercion

This example shows a basic case where Psalm might emit a MixedArgumentTypeCoercion error.

```php
<?php

function foo(array $a) : void {
    takesStringArray($a);
}

/** @param string[] $a */
function takesStringArray(array $a) : void {}


```

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

### UnusedDocblockParam Example

Source: https://psalm.dev/docs/running_psalm/issues/UnusedDocblockParam

Example of an unused docblock parameter.

```php
<?php

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


```

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

### Enabling a Plugin

Source: https://psalm.dev/docs/running_psalm/plugins/using_plugins

Once a plugin is installed, you can enable it using the `psalm-plugin` tool.

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

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

### Generate a config file

Source: https://psalm.dev/docs/running_psalm/installation

Generates a Psalm configuration file for the project.

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

```

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

### UndefinedTrait Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedTrait

Example of referencing a non-existent trait.

```php
<?php

class A {
    use T;
}


```

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

### UnimplementedInterfaceMethod Example

Source: https://psalm.dev/docs/running_psalm/issues/UnimplementedInterfaceMethod

Example showing a class that implements an interface but does not implement all of its methods.

```php
<?php

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

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

### Create a new plugin project using composer

Source: https://psalm.dev/docs/running_psalm/plugins/authoring_plugins

Bootstrap a new plugin project using the psalm/psalm-plugin-skeleton package.

```bash
composer create-project psalm/psalm-plugin-skeleton:dev-master your-plugin-name
```

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

### UndefinedThisPropertyFetch Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedThisPropertyFetch

Example of UndefinedThisPropertyFetch issue in PHP.

```php
<?php

class A {
    function foo() {
        echo $this->foo;
    }
}


```

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

### Running the server in a docker container

Source: https://psalm.dev/docs/running_psalm/language_server

Example command for running Psalm's language server within a Docker container.

```bash
docker-compose exec php /usr/share/php/psalm/psalm-language-server \
   -r=/var/www/html \
   --map-folder=/var/www/html:$PWD

```

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

### RiskyTruthyFalsyComparison Example

Source: https://psalm.dev/docs/running_psalm/issues/RiskyTruthyFalsyComparison

Example of a risky truthy/falsy comparison in PHP.

```php
<?php

/**
 * @param array|null $arg
 * @return void
 */
function foo($arg) {
    if ($arg) {
        // this is risky, bc the empty array and null case are handled together
    }

    if (!$arg) {
        // this is risky, bc the empty array and null case are handled together  
    }
}


```

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

### ParadoxicalCondition Example

Source: https://psalm.dev/docs/running_psalm/issues/ParadoxicalCondition

Example of a paradoxical condition in PHP.

```php
<?php

function foo(string $input) : string {
    return $input === "a" ? "bar" : ($input === "a" ? "foo" : "b");
}


```

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

### Array<string, int> Example

Source: https://psalm.dev/docs/running_psalm/plugins/plugins_type_system

Shows an example of an array treated as a mapping between string keys and integer values.

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

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

### ImpureMethodCall Example

Source: https://psalm.dev/docs/running_psalm/issues/ImpureMethodCall

Example demonstrating an impure method call within a pure function.

```php
<?php

class A {
    public int $a = 5;

    public function foo() : void {
        $this->a++;
    }
}

/** @psalm-pure */
function filterOdd(int $i, A $a) : ?int {
    $a->foo();

    if ($i % 2 === 0 || $a->a === 2) {
        return $i;
    }

    return null;
}

```

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

### UndefinedPropertyAssignment Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedPropertyAssignment

Example of assigning a property to an object that does not have that property defined.

```php
<?php

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


```

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

### MixedPropertyAssignment Example

Source: https://psalm.dev/docs/running_psalm/issues/MixedPropertyAssignment

Example of assigning a property to a value for which Psalm cannot infer a type.

```php
<?php

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

```

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

### InvalidStringClass Example

Source: https://psalm.dev/docs/running_psalm/issues/InvalidStringClass

Example demonstrating the InvalidStringClass issue.

```php
<?php

class Foo {}
$a = "Foo";
new $a();


```

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

### InaccessibleClassConstant example

Source: https://psalm.dev/docs/running_psalm/issues/InaccessibleClassConstant

Example of an inaccessible class constant.

```php
<?php

class A {
    protected const FOO = 'FOO';
}
echo A::FOO;


```

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

### Interface Instantiation Example

Source: https://psalm.dev/docs/running_psalm/issues/InterfaceInstantiation

An example demonstrating an attempt to instantiate an interface, which will trigger the InterfaceInstantiation issue in Psalm.

```php
<?php

interface I {}
new I();

```

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

### Plugin Configuration in psalm.xml

Source: https://psalm.dev/docs/running_psalm/plugins/authoring_plugins

Example of how to add a plugin to the Psalm configuration file using a relative path.

```xml
    <plugins>
        <plugin filename="src/plugins/SomePlugin.php" />
    </plugins>


```

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

### DeprecatedInterface example

Source: https://psalm.dev/docs/running_psalm/issues/DeprecatedInterface

Example of referring to a deprecated interface.

```php
<?php

/** @deprecated */
interface I {}

class A implements I {}


```

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

### DeprecatedProperty example

Source: https://psalm.dev/docs/running_psalm/issues/DeprecatedProperty

Example of getting/setting a deprecated property.

```php
<?php

class A {
    /**
     * @deprecated
     * @var ?string
     */
    public $foo;
}
(new A())->foo = 5;


```

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

### ImpureStaticProperty Example

Source: https://psalm.dev/docs/running_psalm/issues/ImpureStaticProperty

Example demonstrating the use of a static property within a pure method.

```php
<?php

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

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

```

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

### Specializing taints in functions (initial example)

Source: https://psalm.dev/docs/security_analysis/avoiding_false_positives

Initial example demonstrating a potential taint detection issue without specialization.

```php
<?php

function takesInput(string $s) : string {
    return $s;
}

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

?>
```

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

### DeprecatedMethod example

Source: https://psalm.dev/docs/running_psalm/issues/DeprecatedMethod

Example of calling a deprecated method.

```php
<?php

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


```

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

### Plugin Configuration with Absolute Path

Source: https://psalm.dev/docs/running_psalm/plugins/authoring_plugins

Example of how to add a plugin to the Psalm configuration file using an absolute path.

```xml
    <plugins>
        <plugin filename="/path/to/SomePlugin.php" />
    </plugins>


```

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

### Run Psalm using Docker

Source: https://psalm.dev/docs/running_psalm/installation

Runs Psalm within the official Docker image for improved performance.

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

```

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

### Basic Psalm Execution

Source: https://psalm.dev/docs/running_psalm/command_line_usage

Runs Psalm on all files in the project referenced by <projectFiles>.

```bash
./vendor/bin/psalm

```

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

### UndefinedInterface Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedInterface

Example of an interface referencing a non-existent class.

```php
<?php

class C {}

interface I extends C {}


```

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

### UndefinedGlobalVariable Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedGlobalVariable

Example of referencing an undefined global variable.

```php
<?php

echo $a;

```
```

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

### List type examples

Source: https://psalm.dev/docs/annotating_code/type_syntax/array_types

Examples demonstrating the difference between array<int, string> and list<string> in Psalm.

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

```

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

### UndefinedInterfaceMethod Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedInterfaceMethod

Example of calling a method that does not exist on an interface.

```php
<?php

interface I {}

function foo(I $i) {
    $i->bar();
}


```

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

### Configuration file split using XInclude

Source: https://psalm.dev/docs/running_psalm/configuration

An example of splitting the configuration into multiple files using XInclude.

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

```

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

### TaintedUserSecret Example

Source: https://psalm.dev/docs/running_psalm/issues/TaintedUserSecret

Example demonstrating the TaintedUserSecret issue in Psalm.

```php
<?php

class User {
    /**
     * @psalm-taint-source user_secret
     */
    public function getPassword() : string {
        return "$omePa$$word";
    }
}

function showUserPassword(User $user) {
    echo $user->getPassword();
}


```

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

### TaintedUnserialize Example

Source: https://psalm.dev/docs/running_psalm/issues/TaintedUnserialize

Example of tainted input to an unserialize call.

```php
<?php

$command = $_GET["data"];

getObject($command);

function getObject(string $data) : object {
    return unserialize($data);
}


```

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

### Specializing taints in classes (initial example)

Source: https://psalm.dev/docs/security_analysis/avoiding_false_positives

Initial example demonstrating taint detection issue with class properties before specialization.

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

?>
```

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

### PossiblyInvalidPropertyAssignment Example

Source: https://psalm.dev/docs/running_psalm/issues/PossiblyInvalidPropertyAssignment

Example demonstrating the PossiblyInvalidPropertyAssignment issue in Psalm.

```php
<?php

class A {
    /** @var ?string */
    public $bar;
}

/** @return A|int */
function foo() {
    return rand(0, 1) ? new A : 5;
}

$a = foo();
$a->bar = "5";


```

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

### Keyed Array Example

Source: https://psalm.dev/docs/running_psalm/plugins/plugins_type_system

Demonstrates a keyed array (object-like array) with known keys and optional values.

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

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

### NullPropertyFetch Example

Source: https://psalm.dev/docs/running_psalm/issues/NullPropertyFetch

Example demonstrating an attempt to fetch a property on a null value, which triggers the NullPropertyFetch issue.

```php
<?php

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


```

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

### PossiblyUndefinedStringArrayOffset example

Source: https://psalm.dev/docs/running_psalm/issues/PossiblyUndefinedStringArrayOffset

Example of a string-keyed offset not checked for existence.

```php
<?php

/**
 * @param array<string, string> $arr
 */
function foo(array $arr) : void {
    echo $arr["hello"];
}


```

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

### Basic example of MixedReturnTypeCoercion

Source: https://psalm.dev/docs/running_psalm/issues/MixedReturnTypeCoercion

This example shows a basic case where Psalm might emit the MixedReturnTypeCoercion issue.

```php
<?php

/**
 * @return string[]
 */
function foo(array $a) : array {
    return $a;
}


```

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

### PossiblyFalsePropertyAssignmentValue Example

Source: https://psalm.dev/docs/running_psalm/issues/PossiblyFalsePropertyAssignmentValue

Example demonstrating the PossiblyFalsePropertyAssignmentValue issue.

```php
<?php

class A {
    /** @var int */
    public $foo = 0;
}

function assignToA(string $s) {
    $a = new A();
    $a->foo = strpos($s, "haystack");
}


```

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

### NonStaticSelfCall Example

Source: https://psalm.dev/docs/running_psalm/issues/NonStaticSelfCall

Example of calling a non-static function statically.

```php
<?php

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

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


```

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

### InvalidOperand Example

Source: https://psalm.dev/docs/running_psalm/issues/InvalidOperand

Example of using an object as an operand that is unexpected.

```php
<?php

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


```

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

### NullPropertyAssignment Example

Source: https://psalm.dev/docs/running_psalm/issues/NullPropertyAssignment

Example demonstrating an attempt to set a property on a null variable, which triggers the NullPropertyAssignment issue.

```php
<?php

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


```

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

### Invalid Scope Example

Source: https://psalm.dev/docs/running_psalm/issues/InvalidScope

Example of referring to `$this` outside a class.

```php
<?php

echo $this;

```

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

### forceJit

Source: https://psalm.dev/docs/running_psalm/configuration

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.

```xml
<psalm
  forceJit="[bool]"
>

```

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

### InvalidDocblockParamName example

Source: https://psalm.dev/docs/running_psalm/issues/InvalidDocblockParamName

Example of an invalid docblock param name.

```php
<?php

/**
 * @param string[] $bar
 */
function foo(array $barb): void {
    //
}


```

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

### Example of MissingFile issue

Source: https://psalm.dev/docs/running_psalm/issues/MissingFile

This code snippet demonstrates a scenario where `require` is used on a file that does not exist, which would trigger the MissingFile issue.

```php
<?php

require("nonexistent.php");


```

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

### Running Psalm with a different configuration file

Source: https://psalm.dev/docs/running_psalm/configuration

Command to run Psalm with a custom configuration file.

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

```

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

### Super-Globals Configuration

Source: https://psalm.dev/docs/running_psalm/configuration

Example of how to declare custom types for super-globals like $GLOBALS and $_GET.

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

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

### Makeshift Structs example

Source: https://psalm.dev/docs/annotating_code/type_syntax/array_types

Example of a makeshift struct in PHP.

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

```

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

### Undefined Variable Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedVariable

Example of referencing an undefined variable in PHP.

```php
<?php

function foo() {
    echo $a;
}


```

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

### Equality assertions

Source: https://psalm.dev/docs/annotating_code/assertion_syntax

Example demonstrating the difference between =int and int assertions.

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

```

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

### UndefinedDocblockClass Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedDocblockClass

Example of referencing a non-existent class in a docblock.

```php
<?php

/**
 * @param DoesNotExist $a
 */
function foo($a) : void {}


```

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

### Undefined Function Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedFunction

Example of referencing a function that doesn't exist.

```php
<?php

foo();

?>
```

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

### Specializing taints in functions (using @psalm-pure)

Source: https://psalm.dev/docs/security_analysis/avoiding_false_positives

Example showing that `@psalm-pure` functions also specialize taint tracking.

```php
<?php

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

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

?>
```

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

### Undefined Constant Example

Source: https://psalm.dev/docs/running_psalm/issues/UndefinedConstant

Example of referencing an undefined constant in PHP.

```php
<?php

echo FOO_BAR;


```

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

### Generate stub files

Source: https://psalm.dev/docs/running_psalm/plugins/authoring_plugins

Generate stub files for a library using the psalm CLI.

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

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

### UncaughtThrowInGlobalScope example

Source: https://psalm.dev/docs/running_psalm/issues/UncaughtThrowInGlobalScope

Example of a possible exception not caught in global scope.

```php
<?php

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


```

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

### TaintedXpath Example

Source: https://psalm.dev/docs/running_psalm/issues/TaintedXpath

Example of user-controlled input being passed into an xpath query.

```php
<?php

function queryExpression(SimpleXMLElement $xml) : array|false|null {
    $expression = $_GET["expression"];
    return $xml->xpath($expression);
}


```

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

### respectIncludeOnce

Source: https://psalm.dev/docs/running_psalm/configuration

Specifies whether Psalm should respect `require_once()` and `include_once()` behavior, processing files only after their first inclusion. Defaults to `false`, meaning Psalm treats them like `require`/`include` to check all permutations.

```xml
<psalm
  respectIncludeOnce="[bool]"
>


```

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

### TaintedEval Example

Source: https://psalm.dev/docs/running_psalm/issues/TaintedEval

Example of user-controlled input being passed into an eval call.

```php
<?php

$name = $_GET["name"];

evalCode($name);

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


```

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

### Accessing Psalm Configuration in Plugins

Source: https://psalm.dev/docs/running_psalm/configuration

Example of how plugins can access or modify the global configuration using singleton Psalm\Config.

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

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

### RedundantConditionGivenDocblockType Example

Source: https://psalm.dev/docs/running_psalm/issues/RedundantConditionGivenDocblockType

Example showing a redundant condition given docblock type.

```php
<?php

/**
 * @param string $s
 *
 * @return void
 */
function foo($s) {
    if (is_string($s)) {};
}


```

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

### Simplified variable template example

Source: https://psalm.dev/docs/annotating_code/type_syntax/utility_types

Demonstrates the use of variable templates, which allow directly referencing variables in the return type signature, simplifying complex conditional return types.

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

```

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

### Boolean Type Examples

Source: https://psalm.dev/docs/running_psalm/plugins/plugins_type_system

Illustrates the usage of TBool, TFalse, and TTrue in Psalm, showing how narrower types help identify dead code.

```php
/** @return string|false    false when string is empty, first char of the parameter otherwise */
function firstChar(string $s) { return empty($s) ? false : $s[0]; }
```

```php
$first = firstChar("sdf");
if (true === $first) {
  echo "This is actually dead code";
}
```

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

### Redundant cast example

Source: https://psalm.dev/docs/running_psalm/issues/RedundantCast

An example of a redundant string cast in PHP.

```php
<?php
function foo(string $s) : string {
    return (string) $s;
}


```

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

### resolveFromConfigFile attribute

Source: https://psalm.dev/docs/running_psalm/configuration

Example of the resolveFromConfigFile attribute in the psalm configuration.

```xml
<psalm
  resolveFromConfigFile="[bool]"
/>

```

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

### PossiblyNullFunctionCall Example

Source: https://psalm.dev/docs/running_psalm/issues/PossiblyNullFunctionCall

Example of a function call on a possibly null value.

```php
<?php

function foo(?callable $a) : void {
    $a();
}


```

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

### Handling types with Union

Source: https://psalm.dev/docs/running_psalm/plugins/plugins_type_system

Demonstrates how using a Union container simplifies type handling compared to checking individual types.

```php
if ($type instanceof Union)
   foreach ($types->getTypes() as $atomic)
      handleAtomic($atomic);
else handleAtomic($type);

// with union container it becomes
foreach ($types->getTypes() as $atomic)
   handleAtomic($atomic);
```

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

### PossiblyInvalidCast Example

Source: https://psalm.dev/docs/running_psalm/issues/PossiblyInvalidCast

An example demonstrating a possibly invalid cast in PHP.

```php
<?php

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


```

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

### Example of @psalm-api

Source: https://psalm.dev/docs/annotating_code/supported_annotations

Shows how to use @psalm-api to mark classes that are invoked magically and should not be flagged as unused.

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

```

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

### PossiblyFalseIterator Example

Source: https://psalm.dev/docs/running_psalm/issues/PossiblyFalseIterator

Example of code that might trigger the PossiblyFalseIterator issue.

```php
<?php

$arr = rand(0, 1) ? [1, 2, 3] : false;
foreach ($arr as $a) {}


```

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

### properties-of<T> example

Source: https://psalm.dev/docs/annotating_code/type_syntax/utility_types

This example demonstrates the usage of `properties-of<T>` to convert an object into an array, including its non-static properties.

```php
class A {
  public string $foo = 'foo!';
  public int $bar = 42;

  /**
   * @return properties-of<self>
   */
  public function asArray(): array {
    return [
      'foo' => $this->foo,
      'bar' => $this->bar,
    ];
  }

  /**
   * @return list<key-of<properties-of<self>>>
   */
  public function attributeNames(): array {
    return ['foo', 'bar']
  }
}

```

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

### PossiblyInvalidOperand Example

Source: https://psalm.dev/docs/running_psalm/issues/PossiblyInvalidOperand

Example of using a possibly invalid value in an operation.

```php
<?php

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


```

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

### Require a library for stubbing

Source: https://psalm.dev/docs/running_psalm/plugins/authoring_plugins

Use composer to dev-require a library for which you want to create stub files.

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

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

### NonVariableReferenceReturn Example

Source: https://psalm.dev/docs/running_psalm/issues/NonVariableReferenceReturn

Example of a function returning a non-variable reference expression.

```php
<?php

function &getByRef(): int {
    return 5;
}


```

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

### MutableDependency Example

Source: https://psalm.dev/docs/running_psalm/issues/MutableDependency

Example demonstrating a mutable dependency issue in Psalm.

```php
<?php

class MutableParent {
    public int $i = 0;

    public function increment() : void {
        $this->i++;
    }
}

/**
 * @psalm-immutable
 */
final class NotReallyImmutableClass extends MutableParent {}
```
Tokens:
Raw