Type declarationsType declarations can be added to function arguments, return values, as of PHP 7.4.0, class properties, and as of PHP 8.3.0, class constants. They ensure that the value is of the specified type at call time, otherwise a TypeError is thrown. Every single type that PHP supports, with the exception of resource can be used within a user-land type declaration. This page contains a changelog of availability of the different types and documentation about usage of them in type declarations.
Changelog
Atomic Types Usage NotesAtomic types have straight forward behaviour with some minor caveats which are described in this section. Scalar typesWarning
Name aliases for scalar types (bool, int,
float, string) are not supported.
Instead, they are treated as class or interface names.
For example, using
Output of the above example in PHP 8: Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2 Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2 Stack trace: #0 -(3): test(true) #1 {main} thrown in - on line 2 void
Callable typesThis type cannot be used as a class property type declaration.
Type declarations on pass-by-reference ParametersIf a pass-by-reference parameter has a type declaration, the type of the variable is only checked on function entry, at the beginning of the call, but not when the function returns. This means that a function can change the type of variable reference. Example #1 Typed pass-by-reference Parameters
The above example will output something similar to: int(1) Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2 Stack trace: #0 -(9): array_baz(1) #1 {main} thrown in - on line 2 Composite Types Usage NotesComposite type declarations are subject to a couple of restrictions and will perform a redundancy check at compile time to prevent simple bugs. Caution
Prior to PHP 8.2.0, and the introduction of DNF types, it was not possible to combine intersection types with union types. Union typesWarning
It is not possible to combine the two value types false and true together in a union type. Use bool instead. Caution
Prior to PHP 8.2.0, as false and null
could not be used as standalone types, a union type comprised of only
these types was not permitted. This comprises the following types:
false, Nullable type syntactic sugar
A single base type declaration can be marked nullable by prefixing the
type with a question mark (
Duplicate and redundant typesTo catch simple bugs in composite type declarations, redundant types that can be detected without performing class loading will result in a compile-time error. This includes:
For example, if
ExamplesExample #3 Basic class type declaration
Output of the above example in PHP 8: C D Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8 Stack trace: #0 -(14): f(Object(E)) #1 {main} thrown in - on line 8 Example #4 Basic interface type declaration
Output of the above example in PHP 8: C Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8 Stack trace: #0 -(13): f(Object(E)) #1 {main} thrown in - on line 8 Example #5 Basic return type declaration
The above example will output: float(3) Example #6 Returning an object
The above example will output: object(C)#1 (0) { } Example #7 Nullable argument type declaration
The above example will output: object(C)#1 (0) { } NULL Example #8 Nullable return type declaration
Example #9 Class property type declaration
Strict typingBy default, PHP will coerce values of the wrong type into the expected scalar type declaration if possible. For example, a function that is given an int for a parameter that expects a string will get a variable of type string. It is possible to enable strict mode on a per-file basis. In strict mode, only a value corresponding exactly to the type declaration will be accepted, otherwise a TypeError will be thrown. The only exception to this rule is that an int value will pass a float type declaration. Warning
Function calls from within internal functions will not be affected by
the
To enable strict mode, the
Example #10 Strict typing for arguments values
Output of the above example in PHP 8: int(3) Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4 Stack trace: #0 -(9): sum(1.5, 2.5) #1 {main} thrown in - on line 4 Example #11 Coercive typing for argument values
The above example will output: int(3) int(3) Example #12 Strict typing for return values
The above example will output: int(3) Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5 Stack trace: #0 -(9): sum(1, 2.5) #1 {main} thrown in - on line 5 |