Las declaraciones de tipo pueden ser añadidas a los argumentos de función, valores de retorno y desde PHP 7.4.0, propiedades de clase. Éstas declaraciones aseguran que el valor es del tipo especificado en el momento de la llamada, de no ser así se lanzará una excepción de tipo TypeError.
Nota:
Cuando se sobreescribe el método de un padre, el método hijo debe coincidir con cualquier tipo de declaración de retorno del padre. Si el padre no tiene definida un tipo de retorno, entonces el método hijo puede realizarla.
Tipo | Descripción | Versión |
---|---|---|
Nombre de la Clase/Interfaz | El valor debe ser una instancia de la clase o de la interfaz. | |
self | El valor debe ser una instanceof de la misma clase que aquella en la que se utiliza la declaración de tipo. Solamente se puede usar en clases. | |
parent | El valor debe ser una instanceof del padre de la clase en la que se usa la declaración de tipo. Solo se puede usar en clases. | |
array | El valor debe ser un array. | |
callable | El valor debe ser un callable válido. No puede ser usado como una declaración de tipo de propiedad de clase. | |
bool | El valor debe ser un valor booleano. | |
float | El valor debe ser un número de coma flotante. | |
int | El valor debe ser un número entero. | |
string | El valor debe ser un string. | |
iterable | El valor debe ser un array o una instanceof de la clase Traversable. | PHP 7.1.0 |
object | El valor debe ser un objeto. | PHP 7.2.0 |
mixed | El valor puede ser cualquier valor. | PHP 8.0.0 |
No se admiten los alias para los tipos escalares anteriores. En su lugar, se tratan como nombres de clase o interfaz. Por ejemplo, usar boolean
como declaración de tipo requerirá que el valor sea una instanceof
de clase o interfaz boolean
, en lugar de tipo bool:
<?php
function test(boolean $parametro) {}
test(true);
?>
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
mixed es equivalente a union typeobject|resource|array|string|int|float|bool|null. Disponible a partir de PHP 8.0.0.
Ejemplo #1 Declaración de tipo de clase básica
<?php
class C {}
class D extends C {}
// Esta clase no extiende de C.
class E {}
function f(C $c) {
echo get_class($c)."\n";
}
f(new C);
f(new D);
f(new E);
?>
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
Ejemplo #2 Declaración de tipo de interfaz básica
<?php
interface I { public function f(); }
class C implements I { public function f() {} }
// Esta clase no implementa I.
class E {}
function f(I $i) {
echo get_class($i)."\n";
}
f(new C);
f(new E);
?>
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
Ejemplo #3 Declaración de tipo de retorno básica
<?php
function suma($a, $b): float {
return $a + $b;
}
// Se devolverá un valor float.
var_dump(suma(1, 2));
?>
El resultado del ejemplo sería:
float(3)
Ejemplo #4 Retornando un objeto
<?php
class C {}
function getC(): C {
return new C;
}
var_dump(getC());
?>
El resultado del ejemplo sería:
object(C)#1 (0) { }
A partir de PHP 7.1.0, las declaraciones de tipo pueden ser marcadas como nullable anteponiendo un interrogante(?
) en el nombre de tipo. Esto conlleva a que el valor puede ser del tipo específico o null
.
Ejemplo #5 Declaración de tipo de argumento Nullable
<?php
class C {}
function f(?C $c) {
var_dump($c);
}
f(new C);
f(null);
?>
El resultado del ejemplo sería:
object(C)#1 (0) { } NULL
Ejemplo #6 Declaración de tipo de retorno Nullable
<?php
function get_item(): ?string {
if (isset($_GET['item'])) {
return $_GET['item'];
} else {
return null;
}
}
?>
Nota:
Es posible lograr argumentos anulables haciendo
null
el valor por defecto. Esto no se recomienda ya que se rompe durante la herencia.Ejemplo #7 Forma antigua de hacer argumentos nullable por defecto
<?php
class C {}
function f(C $c = null) {
var_dump($c);
}
f(new C);
f(null);
?>El resultado del ejemplo sería:
object(C)#1 (0) { } NULL
Es posible combinar tipos simples en tipos compuestos. PHP permite combinar tipos de las siguientes maneras:
No es posible combinar tipos intersección con tipos unión.
Una declaración de tipo de unión acepta valores de múltiples tipos simples diferentes, en lugar de uno solo. Los tipos de unión se especifican mediante la sintaxis T1|T2|...
. Los tipos de unión están disponibles a partir de PHP 8.0.0.
El tipo null
se admite como parte de las uniones, de modo que T1|T2|null
se puede usar para crear una unión nullable. La notación ?T
existente se considera una forma abreviada del caso común de T|null
.
null
no puede ser usado como tipo standalone.
The false
literal type is supported as part of unions, and is included as for historical reasons many internal functions return false
instead of null
for failures. A classic example of such a function is strpos().
false
no se puede usar como tipo independiente (incluido tipo independiente nullable). Por este motivo false
, false|null
y ?false
no están permitidos.
El literal true
no existe.
Una declaración de tipo de Intersección acepta valores que satisfacen múltiples declaraciones de tipo de clase, en lugar de una sola. Los tipos Intersección se especifican usando la sintaxis T1&T2&...
Los tipos Intersección están disponibles a partir de PHP 8.1.0.
Para detectar errores simples en declaraciones de tipos compuestos, los tipos redundantes que se puedan detectar sin realizar la carga de clase dará como resultado un error en tiempo de compilación. Esto incluye:
int|string|INT
o Countable&Traversable&COUNTABLE
darán como resultado un error. Nota: Esto no garantiza que el tipo sea "mínimo", porque hacerlo requeriría cargar todos los tipos de clase usados.
Por ejemplo, si A
y B
son alias de clase, entonces A|B
sigue siendo un tipo de unión legal, aunque podría reducirse a A
o B
. De manera similar, si la clase B extends A {}
, entonces A|B
es también un tipo de unión legal, aunque podría reducirse a solo A
.
<?php
function foo(): int|INT {} // No permitido
function foo(): bool|false {} // No permitido
function foo(): int&Traversable {} // No permitido
function foo(): self&Traversable {} // No permitido
use A as B;
function foo(): A|B {} // No permitido ("use" es parte de la resolución del nombre)
function foo(): A&B {} // No permitido ("use" es parte de la resolución del nombre)
class_alias('X', 'Y');
function foo(): X|Y {} // Permitido (La redundancia solo se detecta en tiempo de ejecución)
function foo(): X&Y {} // Permitido (La redundancia solo se detecta en tiempo de ejecución)
?>
void
es un tipo de retorno que indica que la función no devuelve un valor. Por lo tanto, no puede ser parte de una declaración de tipo de unión. Disponible a partir de PHP 7.1.0.
Nota:
Queda obsoleto el retorno por referencia desde una funcion void a partir de PHP 8.1.0, debido a que dicha función es contradictoria. Previamente emitía el siguiente
E_NOTICE
cuando se llamaba:Only variable references should be returned by reference
<?php
function &test(): void {}
?>
never
es un tipo de retorno que indica que la función no retorna. Esto significa que llama a exit(), lanza una excepción o es un ciclo infinito. Por lo tanto, no puede ser parte de una declaración de tipo de unión. Disponible a partir de PHP 8.1.0.
never es, en el lenguaje de la teoría de tipos, el tipo inferior. Lo que significa que es el subtipo de cualquier otro tipo y puede reemplazar cualquier otro tipo de retorno durante la herencia.
El valor debe ser una instancia de la misma clase en la que se llama al método. Disponible a partir de PHP 8.0.0.
Por defecto, PHP forzará los valores del tipo incorrecto en la declaración de tipo escalar esperada si es posible. Por ejemplo, una función a la que se le da un int para un parámetro que espera una string obtendrá una variable de tipo string.
Es posible habilitar el modo estricto por archivo. En modo estricto, solo se aceptará un valor que corresponda exactamente a la declaración de tipo. De lo contrario, se lanzará un TypeError. La única excepción a esta regla es que un valor int pasará una declaración de tipo float.
Las llamadas a funciones desde funciones internas no se verán afectadas por la declaración de strict_types
.
Para habilitar el modo estricto, se usa el constructor declare
con la declaración strict_types
=1.
Nota:
El tipado estricto se aplica a las llamadas de función realizadas desde dentro del archivo con el tipado estricto habilitado, no a las funciones declaradas de ese archivo. Si un archivo sin
strict_types
activado realiza una llamada a una función que se definió en un archivo constrict_types
activado, la preferencia será respetada (escritura coercitiva) y se forzará el valor.
Nota:
La tipificación estricta solo está definida para declaraciones de tipos escalares.
Ejemplo #8 Tipificación estricta para los valores de los argumentos
<?php
declare(strict_types=1);
function suma(int $a, int $b) {
return $a + $b;
}
var_dump(suma(1, 2));
var_dump(suma(1.5, 2.5));
?>
Output of the above example in PHP 8:
int(3) Fatal error: Uncaught TypeError: suma(): 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
Ejemplo #9 Tipificación coercitiva para valores de los argumentos
<?php
function suma(int $a, int $b) {
return $a + $b;
}
var_dump(suma(1, 2));
// Estos serán forzados a números enteros: ¡observe el resultado a continuación!
var_dump(suma(1.5, 2.5));
?>
El resultado del ejemplo sería:
int(3) int(3)
Ejemplo #10 Tipificación estricta para valores de retorno
<?php
declare(strict_types=1);
function suma($a, $b): int {
return $a + $b;
}
var_dump(suma(1, 2));
var_dump(suma(1, 2.5));
?>
El resultado del ejemplo sería:
int(3) Fatal error: Uncaught TypeError: suma(): Return value must be of type int, float returned in -:5 Stack trace: #0 -(9): suma(1, 2.5) #1 {main} thrown in - on line 5
Cuando strict_types
no está activado, las declaraciones de tipo escalar están sujetas a coerciones de tipo limitadas. Si el tipo exacto del valor no es parte de la unión, entonces el tipo de destino se elige en el siguiente orden de preferencia:
Como excepción, si el valor es una cadena y tanto int como float son parte de la unión, el tipo preferido está determinado por la semántica de "cadena numérica" existente. Por ejemplo, para "42"
se elige int, mientras que para "42.0"
se elige float.
Nota:
Los tipos que no forman parte de la lista de preferencias anterior no son objetivos elegibles para la coerción implícita. En particular, no ocurre ninguna coerción implícita para los tipos
null
yfalse
.
Ejemplo #11 Ejemplo de tipos siendo forzados a formar parte del tipo Unión
<?php
// int|string
42 --> 42 // tipo exacto
"42" --> "42" // tipo exacto
new ObjectWithToString --> "Resultado de __toString()"
// object nunca compatible con int, se resuelve como string
42.0 --> 42 // float compatible con int
42.1 --> 42 // float compatible con int
1e100 --> "1.0E+100" // float demasiado largo para tipo int, se resuelve como string
INF --> "INF" // float demasiado largo para tipo int, se resuelve como string
true --> 1 // bool compatible con int
[] --> TypeError // array no compatible con int o string
// int|float|bool
"45" --> 45 // string numérico int
"45.0" --> 45.0 // string numérico float
"45X" --> true // no es string numérico, se resuelve como bool
"" --> false // no es string numérico, se resuelve como bool
"X" --> true // no es string numérico, se resuelve como bool
[] --> TypeError // array no compatible con int, float or bool
?>
Ejemplo #12 Tipificación de parámetros pasados por referencia
Los tipos declarados de parámetros pasados por referencia se verifican en la entrada de la función, pero no cuando la función devuelve el retorno, por lo que después de que la función haya devuelvo el retorno, el tipo de argumento puede haber cambiado.
<?php
function array_baz(array &$param)
{
$param = 1;
}
$var = [];
array_baz($var);
var_dump($var);
array_baz($var);
?>
Output of the above example in 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
Ejemplo #13 Capturando TypeError
<?php
declare(strict_types=1);
function suma(int $a, int $b) {
return $a + $b;
}
try {
var_dump(suma(1, 2));
var_dump(suma(1.5, 2.5));
} catch (TypeError $e) {
echo 'Error: ', $e->getMessage();
}
?>
Output of the above example in PHP 8:
int(3) Error: suma(): Argument #1 ($a) must be of type int, float given, called in - on line 10