Psalm Type Annotations Reference

Quick reference of all type annotations supported by Psalm 7. Useful when writing stubs and handlers.

Source of truth: vendor/vimeo/psalm/src/Psalm/Internal/Type/TypeTokenizer.php (PSALM_RESERVED_WORDS) and vendor/vimeo/psalm/src/Psalm/DocComment.php (PSALM_ANNOTATIONS).

Psalm docs (deep links):

• Typing in Psalm
• Supported Annotations
• Templated Annotations
• Adding Assertions
• Assertion Syntax
• Type syntax: Atomic, Scalar, Value, Object, Array, Callable, Utility, Union, Intersection, Conditional, Top/Bottom, Other

Scalar Types

Integer Subtypes

String Subtypes

Literal Types

42              // literal int
3.14            // literal float
'hello'         // literal string
"hello"         // literal string
Foo::class      // literal class-string
Foo::CONST      // class constant value

Array / List Types

Array Shapes

array{key: string, id: int}        // required keys
array{key?: string}                // optional key
array{0: string, 1: int, ...}     // known prefix + open-ended
list{string, int, float}          // positional list shape

Object Shapes

object{foo: string, bar: int}
object{foo?: string}               // optional property

Callable Types

Callable Mutation Modifiers

Generics

/** [@template](https://github.com/template) T */
/** [@template](https://github.com/template) T of SomeType */           // upper bound
/** [@template-covariant](https://github.com/template-covariant) T */
/** [@extends](https://github.com/extends) Base<int, string> */
/** [@implements](https://github.com/implements) Interface<Foo> */
/** [@use](https://github.com/use) TraitName<Bar> */

Utility Types

Conditional Types

Syntax: (condition ? TypeIfTrue : TypeIfFalse). Conditions can test is, type narrowing on params, or even func_num_args().

// Basic: narrow return type based on a template param
/** [@return](https://github.com/return) (T is string ? int : float) */

// Nullable input → nullable output
/** [@return](https://github.com/return) ($path is null ? null : string) */

// Return type depends on a boolean flag
/** [@return](https://github.com/return) ($choose is true ? TA : TB) */

// Non-empty guard
/** [@return](https://github.com/return) ($format is non-empty-string ? non-empty-string : string) */

// Lowercase propagation
/** [@return](https://github.com/return) ($lowercase is true ? lowercase-string : string) */

// Null-or-value pattern (common in Laravel)
/** [@return](https://github.com/return) ($location is null ? int : int|null) */

// Ternary with union fallback
/** [@return](https://github.com/return) ($return is true ? string : void) */
/** [@return](https://github.com/return) ($return is true ? string : true) */
/** [@return](https://github.com/return) ($return is true ? string : bool) */

// Array emptiness drives return type
/** [@return](https://github.com/return) (TArray is non-empty-array ? non-empty-list<key-of<TArray>> : list<key-of<TArray>>) */
/** [@return](https://github.com/return) (TArray is array<never, never> ? null : TValue) */
/** [@return](https://github.com/return) (TArray is array<never, never> ? false : TValue|false) */

// Nested conditionals
/**
 * [@return](https://github.com/return) ($num is int ? positive-int|0 : ($num is float ? float : positive-int|0|float))
 */

// Overload based on argument count
/** [@return](https://github.com/return) (func_num_args() is 2 ? (null|list<float|int|string|null>) : int) */
/** [@return](https://github.com/return) (func_num_args() is 0 ? array<string, string> : string|false) */

Union and Intersection

int|string              // union
?string                 // shorthand for string|null
Foo&Bar                 // intersection (must satisfy both)

Type Aliases

/** [@psalm-type](https://github.com/psalm-type) UserId = positive-int */
/** [@psalm-import-type](https://github.com/psalm-import-type) UserId from UserService */

Docblock Annotations

Standard PHPDoc (Psalm-aware)

[@var](https://github.com/var), [@param](https://github.com/param), [@return](https://github.com/return), [@property](https://github.com/property), [@property-read](https://github.com/property-read), [@property-write](https://github.com/property-write), [@method](https://github.com/method), [@throws](https://github.com/throws), [@deprecated](https://github.com/deprecated), [@internal](https://github.com/internal), [@mixin](https://github.com/mixin)

All of the above also accept a [@psalm-](https://github.com/psalm-) prefix (e.g. [@psalm-param](https://github.com/psalm-param)) for advanced type syntax that phpDocumentor can't parse. PHPStan prefix ([@phpstan-param](https://github.com/phpstan-param), etc.) is also recognized.

Assertions

Negated assertions (!Type) assert the param is not of the given type. Common examples: !null, !false, !string.

Output Type Narrowing

Suppression and Debugging

Purity and Mutability

Readonly

Sealing

Visibility Overrides

Class-Level

Generators and Scope

Stub-Specific