<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 0ece873cecfc4dacd14e8bebbec12c6e00de56a0 Maintainer: PhilDaiguille Status: ready -->

<!-- Reviewed: no Maintainer: Marqitos -->

<sect1 xml:id="language.types.declarations">

<title>Declaraciones de tipo</title>

<para>

Las declaraciones de tipos pueden ser añadidas a los argumentos de las funciones,

valores de retorno, a partir de PHP 7.4.0, las propiedades de clase,

y a partir de PHP 8.3.0, las constantes de clase.

Aseguran que el valor es del tipo especificado en el momento de la llamada,

de lo contrario se lanza un <classname>TypeError</classname>.

</para>

<para>

Cada tipo soportado por PHP, con la excepción del tipo

<type>resource</type>, puede ser utilizado en una declaración de tipo

por el usuario.

Esta página contiene un registro de cambios de la disponibilidad de

los diferentes tipos y la documentación sobre su uso en las

declaraciones de tipo.

</para>

<note>

<para>

Cuando una clase implementa un método de interfaz o reimplementa un método

que ya ha sido definido por una clase padre, debe ser compatible con la

definición mencionada.

Un método es compatible si sigue las reglas de

<link linkend="language.oop5.variance">variance</link>.

</para>

</note>

<sect2 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.3.0</entry>

<entry>

Añadido soporte para las constantes tipadas de clase, interfaz, trait y enum.

</entry>

</row>

<row>

<entry>8.2.0</entry>

<entry>

Añadido soporte de tipo <acronym>DNF</acronym> (Forma Normal Disyuntiva).

</entry>

</row>

<row>

<entry>8.2.0</entry>

<entry>

Añadido soporte del tipo <type>true</type>.

</entry>

</row>

<row>

<entry>8.2.0</entry>

<entry>

Los tipos <type>null</type> y <type>false</type> pueden ahora ser utilizados de manera autónoma.

</entry>

</row>

<row>

<entry>8.1.0</entry>

<entry>

Se ha añadido soporte para los tipos de intersección.

</entry>

</row>

<row>

<entry>8.1.0</entry>

<entry>

El retorno por referencia desde una función <type>void</type> ahora está desaconsejado.

</entry>

</row>

<row>

<entry>8.1.0</entry>

<entry>

Se ha añadido soporte para el tipo de retorno únicamente <type>never</type>.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

Añadido soporte de <type>mixed</type>

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

Se ha añadido soporte para el tipo de retorno únicamente <type>static</type>.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

Se ha añadido soporte para los tipos de unión.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Añadido soporte para el tipado de propiedades de clase.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

Añadido soporte para <type>object</type>.

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

Añadido soporte para <type>iterable</type>.

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

Añadido soporte para <type>void</type>.

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

Se ha añadido soporte para los tipos nullable.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</sect2>

<sect2 xml:id="language.types.declarations.base">

<title>Notas de uso de los tipos atómicos</title>

<simpara>

Los tipos atómicos tienen un comportamiento directo con algunas advertencias

menores que se describen en esta sección.

</simpara>

<sect3 xml:id="language.types.declarations.base.scalar">

<title>Tipos escalares</title>

<warning>

<para>

Los alias para los tipos escalares (<type>bool</type>, <type>int</type>,

<type>float</type>, <type>string</type>) no son soportados.

En su lugar, son tratados como nombres de clase o interfaz.

Por ejemplo, utilizar <literal>boolean</literal> como una declaración de

tipo requiere que el valor sea una &instanceof; de la clase o

interfaz <literal>boolean</literal>, en lugar de tipo

<type>bool</type>:

</para>

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

function test(boolean $param) {}

test(true);

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

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

]]>

</screen>

</informalexample>

</warning>

</sect3>

<sect3 xml:id="language.types.declarations.void">

<title>void</title>

<note>

<para>

El retorno por referencia desde una función <type>void</type> está obsoleto a partir

de PHP 8.1.0, ya que tal función es contradictoria.

Anteriormente, ya emitía los siguientes <constant>E_NOTICE</constant> cuando se llamaba:

<computeroutput>Only variable references should be returned by reference</computeroutput>.

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

function &test(): void {}

?>

]]>

</programlisting>

</informalexample>

</para>

</note>

</sect3>

<sect3 xml:id="language.types.declarations.base.function">

<title>Tipos Callable</title>

<para>

Este tipo no puede ser utilizado como declaración de tipo de propiedad de

clase.

</para>

<note>

<simpara>

No es posible especificar la firma de la función.

</simpara>

</note>

</sect3>

<sect3 xml:id="language.types.declarations.references">

<title>Declaraciones de tipo sobre los parámetros de referencia</title>

<simpara>

Si un parámetro pasado por referencia a una declaración de tipo, el tipo

de la variable <emphasis>solo se verifica</emphasis> a la entrada de

la función, al inicio de la llamada, pero no cuando la función es llamada

nuevamente.

Esto significa que una función puede modificar el tipo de la variable pasada

por referencia.

</simpara>

<example>

<title>Parámetro tipado pasado por referencia</title>

<programlisting role="php">

<![CDATA[

<?php

function array_baz(array &$param)

{

$param = 1;

}

$var = [];

array_baz($var);

var_dump($var);

array_baz($var);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

</sect3>

</sect2>

<sect2 xml:id="language.types.declarations.composite">

<title>Notas de uso de los tipos compuestos</title>

<para>

Las declaraciones de tipo compuesto están sujetas a algunas restricciones y

realizarán un control de redundancia en el momento de la compilación para

evitar errores simples.

</para>

<caution>

<simpara>

Anterior a PHP 8.2.0 y la introducción de los tipos <acronym>DNF</acronym>, no

era posible combinar las intersecciones de tipo con las uniones de tipo.

</simpara>

</caution>

<sect3 xml:id="language.types.declarations.composite.union">

<title>Tipos de uniones</title>

<warning>

<simpara>

No es posible combinar los dos tipos de singleton

<type>false</type> y <type>true</type> juntos en una

unión de tipo.

Utilice en su lugar <type>bool</type>.

</simpara>

</warning>

<caution>

<simpara>

Anterior a PHP 8.2.0, como <type>false</type> y <type>null</type> no

podían ser utilizados como tipos autónomos, una unión de tipo

compuesta únicamente de estos tipos no estaba permitida. Esto incluye los

tipos siguientes: <type>false</type>, <literal>false|null</literal>

y <literal>?false</literal>.

</simpara>

</caution>

<sect4 xml:id="language.types.declarations.nullable">

<title>Azúcar sintáctico de tipo nullable</title>

<para>

Una declaración de tipo de base única puede ser marcada como valor NULL

anteponiendo el tipo de un signo de interrogación (<literal>?</literal>).

Así <literal>?T</literal> y <literal>T|null</literal> son idénticos.

</para>

<note>

<simpara>

Esta sintaxis es soportada a partir de PHP 7.1.0, y es anterior

a la soporte generalizado de los tipos de unión.

</simpara>

</note>

<note>

<para>

También es posible obtener argumentos nullable haciendo de

<literal>null</literal> el valor por defecto.

Esto no es recomendado, ya que si el valor por defecto es modificado en

una clase hija, se desencadenará una violación de compatibilidad de tipo ya que el tipo <type>null</type> deberá ser añadido a la declaración de tipo.

Este comportamiento también está obsoleto a partir de PHP 8.4.

</para>

<example>

<title>Forma antigua de hacer los argumentos nullable</title>

<programlisting role="php">

<![CDATA[

<?php

class C {}

function f(C $c = null) {

var_dump($c);

}

f(new C);

f(null);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

object(C)#1 (0) {

}

NULL

]]>

</screen>

</example>

</note>

</sect4>

</sect3>

<sect3 xml:id="language.types.declarations.composite.redundant">

<title>Tipos duplicados y redundantes</title>

<para>

Para detectar errores simples en las declaraciones de tipo compuesto,

los tipos redundantes que pueden ser detectados sin realizar una carga de clase resultarán en un error de compilación. Esto incluye:

<itemizedlist>

<listitem>

<simpara>

Cada tipo resuelto por nombre solo puede ocurrir una vez.

Los tipos como <literal>int|string|INT</literal> o

<literal>Countable&amp;Traversable&amp;COUNTABLE</literal>

generan un error.

</simpara>

</listitem>

<listitem>

<simpara>

El uso de <type>mixed</type> o <type>never</type> resulta en un error.

</simpara>

</listitem>

<listitem>

<simpara>Para los tipos de uniones:</simpara>

<itemizedlist>

<listitem>

<simpara>

Si <type>bool</type> es utilizado, <type>false</type> o

<type>true</type> no puede ser utilizado adicionalmente.

</simpara>

</listitem>

<listitem>

<simpara>

Si <type>object</type> es utilizado, los tipos de clase no pueden

ser utilizados adicionalmente.

</simpara>

</listitem>

<listitem>

<simpara>

Si <type>iterable</type> es utilizado, <type>array</type>

y <classname>Traversable</classname> no pueden ser utilizados

adicionalmente.

</simpara>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<simpara>Para los tipos de intersecciones:</simpara>

<itemizedlist>

<listitem>

<simpara>

El uso de un tipo que no es un tipo de clase genera un error.

</simpara>

</listitem>

<listitem>

<simpara>

El uso de <type>self</type>, <type>parent</type> o

<type>static</type> resulta en un error.

</simpara>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<simpara>Para los tipos <acronym>DNF</acronym>:</simpara>

<itemizedlist>

<listitem>

<simpara>

Si un tipo más genérico es utilizado, el más restrictivo es redundante.

</simpara>

</listitem>

<listitem>

<simpara>

Uso de dos tipos de intersección idénticos.

</simpara>

</listitem>

</itemizedlist>

</listitem>

</itemizedlist>

</para>

<note>

<simpara>

Esto no garantiza que el tipo sea « mínimo », ya que esto requeriría

cargar todos los tipos de clase utilizados.

</simpara>

</note>

<para>

Por ejemplo, si <literal>A</literal> y <literal>B</literal> son

alias de clase, entonces <literal>A|B</literal> sigue siendo una unión de tipo

legal, aunque sea posible reducir a <literal>A</literal> o

<literal>B</literal>.

Asimismo, si la clase <code>B extends A {}</code>, entonces

<literal>A|B</literal> también es una unión de tipo legal, aunque podría ser

reducida al tipo <literal>A</literal> únicamente.

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

function foo(): int|INT {} // No autorizado

function foo(): bool|false {} // No autorizado

function foo(): int&Traversable {} // No autorizado

function foo(): self&Traversable {} // No autorizado

use A as B;

function foo(): A|B {} // No autorizado ("use" forma parte de la resolución de nombres)

function foo(): A&B {} // No autorizado ("use" forma parte de la resolución de nombres)

class_alias('X', 'Y');

function foo(): X|Y {} // Autorizado (la redundancia solo se conoce en tiempo de ejecución)

function foo(): X&Y {} // Autorizado (la redundancia solo se conoce en tiempo de ejecución)

?>

]]>

</programlisting>

</informalexample>

</para>

</sect3>

</sect2>

<sect2 xml:id="language.types.declarations.examples">

&reftitle.examples;

<example>

<title>Declaración de tipo de clase de base</title>

<programlisting role="php">

<![CDATA[

<?php

class C {}

class D extends C {}

// Esta no extiende C.

class E {}

function f(C $c) {

echo get_class($c)."\n";

}

f(new C);

f(new D);

f(new E);

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

<example>

<title>Declaración de tipo de interfaz de base</title>

<programlisting role="php">

<![CDATA[

<?php

interface I { public function f(); }

class C implements I { public function f() {} }

// Esta no implementa I.

class E {}

function f(I $i) {

echo get_class($i)."\n";

}

f(new C);

f(new E);

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

<example>

<title>Declaración de tipo de retorno de base</title>

<programlisting role="php">

<![CDATA[

<?php

function sum($a, $b): float {

return $a + $b;

}

// Note que un float será devuelto.

var_dump(sum(1, 2));

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

float(3)

]]>

</screen>

</example>

<example>

<title>Retorno de un objeto</title>

<programlisting role="php">

<![CDATA[

<?php

class C {}

function getC(): C {

return new C;

}

var_dump(getC());

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

object(C)#1 (0) {

}

]]>

</screen>

</example>

<example>

<title>Declaración de tipo de argumento nullable</title>

<programlisting role="php">

<![CDATA[

<?php

class C {}

function f(?C $c) {

var_dump($c);

}

f(new C);

f(null);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

object(C)#1 (0) {

}

NULL

]]>

</screen>

</example>

<example>

<title>Declaración de tipo de retorno nullable</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

function get_item(): ?string {

if (isset($_GET['item'])) {

return $_GET['item'];

} else {

return null;

}

}

?>

]]>

</programlisting>

</example>

<example>

<title>Declaración de tipo para las propiedades de clase</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

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

}

}

?>

]]>

</programlisting>

</example>

</sect2>

<!-- TODO Move this into its own declare page -->

<sect2 xml:id="language.types.declarations.strict">

<title>Tipado estricto</title>

<para>

Por defecto, PHP convertirá los valores de un tipo incorrecto al tipo

escalar esperado siempre que sea posible. Por ejemplo, una función, que espera

como parámetro una <type>string</type>, a la que se pasa un

<type>int</type> recibirá una variable de tipo <type>string</type>.

</para>

<para>

Es posible activar el modo de tipado estricto archivo por archivo.

En el modo estricto, solo una variable que coincida exactamente con el

tipo esperado en la declaración será aceptada, de lo contrario se lanzará un

<classname>TypeError</classname>.

La única excepción a esta regla es que un valor de tipo <type>int</type>

puede pasar una declaración de tipo <type>float</type>.

</para>

<warning>

<simpara>

Las llamadas a funciones desde funciones internas no serán

afectadas por la declaración <literal>strict_types</literal>.

</simpara>

</warning>

<para>

Para activar el modo estricto, se utiliza la expresión &declare; con la

declaración <literal>strict_types</literal>:

</para>

<note>

<para>

El tipado estricto se aplica a las llamadas de función realizadas desde

<emphasis>dentro</emphasis> de un archivo cuyo tipado estricto está activo, y no a las funciones declaradas en ese archivo. Si un archivo cuyo tipado estricto no está activado realiza una llamada a una función que ha sido definida en un archivo cuyo tipo estricto está activo, la preferencia del llamante (modo coercitivo) será respetada y el valor será forzado.

</para>

</note>

<note>

<para>

El tipado estricto solo está definido para las declaraciones de tipo escalar.

</para>

</note>

<example>

<title>Tipado estricto para los valores de argumentos</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

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

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

<example>

<title>Tipado coercitivo para los valores de argumentos</title>

<programlisting role="php">

<![CDATA[

<?php

function sum(int $a, int $b) {

return $a + $b;

}

var_dump(sum(1, 2));

// Estos serán forzados a enteros: ¡note la salida a continuación!

var_dump(sum(1.5, 2.5));

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

int(3)

int(3)

]]>

</screen>

</example>

<example>

<title>Tipado estricto para los valores de retorno</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

declare(strict_types=1);

function sum($a, $b): int {

return $a + $b;

}

var_dump(sum(1, 2));

var_dump(sum(1, 2.5));

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

</sect2>

</sect1>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->