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

<!-- EN-Revision: b57f8f256a4773fc09d19733c70ef8816074d12d Maintainer: pastore Status: ready -->

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

<title>Dichiarazioni di tipo</title>

<para>

Le dichiarazioni di tipo possono essere aggiunte agli argomenti delle funzioni, ai valori restituiti

e, a partire da PHP 7.4.0, alle proprietà di classe. Assicurano che il valore

sia del tipo specificato al momento della chiamata, altrimenti viene

generato un <classname>TypeError</classname>.

</para>

<!-- Find better place where to put this note -->

<note>

<!-- TODO Link to covariance section -->

<para>

Quando si sovrascrive un metodo genitore, il metodo del figlio deve corrispondere a qualsiasi dichiarazione

del tipo restituito sul genitore. Se il genitore non definisce un tipo

restituito, allora il metodo figlio può farlo.

</para>

</note>

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

<title>Tipi singoli</title>

<informaltable>

<tgroup cols="3">

<thead>

<row>

<entry>&Type;</entry>

<entry>&Description;</entry>

<entry>&Version;</entry>

</row>

</thead>

<tbody>

<row>

<entry>Nome di classe/interfaccia</entry>

<entry>

Il valore deve essere un'&instanceof; della classe o dell'interfaccia data.

</entry>

<entry/>

</row>

<row>

<entry><type>self</type></entry>

<entry>

Il valore deve essere un'&instanceof; della stessa classe di quella

in cui viene utilizzata la dichiarazione del tipo.

Può essere utilizzato solo nelle classi.

</entry>

<entry></entry>

</row>

<row>

<entry><type>parent</type></entry>

<entry>

Il valore deve essere un'&instanceof; del genitore della classe

in cui viene utilizzata la dichiarazione del tipo.

Può essere utilizzato solo nelle classi.

</entry>

<entry/>

</row>

<row>

<entry><type>array</type></entry>

<entry>

Il valore deve essere un <type>array</type>.

</entry>

<entry/>

</row>

<row>

<entry><type>callable</type></entry>

<entry>

Il valore deve essere una <type>callable</type> valida.

Non può essere utilizzato come dichiarazione del tipo di proprietà della classe.

</entry>

<entry/>

</row>

<row>

<entry><type>bool</type></entry>

<entry>

Il valore deve essere un valore booleano.

</entry>

<entry/>

</row>

<row>

<entry><type>float</type></entry>

<entry>

Il valore deve essere un numero in virgola mobile.

</entry>

<entry/>

</row>

<row>

<entry><type>int</type></entry>

<entry>

Il valore deve essere un numero intero.

</entry>

<entry/>

</row>

<row>

<entry><type>string</type></entry>

<entry>

Il valore deve essere una <type>string</type>.

</entry>

<entry/>

</row>

<row>

<entry><type>iterable</type></entry>

<entry>

Il valore deve essere un <type>array</type> o un'&instanceof; <classname>Traversable</classname>.

</entry>

<entry>PHP 7.1.0</entry>

</row>

<row>

<entry><type>object</type></entry>

<entry>

Il valore deve essere un <type>object</type>.

</entry>

<entry>PHP 7.2.0</entry>

</row>

<row>

<entry><type>mixed</type></entry>

<entry>

Il valore può essere qualsiasi valore.

</entry>

<entry>PHP 8.0.0</entry>

</row>

</tbody>

</tgroup>

</informaltable>

<warning>

<para>

Gli alias per i tipi scalari di sopra non sono supportati.

Vengono invece trattati come nomi di classi o interfacce.

Ad esempio, usando <literal>boolean</literal> come dichiarazione di tipo

richiederà che il valore sia un &instanceof; della classe o dell'interfaccia

<literal>boolean</literal>, invece che di tipo <type>bool</type>:

</para>

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

</para>

</warning>

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

<title>mixed</title>

<para>

<type>mixed</type> è equivalente al <link linkend="language.types.declarations.composite.union">tipo union</link>

<type class="union">

<type>object</type><type>resource</type><type>array</type><type>string</type>

<type>int</type><type>float</type><type>bool</type><type>null</type>

</type>.

Disponibile a partire da PHP 8.0.0.

</para>

</sect3>

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

&reftitle.examples;

<example>

<title>Dichiarazione di base del tipo classe</title>

<programlisting role="php">

<![CDATA[

<?php

class C {}

class D extends C {}

// Questa non estende 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>Dichiarazione di base del tipo interfaccia</title>

<programlisting role="php">

<![CDATA[

<?php

interface I { public function f(); }

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

// Questa non 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>Dichiarazione di base del tipo restituito</title>

<programlisting role="php">

<![CDATA[

<?php

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

return $a + $b;

}

// Notare che verrà restituito un float.

var_dump(sum(1, 2));

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

float(3)

]]>

</screen>

</example>

<example>

<title>Restituzione di un oggetto</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>

</sect3>

</sect2>

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

<title>Tipo nullable</title>

<para>

A partire da PHP 7.1.0, le dichiarazioni di tipo possono essere contrassegnate come nullable anteponendo al

nome del tipo un punto interrogativo (<literal>?</literal>).

Ciò significa che il valore può essere del tipo specificato o &null;.

</para>

<para>

<example>

<title>Dichiarazione del tipo di argomento 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>Dichiarazione del tipo restituito nullable</title>

<programlisting role="php">

<![CDATA[

<?php

function get_item(): ?string {

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

return $_GET['item'];

} else {

return null;

}

}

?>

]]>

</programlisting>

</example>

</para>

<note>

<para>

È possibile ottenere argomenti nullable rendendo

<literal>null</literal> il valore predefinito.

Questo non è raccomandato in quanto si interrompe durante l'eredità.

</para>

<example>

<title>Vecchio modo per rendere gli argomenti 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>

</sect2>

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

<title>Tipi compositi</title>

<para>

È possibile combinare tipi semplici in tipi compositi.

PHP consente di combinare i tipi nei seguenti modi:

</para>

<itemizedlist>

<listitem>

<simpara>

Union di tipi semplici. A partire da PHP 8.0.0.

</simpara>

</listitem>

<listitem>

<simpara>

Intersezione di tipi di classi (interfacce e nomi di classi). A partire da PHP 8.1.0.

</simpara>

</listitem>

</itemizedlist>

<caution>

<simpara>

Non è possibile combinare i tipi di intersezione con i tipi union.

</simpara>

</caution>

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

<title>Tipi union</title>

<para>

Una dichiarazione di tipo union accetta valori di più tipi semplici diversi,

anziché uno solo.

I tipi union vengono specificati utilizzando la sintassi <literal>T1|T2|...</literal>.

I tipi union sono disponibili a partire da PHP 8.0.0.

</para>

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

<title>Tipi union nullable</title>

<para>

Il tipo <literal>null</literal> è supportato come parte delle union,

in modo tale che <literal>T1|T2|null</literal> possa essere utilizzato per creare una union nullable.

La notazione <literal>?T</literal> esistente è considerata una scorciatoia

per il caso comune di <literal>T|null</literal>.

</para>

<caution>

<simpara>

<literal>null</literal> non può essere utilizzato come tipo autonomo.

</simpara>

</caution>

</sect4>

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

<title>Lo pseudotipo false</title>

<para>

Il tipo letterale <literal>false</literal> è supportato come parte delle union

ed è incluso poiché per ragioni storiche molte funzioni interne restituiscono

<literal>false</literal> invece di <literal>null</literal> per gli errori.

Un classico esempio di tale funzione è <function>strpos</function>.

</para>

<caution>

<simpara>

<literal>false</literal> non può essere utilizzato come tipo autonomo (incluso

il tipo autonomo nullable).

Pertanto, <literal>false</literal>, <literal>false|null</literal>

e <literal>?false</literal> non sono consentiti.

</simpara>

</caution>

<caution>

<simpara>

Il tipo letterale <literal>true</literal> <emphasis>non</emphasis>

esiste.

</simpara>

</caution>

</sect4>

</sect3>

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

<title>Tipi intersezione</title>

<para>

Una dichiarazione di tipo intersezione accetta valori che soddisfano più

dichiarazioni di tipo classe, anziché una singola.

I tipi intersezione sono specificati utilizzando la sintassi <literal>T1&amp;T2&amp;...</literal>.

I tipi intersezione sono disponibili a partire da PHP 8.1.0.

</para>

</sect3>

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

<title>Tipi duplicati e ridondanti</title>

<para>

Per rilevare semplici bug nelle dichiarazioni di tipo composito, i tipi ridondanti che

possono essere rilevati senza eseguire il caricamento della classe risulteranno in un

errore in fase di compilazione. Ciò comprende:

<itemizedlist>

<listitem>

<simpara>

Ogni tipo risolto dal nome può verificarsi solo una volta. Tipi come

<literal>int|string|INT</literal> o

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

generano un errore.

</simpara>

</listitem>

<listitem>

<simpara>

L'utilizzo di <type>mixed</type> genera un errore.

</simpara>

</listitem>

<listitem>

<simpara>Per i tipi union:</simpara>

<itemizedlist>

<listitem>

<simpara>

Se viene usato <type>bool</type>, <type>false</type> non può essere utilizzato in aggiunta.

</simpara>

</listitem>

<listitem>

<simpara>

Se viene usato <type>object</type>, i tipi di classe non possono essere utilizzati in aggiunta.

</simpara>

</listitem>

<listitem>

<simpara>

Se viene usato <type>iterable</type>, <type>array</type>

e <classname>Traversable</classname> non possono essere utilizzati in aggiunta.

</simpara>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<simpara>Per i tipi intersezione:</simpara>

<itemizedlist>

<listitem>

<simpara>

L'utilizzo di un tipo che non è un tipo di classe genera un errore.

</simpara>

</listitem>

<listitem>

<simpara>

L'utilizzo di <type>self</type>, <type>parent</type> o

<type>static</type> genera un errore.

</simpara>

</listitem>

</itemizedlist>

</listitem>

</itemizedlist>

</para>

<note>

<simpara>

Ciò non garantisce che il tipo sia “minimo”, poiché ciò

richiederebbe il caricamento di tutti i tipi di classe utilizzati.

</simpara>

</note>

<para>

Ad esempio, se <literal>A</literal> e <literal>B</literal> sono alias di

classe, <literal>A|B</literal> rimane un tipo di union legale, anche

se potrebbe essere ridotto a <literal>A</literal> o

<literal>B</literal>.

Allo stesso modo, se la classe <code>B extends A {}</code>, anche <literal>A|B</literal>

è un tipo di union legale, anche se potrebbe essere ridotta solo a

<literal>A</literal>.

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

function foo(): int|INT {} // Non consentito

function foo(): bool|false {} // Non consentito

function foo(): int&Traversable {} // Non consentito

function foo(): self&Traversable {} // Non consentito

use A as B;

function foo(): A|B {} // Non consentito ("use" fa parte della risoluzione dei nomi)

function foo(): A&B {} // Non consentito ("use" fa parte della risoluzione dei nomi)

class_alias('X', 'Y');

function foo(): X|Y {} // Consentito (la ridondanza è nota solo in fase di esecuzione)

function foo(): X&Y {} // Consentito (la ridondanza è nota solo in fase di esecuzione)

?>

]]>

</programlisting>

</informalexample>

</para>

</sect3>

</sect2>

<sect2 xml:id="language.types.declarations.return-only">

<title>Tipi di solo ritorno</title>

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

<title>void</title>

<para>

<literal>void</literal> è un tipo di ritorno che indica che la funzione non

restituisce un valore.

Pertanto non può essere parte di una dichiarazione di tipo union.

Disponibile da PHP 7.1.0.

</para>

<note>

<para>

Il ritorno per riferimento da una funzione <type>void</type> è deprecato a partire da PHP 8.1.0,

perché tale funzione è contraddittoria.

In precedenza, emetteva già il seguente

<constant>E_NOTICE</constant> quando chiamata:

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

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

function &test(): void {}

?>

]]>

</programlisting>

</informalexample>

</para>

</note>

</sect3>

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

<title>never</title>

<para>

<literal>never</literal> è un tipo di ritorno che indica che la funzione non

ha un ritorno. Ciò significa che chiama <function>exit</function>, genera

un'eccezione o è un ciclo infinito.

Pertanto non può essere parte di una dichiarazione di tipo union.

Disponibile a partire da PHP 8.1.0.

</para>

<para>

<type>never</type> è, nel gergo della teoria dei tipi, il tipo inferiore.

Significa che è il sottotipo di ogni altro tipo e può sostituire qualsiasi altro

tipo di ritorno durante l'ereditarietà.

</para>

</sect3>

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

<title>static</title>

<para>

Il valore deve essere un'&instanceof; della stessa classe di quella

in cui è chiamato il metodo.

Disponibile da PHP 8.0.0.

</para>

</sect3>

</sect2>

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

<title>Tipizzazione strict</title>

<para>

Per impostazione predefinita, PHP costringerà i valori del tipo sbagliato nella dichiarazione

del tipo scalare previsto, se possibile. Ad esempio, una funzione a cui viene assegnato

un <type>int</type> per un parametro che prevede una <type>string</type>

otterrà una variabile di tipo <type>string</type>.

</para>

<para>

È possibile abilitare la modalità strict per file. In modalità

strict, sarà accettato solo un valore corrispondente esattamente alla dichiarazione

del tipo, altrimenti verrà lanciato un <classname>TypeError</classname>.

L'unica eccezione a questa regola è che un valore <type>int</type>

passerà una dichiarazione di tipo <type>float</type>.

</para>

<warning>

<simpara>

Le chiamate di funzione dall'interno delle funzioni interne non saranno influenzate

dalla dichiarazione <literal>strict_types</literal>.

</simpara>

</warning>

<para>

Per abilitare la modalità rigorosa, il &declare; viene utilizzato con la

dichiarazione <literal>strict_types</literal>:

</para>

<note>

<para>

La tipizzazione strict si applica alle chiamate di funzione effettuate

<emphasis>all'interno</emphasis> del file con la tipizzazione strict abilitata, non alle

funzioni dichiarate all'interno di quel file. Se un file senza la tipizzazione

strict abilitata effettua una chiamata a una funzione che è stata definita in un file

con la tipizzazione strict, la preferenza del chiamante (tipizzazione coercitiva)

verrà rispettata e il valore verrà forzato.

</para>

</note>

<note>

<para>

La tipizzazione strict è definita solo per le dichiarazioni di tipo scalare.

</para>

</note>

<example>

<title>Tipizzazione strict per i valori degli argomenti</title>

<programlisting role="php">

<![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>Tipizzazione coercitiva per i valori degli argomenti</title>

<programlisting role="php">

<![CDATA[

<?php

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

return $a + $b;

}

var_dump(sum(1, 2));

// Questi verranno convertiti in numeri interi: nota l'output qui sotto!

var_dump(sum(1.5, 2.5));

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

int(3)

int(3)

]]>

</screen>

</example>

<example>

<title>Tipizzazione strict per i valori di ritorno</title>

<programlisting role="php">

<![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>

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

<title>Tipizzazione coercitiva con tipi union</title>

<para>

Quando <literal>strict_types</literal> non è abilitato, le dichiarazioni di tipo scalare

sono soggette a limitate coercizioni di tipo implicito.

Se il tipo esatto del valore non fa parte della union, il tipo di destinazione

viene scelto nel seguente ordine di preferenza:

<orderedlist>

<listitem>

<simpara>

<type>int</type>

</simpara>

</listitem>

<listitem>

<simpara>

<type>float</type>

</simpara>

</listitem>

<listitem>

<simpara>

<type>string</type>

</simpara>

</listitem>

<listitem>

<simpara>

<type>bool</type>

</simpara>

</listitem>

</orderedlist>

Se il tipo esiste nella union e il valore può essere forzato al

tipo sotto la semantica di controllo del tipo esistente di PHP, viene scelto il tipo.

Altrimenti viene provato il tipo successivo.

</para>

<caution>

<para>

In via eccezionale, se il valore è una stringa e sia int che float fanno parte

della union, il tipo preferito è determinato dalla semantica

“stringa numerica” esistente.

Ad esempio, per <literal>"42"</literal> viene scelto <type>int</type>,

mentre per <literal>"42.0"</literal> viene scelto <type>float</type>.

</para>

</caution>

<note>

<para>

I tipi che non fanno parte dell'elenco di preferenze di cui sopra non sono obiettivi

ammissibili per la coercizione implicita. In particolare non si verificano coercizioni implicite ai

tipi <literal>null</literal> e <literal>false</literal>.

</para>

</note>

<example>

<title>Esempio di tipi che vengono forzati in un tipo parte della union</title>

<programlisting role="php">

<![CDATA[

<?php

// int|string

42 --> 42 // tipo esatto

"42" --> "42" // tipo esatto

new ObjectWithToString --> "Risultato di __toString()"

// oggetto mai compatibile con int, ripiega su string

42.0 --> 42 // float compatibile con int

42.1 --> 42 // float compatibile con int

1e100 --> "1.0E+100" // float troppo grande per il tipo int, ripiega su string

INF --> "INF" // float troppo grande per il tipo int, ripiega su string

true --> 1 // bool compatibile con int

[] --> TypeError // array non compatibile con int o string

// int|float|bool

"45" --> 45 // stringa numerica intera

"45.0" --> 45.0 // stringa numerica float

"45X" --> true // non una stringa numerica, ripiega su bool

"" --> false // non una stringa numerica, ripiega su bool

"X" --> true // non una stringa numerica, ripiega su bool

[] --> TypeError // array non compatibile con int, float o bool

?>

]]>

</programlisting>

</example>

</sect2>

<!-- TODO figure out what do to with these things -->

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

<title>Misc</title>

<example>

<title>Parametri passati per referenza Tipizzati</title>

<simpara>

I tipi dichiarati di parametri di referenza vengono controllati all'immissione della funzione, ma

non quando la funzione ritorna, quindi dopo che la funzione ritorna, il

tipo dell'argomento potrebbe essere cambiato.

</simpara>

<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.8;

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

<example>

<title>Cattura <classname>TypeError</classname></title>

<programlisting role="php">

<![CDATA[

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

}

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

int(3)

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

]]>

</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

-->