PHP: Déclarations de type

Déclarations de type

Les déclarations de types peuvent être ajoutées aux arguments des fonctions, valeurs de retour, et, à partir de PHP 7.4.0, les propriétés de classes. Elles assurent que les valeurs sont du type spécifié au temps de l'appel, sinon une TypeError est lancé.

Note:
Lors de la surcharge d'une méthode parente, la méthode enfant doit correspondre son type de retour avec la déclaration de type parente. Si le parent ne définit par de type de retour, la méthode enfant peut en déclarer un.

Types unique

Type	Description	Version
Nom de classe/interface	La valeur doit être une `instanceof` de la classe ou interface donnée.
self	La valeur doit être une `instanceof` de la même classe que celle dans laquelle la déclaration de type est utilisée. Peut uniquement être utilisé dans les classes.
parent	La valeur doit être une `instanceof` du parent de la classe dans laquelle la déclaration de type est utilisée. Peut uniquement être utilisé dans les classes.
array	La valeur doit être un tableau (array).
callable	La valeur doit être un callable valide. Ne peut être utilisé comme déclaration de type de propriété de classe.
bool	La valeur doit être un booléen (bool).
float	La valeur doit être un nombre flottant (float).
int	La valeur doit être un entier (int).
string	La valeur doit être une chaîne de caractères (string).
iterable	La valeur doit être soit un array ou une `instanceof` Traversable.	PHP 7.1.0
object	La valeur doit être un objet (object).	PHP 7.2.0
mixed	La valeur peut être n'importe quelle valeur.	PHP 8.0.0

Avertissement

Les alias pour les types scalaires ci-dessus ne sont pas supportés. À la place, ils sont traités comme des noms de classe ou d'interface. Par exemple, utiliser boolean comme un déclaration de type nécessite que la valeur soit une instanceof de la classe ou interface boolean, plutôt que de type bool :


<?php
    function test(boolean $param) {}
    test(true);
?>

Résultat de l'exemple ci-dessus en 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

mixed

Exemples

Exemple #1 Déclaration de type de classe basique


<?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);
?>

Résultat de l'exemple ci-dessus en 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

Exemple #2 Déclaration de type d'interface basique


<?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);
?>

Résultat de l'exemple ci-dessus en 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

Exemple #3 Déclaration de type de retour basique


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

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

L'exemple ci-dessus va afficher :

float(3)

Exemple #4 Retournant un objet


<?php
class C {}

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

var_dump(getC());
?>

L'exemple ci-dessus va afficher :

object(C)#1 (0) {
}

Type nullable

À partir de PHP 7.1.0, les déclarations de type peuvent être marquées comme nullable en préfixant le nom du type avec un point d'interrogation (?). Ceci signifie que la fonction retourne soit le type spécifié soit null.

Exemple #5 Déclaration de type d'argument nullable


<?php
class C {}

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

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

L'exemple ci-dessus va afficher :

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

Exemple #6 Déclaration de type de retour nullable


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

Note:
Antérieur à PHP 7.1.0, il était possible d'accomplir des arguments nullable en définissant la valeur par défaut à null. Ceci n'est pas recommandé car ceci casse lors de l'héritage.
Exemple #7 Ancienne façon de rendre un argument nullable

<?php class C {} function f(C $c = null) { var_dump($c); } f(new C); f(null); ?>

L'exemple ci-dessus va afficher :
object(C)#1 (0) {
}
NULL

Type d'union

Une déclaration de type d'union accepte les valeurs de plusieurs types différents, au lieu d'un seul type. Les types d'union sont spécifiés en utilisant la syntaxe T1|T2|.... Les types d'union sont disponibles à partir de PHP 8.0.0.

Type d'union nullable

Le type null est supporté en tant qu'union, tel que T1|T2|null peut être utilisé pour créer une union nullable. La notation existante ?T est considérée comme un raccourci pour le cas commun T|null.

Attention

null ne peut être utilisé comme type autonome.

Le pseudo-type false

Le type littéral false est supporté en tant qu'union, et est inclus pour des raisons historiques car beaucoup de fonctions internes retournent false au lieu de null en cas d'échec. Un exemple classique d'une telle fonction est strpos().

Attention

false ne peut être utilisé comme type autonome (incluant un type nullable autonome). De ce fait, false, false|null et ?false ne sont pas permit.

Attention

Le type littéral true n'existe pas.

Type redondant et dupliqué

Pour anticiper des bugs simples dans les déclarations de types d'union, les types redondant qui peuvent être détectés sans effectuer un chargement des classes résulteront dans une erreur lors de la compilation. Ceci inclus :

Each name-resolved type may only occur once. Types such as int|string|INT result in an error.
Si bool est utilisé, false ne peut pas être utilisé additionnellement.
Si object est utilisé, les types de classes ne peuvent pas être utilisés additionnellement.
Si iterable est utilisé, array et Traversable ne peuvent pas être utilisés additionnellement.

Note: Ceci ne garantie pas que le type soit “minimal”, car faire ainsi nécessiterait de charger tous les types de classe utilisés.

Par exemple, si A et B sont des alias de classe, alors A|B continue d'être un type d'union légal, même si il peut être réduit à soit A ou B. Similairement, si la classe B extends A {}, alors A|B est aussi un type d'union légal, même si il peut être réduit à juste A.


<?php
function foo(): int|INT {} // Disallowed
function foo(): bool|false {} // Disallowed

use A as B;
function foo(): A|B {} // Disallowed ("use" is part of name resolution)

class_alias('X', 'Y');
function foo(): X|Y {} // Allowed (redundancy is only known at runtime)
?>

Type uniquement valide comme type de retour

void

void est un type de retour indiquant que la fonction ne retourne pas de valeur. Ainsi il ne peut pas faire partie d'une déclaration de type d'union. Disponible à partir de PHP 7.1.0.

static

La valeur doit être une instanceof de la même classe que celle où la méthode est appelée. Disponible à partir de PHP 8.0.0.

Typage Strict

Par défaut, PHP va convertir les valeurs d'un mauvais type vers le type scalaire attendu tant que possible. Par exemple, une fonction, qui attend comme paramètre une string, à laquelle est passée un int recevra une variable de type string.

Il est possible d'activer le mode de typage strict fichier par fichier. Dans le mode strict, seule une variable correspondant exactement au type attendu dans la déclaration sera acceptée sinon une TypeError sera levée. La seule exception à cette règle est qu'une valeur de type int peut passer une déclaration de type float.

Avertissement

Les appels aux fonctions depuis des fonctions internes ne seront pas affectés par la déclaration strict_types.

Pour activer le mode strict, l'expression declare est utilisée avec la déclaration strict_types :

Note:
Le typage strict s'applique aux appels de fonction effectués depuis l'intérieur d'un fichier dont le typage strict est actif, et non aux fonctions déclarées dans ce fichier. Si un fichier dont le typage strict n'est pas activé effectue un appel à une fonction qui a été définie dans un fichier dont le type strict est actif, la préférence de l'appelant (mode coercitif) sera respecté, et la valeur sera forcée.

Note:
Le typage strict n'est défini que pour les déclarations de type scalaire.

Exemple #8 Typage strict pour les valeurs d'arguments


<?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));
?>

Résultat de l'exemple ci-dessus en 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

Exemple #9 Typage coercitif pour les valeurs d'arguments


<?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));
?>

L'exemple ci-dessus va afficher :

int(3)
int(3)

Exemple #10 Typage strict pour les valeurs de retour


<?php
declare(strict_types=1);

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

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

L'exemple ci-dessus va afficher :

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

Typage coercitif avec les types d'union

Quand strict_types n'est pas activé, les déclarations de types scalaire sont sujet à des coercitions de type implicite limité. Si le type exact de la valeur ne fait pas partie de l'union, alors le type cible est choisie dans l'ordre de préférence suivant :

int
float
string
bool

Si le type existe dans l'union, et que la valeur peut être forcée dans le type sous les sémantiques existante de vérification de type de PHP, alors le type est choisi. Sinon le prochain type est essayé.

Attention

Il y a une exception, si la valeur est une chaîne de caractère et que int et float font partie de l'union, alors le type préféré est choisie en fonction des sémantiques de “chaîne numérique”. Par exemple, pour "42" int est choisie, tant que pour "42.0" float est choisie.

Note:
Les types qui ne font pas partie de la liste de préférence ci-dessus ne sont pas des cibles éligibles aux coercitions implicites. En particulier aucune coercition implicite aux types null et false se produit.

Exemple #11 Exemple de types étant forcé dans le type faisant partie de l'union


<?php
// int|string
42    --> 42          // exact type
"42"  --> "42"        // exact type
new ObjectWithToString --> "Result of __toString()"
                      // object never compatible with int, fall back to string
42.0  --> 42          // float compatible with int
42.1  --> 42          // float compatible with int
1e100 --> "1.0E+100"  // float too large for int type, fall back to string
INF   --> "INF"       // float too large for int type, fall back to string
true  --> 1           // bool compatible with int
[]    --> TypeError   // array not compatible with int or string

// int|float|bool
"45"    --> 45        // int numeric string
"45.0"  --> 45.0      // float numeric string

"45X"   --> true      // not numeric string, fall back to bool
""      --> false     // not numeric string, fall back to bool
"X"     --> true      // not numeric string, fall back to bool
[]      --> TypeError // array not compatible with int, float or bool
?>

Divers

Exemple #12 Paramètre typée passé par référence

Les types déclarés des références des paramètres sont vérifiés lors de l'entrée dans la fonction, mais pas lorsque la fonction retourne, donc après que la fonction a retourné, le type de l'argument a pu être modifié.


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

Résultat de l'exemple ci-dessus en PHP 8 :

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

Exemple #13 Capturer l'exception de type TypeError


<?php
declare(strict_types=1);

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

try {
    var_dump(sum(1, 2));
    var_dump(sum(1.5, 2.5));
} catch (TypeError $e) {
    echo 'Error: ', $e->getMessage();
}
?>

Résultat de l'exemple ci-dessus en PHP 8 :

int(3)
Error: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 10

add a note

User Contributed Notes 1 note

down

anisgazig at example dot com ¶

3 years ago


same data type and same value but first function declare as a argument type declaration and return int(7)
and second fucntion declare as a return type declaration but return int(8).

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

var_dump(argument_type_declaration(3.5,4.7));
//output:int(7)

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

var_dump(return_type_declaration(3.5,4.7));

//output:int(8)

add a note