Menu
A PHPDoc type is what’s written in place of
[Type]
in annotations like @var [Type]
or @param [Type] $foo
.Basic types #
int
,integer
positive-int
,negative-int
string
bool
,boolean
true
false
null
float
double
array
iterable
callable
resource
void
object
Mixed #
PHPStan is a static code analyzer for PHP which can reduce the amount of bugs in a project and make it more maintainable in the long run. With the latest release of PHPStorm 2020.3 EAP, support for PHPStan is provided directly by PHPStorm - no plugins necessary. PhpStorm 2020.3 comes with support for two popular static analysis tools in PHP: Psalm and PHPStan. Starting with this release, PhpStorm has first-class support for these tools, which will help you highlight problems in the editor and better support for Psalm annotations. In PhpStorm, we’ve already annotated some internal PHP functions like parseurl with # ArrayShape, so you can benefit from the attributes right away. Fortunately, the syntax of one-line attributes is backward-compatible.
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
Xampp xdebug phpstorm. , but an explicit one is sufficient.Classes and interfaces #
A fully-qualified name (FQN) like
FooBarBaz
, 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.
General arrays #
Type[]
array<Type>
array<int, Type>
non-empty-array<Type>
non-empty-array<int, Type>
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.Phpstan Phpstorm
If PHP encounters
Collection|Foo[]
, two possible paths are taken:Collection
implementsTraversable
soCollection|Foo[]
is interpreted as aCollection
object that iterates overFoo
. The array part isn’t applied.Collection
does not implementTraversable
soCollection|Foo[]
is interpreted as aCollection
object or an array ofFoo
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 #
class-string #
class-string
type can be used wherever a valid class name string is expected. Generic variant class-string<T>
also works.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:Other advanced string types #
There’s also
callable-string
and numeric-string
.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:
Then you can use these aliases in your codebase:
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:To use a local type alias elsewhere, you can import it using the
@phpstan-import-type
annotation:You can optionally change the name of the imported alias:
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}
(key1
is optional in the array)array{int, int}
(keys are0
and1
)array{foo: int, bar: string}
(quotes around array keys 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 #
Available in PHPStan 0.12.20
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 onself
that start withSOME_
)Foo::*
(all constants onFoo
)
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, returnsmixed
)callable(float ..$floats): (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 #
Phpstorm Phpstan No Rules Detected
All of these names are equivalent:
Phpstan Phpstorm Docker
never
never-return
never-returns
no-return
Phpstan For Phpstorm
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.