Type declarations

Type 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 is thrown. TypeError

Every single type that PHP supports, with the exception of 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. resource

Opmerking: > When a class implements an interface method or reimplements a method which has already been defined by a parent class, it has to be compatible with the aforementioned definition. A method is compatible if it follows the rules. variance

| Version | Description | | --- | --- | | 8.3.0 | Support for class, interface, trait, and enum constant typing has been added. | | 8.2.0 | Support for types has been added. | | 8.2.0 | Support for the literal type has been added. | | 8.2.0 | The types and can now be used standalone. | | 8.1.0 | Support for intersection types has been added. | | 8.1.0 | Returning by reference from a function is now deprecated. | | 8.1.0 | Support for the return only type has been added. | | 8.0.0 | Support for has been added. | | 8.0.0 | Support for the return only type has been added. | | 8.0.0 | Support for union types has been added. | | 7.4.0 | Support for class properties typing has been added. | | 7.2.0 | Support for has been added. | | 7.1.0 | Support for has been added. | | 7.1.0 | Support for has been added. | | 7.1.0 | Support for nullable types has been added. |

Atomic Types Usage Notes

Atomic types have straight forward behaviour with some minor caveats which are described in this section.

Scalar types

Waarschuwing: > Name aliases for scalar types (, , , ) are not supported. Instead, they are treated as class or interface names. For example, using as a type declaration will require the value to be an instanceof the class or interface , rather than of type : bool``int``float``string``boolean``boolean``bool
<?php
    function test(boolean $param) {}
    test(true);
?>
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

Opmerking: > Returning by reference from a function is deprecated as of PHP 8.1.0, because such a function is contradictory. Previously, it already emitted the following when called: .
`void``E_NOTICE````php

Callable types

This type cannot be used as a class property type declaration.

Opmerking: > It is not possible to specify the signature of the function.

Type declarations on pass-by-reference Parameters

If a pass-by-reference parameter has a type declaration, the type of the
variable is  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.

only

Voorbeeld: Typed pass-by-reference Parameters

<?php
function array_baz(array &$param)
{
    $param = 1;
}
$var = [];
array_baz($var);
var_dump($var);
array_baz($var);
?>

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 Notes

Composite type declarations are subject to a couple of restrictions and will perform a redundancy check at compile time to prevent simple bugs.

Let op: > Prior to PHP 8.2.0, and the introduction of types, it was not possible to combine intersection types with union types.

Union types

Waarschuwing: > It is not possible to combine the two singleton types and together in a union type. Use instead. false``true``bool

Let op: > Prior to PHP 8.2.0, as and could not be used as standalone types, a union type comprised of only these types was not permitted. This comprises the following types: , , and . false``null``false``false|null``?false

Nullable type syntactic sugar

 A single base type declaration can be marked nullable by prefixing the
 type with a question mark ().
 Thus  and  are identical.
`?``?T``T|null`

Opmerking: > This syntax is supported as of PHP 7.1.0, and predates generalized union types support.

Opmerking: > It is also possible to achieve nullable arguments by making the default value. This is not recommended as if the default value is changed in a child class a type compatibility violation will be raised as the type will need to be added to the type declaration. This behavior is also deprecated since PHP 8.4. null``null

Voorbeeld: Old way to make arguments nullable
<?php
class C {}

function f(C $c = null) {
    var_dump($c);
}

f(new C);
f(null);
?>
object(C)#1 (0) {
}
NULL

Duplicate and redundant types

To 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:

Each name-resolved type may only occur once. Types such as or result in an error. int|string|INT``Countable&Traversable&COUNTABLE
Using or results in an error. mixed``never
For union types: - If is used, or cannot be used additionally. bool``false``true - If is used, class types cannot be used additionally. object - If is used, and cannot be used additionally. iterable``array``Traversable
For intersection types: - Using a type which is not a class-type results in an error. - Using either , , or results in an error. self``parent``static
For types: - If a more generic type is used, the more restrictive one is redundant. - Using two identical intersection types.

Opmerking: > This does not guarantee that the type is “minimal”, because doing so would require loading all used class types.

For example, if  and  are class
aliases, then  remains a legal union type, even
though it could be reduced to either  or
.
Similarly, if class , then 
is also a legal union type, even though it could be reduced to just
.

`ABA|BABB extends A {}A|B``A````php




**Voorbeeld: Basic class type declaration**

```php
<?php
class C {}
class D extends C {}

// This doesn't extend C.
class E {}

function f(C $c) {
    echo get_class($c)."\n";
}

f(new C);
f(new D);
f(new E);
?>

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

Voorbeeld: Basic interface type declaration

<?php
interface I { public function f(); }
class C implements I { public function f() {} }

// This doesn't implement I.
class E {}

function f(I $i) {
    echo get_class($i)."\n";
}

f(new C);
f(new E);
?>

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

Voorbeeld: Basic return type declaration

<?php
function sum($a, $b): float {
    return $a + $b;
}

// Note that a float will be returned.
var_dump(sum(1, 2));
?>

float(3)

Voorbeeld: Returning an object

<?php
class C {}

function getC(): C {
    return new C;
}

var_dump(getC());
?>

object(C)#1 (0) {
}

Voorbeeld: Nullable argument type declaration

<?php
class C {}

function f(?C $c) {
    var_dump($c);
}

f(new C);
f(null);
?>

object(C)#1 (0) {
}
NULL

Voorbeeld: Nullable return type declaration

<?php
function get_item(): ?string {
    if (isset($_GET['item'])) {
        return $_GET['item'];
    } else {
        return null;
    }
}
?>

Voorbeeld: Class property type declaration

<?php
class User {
    public static string $foo = 'foo';

    public int $id;
    public string $username;

    public function __construct(int $id, string $username) {
        $this->id = $id;
        $this->username = $username;
    }
}
?>

Strict typing

By 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 for a parameter that expects a will get a variable of type . int``string``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 will be thrown. The only exception to this rule is that an value will pass a type declaration. TypeError``int``float

Waarschuwing: > Function calls from within internal functions will not be affected by the declaration. strict_types

To enable strict mode, the declare statement is used with the declaration: strict_types

Opmerking: > Strict typing applies to function calls made from the file with strict typing enabled, not to the functions declared within that file. If a file without strict typing enabled makes a call to a function that was defined in a file with strict typing, the caller's preference (coercive typing) will be respected, and the value will be coerced. within

Opmerking: > Strict typing is only defined for scalar type declarations.

Voorbeeld: Strict typing for arguments values

<?php
declare(strict_types=1);

function sum(int $a, int $b) {
    return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1.5, 2.5));
?>

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

Voorbeeld: Coercive typing for argument values

<?php
function sum(int $a, int $b) {
    return $a + $b;
}

var_dump(sum(1, 2));

// These will be coerced to integers: note the output below!
var_dump(sum(1.5, 2.5));
?>

int(3)
int(3)

Voorbeeld: Strict typing for return values

<?php
declare(strict_types=1);

function sum($a, $b): int {
    return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1, 2.5));
?>

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

Vorige ← Callables Volgende Enumerations →

Type declarations

Type declarations

Atomic Types Usage Notes

Scalar types

void

Callable types

Type declarations on pass-by-reference Parameters

Composite Types Usage Notes

Union types

Nullable type syntactic sugar

Duplicate and redundant types

Strict typing

Documentatie