Menu

PHPDoc Types

A PHPDoc type is what’s written in place of [Type] in annotations like @var [Type] or @param [Type] $foo. Learn more about PHPDoc basics »

Basic types #

  • int, integer
  • string
  • array-key
  • bool, boolean
  • true
  • false
  • null
  • float
  • double
  • scalar
  • array
  • iterable
  • callable
  • resource
  • void
  • object

Mixed #

mixed type can be used if we don’t want to define a more specific type. PHPStan doesn’t check anything on the mixed type - any property or method can be called on it and it can be passed to any type in a function/method call.

PHPStan has a concept of implicit and explicit mixed. Missing typehint is implicit mixed - no type was specified as a parameter type or a return type. Explicit mixed is written in the PHPDoc. PHPStan’s rule level 6 isn’t satisfied with implicit mixed, but an explicit one is sufficient.

Classes and interfaces #

A fully-qualified name (FQN) like \Foo\Bar\Baz, or a relative name like Baz resolved based on the current namespace and use statements can be used.

Trait names cannot be used in PHPDocs, as they don’t work as native PHP typehints either.

Integer ranges #

  • positive-int
  • negative-int
  • int<0, 100>
  • int<min, 100>
  • int<50, max>

General arrays #

  • Type[]
  • array<Type>
  • array<int, Type>
  • non-empty-array<Type>
  • non-empty-array<int, Type>

Key and value types of arrays and iterables #

  • key-of<Type::ARRAY_CONST>
  • value-of<Type::ARRAY_CONST>
class Foo {
   public const WHEELER = [
      'car' => 4,
      'bike' => 2,
   ];
}

/**
 * @param key-of<Foo::WHEELER> $type
 * @param value-of<Foo::WHEELER> $wheels
 */
function repair(string $type, int $wheels): void
{
    // $type is 'bike'|'car'
    // $wheels is 2|4
}

Additionally value-of<BackedEnum> is supported.

Iterables #

  • iterable<Type>
  • Collection<Type>
  • Collection<int, Type>
  • Collection|Type[]

These notations specify the iterable key and value types in a foreach statement.

These iterable rules are applied only when the Collection type isn’t generic. When it’s generic, generics rules for class-level type variables are applied.

If PHPStan encounters Collection|Foo[], two possible paths are taken:

  1. Collection implements Traversable so Collection|Foo[] is interpreted as a Collection object that iterates over Foo. The array part isn’t applied.
  2. Collection does not implement Traversable so Collection|Foo[] is interpreted as a Collection object or an array of Foo objects.

If Collection|Foo[] means “Collection or array” in your case even if Collection implements Traversable, you need to disambiguate the type by using Collection|array<Foo> instead.

Union types #

Written as Type1|Type2. Read more about union types here »

Intersection types #

Written as Type1&Type2. Read more about intersection types here »

Parentheses #

Parentheses can be used to disambiguate types: (Type1&Type2)|Type3

static and $this #

To denote that a method returns the same type it’s called on, use @return static or @return $this.

This is useful if we want to tell that a method from a parent class will return an object of the child class when the parent class is extended (see example).

A narrower @return $this instead of @return static can also be used, and PHPStan will check if you’re really returning the same object instance and not just an object of the child class.

Generics #

Generics », Generics By Examples »

Conditional return types #

A simpler alternative to generics if you just want to infer the return type based on if-else logic.

/**
 * @return ($size is positive-int ? non-empty-array : array)
 */
function fillArray(int $size): array
{
	...
}

It can be combined with generics as well in both the condition and the if-else types:

/**
 * @template T of int|array<int>
 * @param T $id
 * @return (T is int ? static : array<static>)
 */
public function fetch(int|array $id)
{
	...
}

class-string #

class-string type can be used wherever a valid class name string is expected. Generic variant class-string<T> also works, or you can use class-string<Foo> to only accept valid class names that are subtypes of Foo.

/**
 * @param class-string $className
 */
function foo(string $className): void { ... }

Both literal strings with valid class names ('stdClass') and class constants (\stdClass::class) are accepted as class-string arguments.

If you have a general string and want to pass it as a class-string argument, you need to make sure the string contains a valid class name:

function bar(string $name): void
{
    if (class_exists($name)) { // or interface_exists()
        // $name is class-string here
        foo($name);
    }
}

Other advanced string types #

callable-string is a string that PHP considers a valid callable.

numeric-string is a string that would pass an is_numeric() check.

non-empty-string is any string except ''. It does not mean “empty” in the weird sense used by empty().

non-falsy-string (also known as truthy-string) is any string that is true after casting to boolean.

Security-focused literal-string is inspired by the is_literal() RFC. In short, it means a string that is either written by a developer or composed only of developer-written strings.

Global type aliases #

Type aliases (also known as typedef) are a popular feature in other languages like TypeScript or C++. Defining type aliases will allow you to reference complex types in your PHPDocs by their alias.

You can define global type aliases in the configuration file:

parameters:
	typeAliases:
		Name: 'string'
		NameResolver: 'callable(): string'
		NameOrResolver: 'Name|NameResolver'

Then you can use these aliases in your codebase:

/**
 * @param NameOrResolver $arg
 */
function foo($arg)
{
	// $arg is string|(callable(): string)
}

Local type aliases #

You can also define and use local aliases in PHPDocs using the @phpstan-type annotation. These are scoped to the class that defines them:

/**
 * @phpstan-type UserAddress array{street: string, city: string, zip: string}
 */
class User
{
	/**
	 * @var UserAddress
	 */
	private $address; // is of type array{street: string, city: string, zip: string}
}

To use a local type alias elsewhere, you can import it using the @phpstan-import-type annotation in another class’ PHPDocs:

/**
 * @phpstan-import-type UserAddress from User
 */
class Order
{
	/** @var UserAddress */
	private $deliveryAddress; // is of type array{street: string, city: string, zip: string}
}

You can optionally change the name of the imported alias:

/**
 * @phpstan-import-type UserAddress from User as DeliveryAddress
 */
class Order
{
	/** @var DeliveryAddress */
	private $deliveryAddress; // is of type array{street: string, city: string, zip: string}
}

Array shapes #

This feature enables usage of strong types in codebases where arrays of various specific shapes are passed around functions and methods. PHPStan checks that the values in specified keys have the correct types:

  • array{'foo': int, "bar": string}
  • array{0: int, 1?: int} (key 1 is optional in the array)
  • array{int, int} (keys are 0 and 1)
  • array{foo: int, bar: string} (quotes around array keys for simple strings aren’t necessary)

This is different from general arrays that mandate that all the keys and values must be of a specific homogeneous type. Array shapes allow each key and value to be different.

Literals and constants #

PHPStan allows specifying scalar values as types in PHPDocs:

  • 234 (integers)
  • 1.0 (floats)
  • 'foo'|'bar' (strings; types can be combined with others)

Constant enumerations are also supported:

  • Foo::SOME_CONSTANT
  • Foo::SOME_CONSTANT|Bar::OTHER_CONSTANT
  • self::SOME_* (all constants on self that start with SOME_)
  • Foo::* (all constants on Foo)

Global constants #

Available in PHPStan 1.6

Constants are supported as long as they don’t contain lowercase letters and a class with the same name doesn’t exist:

  • SOME_CONSTANT
  • SOME_CONSTANT|OTHER_CONSTANT

Callables #

The callable typehint has been in PHP for a long time. But it doesn’t allow enforcing specific callback signatures. However, PHPStan allows and enforce specific signatures in PHPDocs:

  • callable(int, int): string (accepts two integers, returns a string)
  • callable(int, int=): string (second parameter is optional)
  • callable(int $foo, string $bar): void (accepts an integer and a string, doesn’t return anything; parameter names are optional and insignificant)
  • callable(string &$bar): mixed (accepts a string parameter passed by reference, returns mixed)
  • callable(float ...$floats): (int|null) (accepts multiple variadic float arguments, returns integer or null)
  • callable(float...): (int|null) (accepts multiple variadic float arguments, returns integer or null)

Parameter types and return type are required. Use mixed if you don’t want to use a more specific type.

Bottom type #

All of these names are equivalent:

  • never
  • never-return
  • never-returns
  • no-return

Marking a function or a method as @return never tells PHPStan the function always throws an exception, or contains a way to end the script execution, like die() or exit(). This is useful when solving undefined variables.

Integer masks #

Available in PHPStan 1.6.0

Some functions accept a bitmask composed by |-ing different integer values. 0 is always part of the possible values. Some examples:

  • int-mask<1, 2, 4> (accepts values that can be composed using | from the given integers, and 0)
  • int-mask-of<1|2|4> (the same as above, but writting as a union)
  • int-mask-of<Foo::INT_*> (accepts values from all constants on Foo that start with INT_)

Edit this page on GitHub

Twitter RSS
© 2016–2022 Ondřej Mirtes