references.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a2a141160a466ff8eb34be4c75e7701b75d689ad Maintainer: cucinato  Status: ready -->
 <chapter xml:id="language.references" xmlns="http://docbook.org/ns/docbook">
  <title>Spiegazioni sui riferimenti</title>

  <sect1 xml:id="language.references.whatare">
   <title>Cosa sono i riferimenti</title>
   <simpara>
    I riferimenti in PHP sono il mezzo per accedere ad uno stesso contenuto di variabile 
    utilizzando diversi nomi. Non si sta parlando di puntatori come in C; per esempio,
    non si può effettuare aritmetica dei puntatori, perché non sono
    reali indirizzi di memoria, e così via. Vedere
    <xref linkend="language.references.arent" /> per ulteriori
    informazioni. Al contrario, sono alias nella tabella dei simboli. Si noti che in
    PHP, il nome delle variabili e il loro contenuto sono cose diverse, uno stesso
    contenuto infatti può avere nomi diversi. L'analogia più prossima è quella con
    i nomi dei file e i file stessi in Unix - i nomi delle variabili sono come directory,
    mentre il contenuto delle variabili è il file stesso. I riferimenti possono essere
    pensati come hardlink del filesystem Unix.
   </simpara>
  </sect1>

  <sect1 xml:id="language.references.whatdo">
   <title>Che cosa fanno i riferimenti</title>
   <para>
    Esistono tre operazioni principali effettuate attraverso i riferimenti:
    <link linkend="language.references.whatdo.assign">assegnare per
    riferimento</link>, <link linkend="language.references.whatdo.pass">passare
    per riferimento</link>,
    e <link linkend="language.references.whatdo.return">restituzione per
    riferimento</link>. Questa sezione darà un'introduzione a queste
    operazioni, con collegamenti per ulteriori informazioni.
   </para>
   <sect2 xml:id="language.references.whatdo.assign">
    <title>Assegnazione per Riferimento</title>
    <para>
     Attraverso questa prima operazione, i riferimenti PHP permettono di
     far sì che due variabili facciano riferimento allo stesso contenuto. Questo significa, che scrivendo:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$a =& $b;
?>
]]>
      </programlisting>
     </informalexample>
     <varname>$a</varname> e <varname>$b</varname>
     puntano allo stesso contenuto.
     <note>
      <para>
       <varname>$a</varname> e <varname>$b</varname> sono completamente
       uguali, ma <varname>$a</varname> non è un puntatore a
       <varname>$b</varname> o vice versa,
       <varname>$a</varname> e <varname>$b</varname> puntano semplicemente nello
       stesso posto.
      </para>
     </note>
    </para>
    <note>
     <para>
      Se si assegna, si passa o si restituisce per riferimento una variabile non definita,
      questa verrà creata.
      <example>
       <title>Uso dei riferimenti con variabili non definite</title>
       <programlisting role="php">
<![CDATA[
<?php
function foo(&$var) { }

foo($a); // $a is "created" and assigned to null

$b = array();
foo($b['b']);
var_dump(array_key_exists('b', $b)); // bool(true)

$c = new StdClass;
foo($c->d);
var_dump(property_exists($c, 'd')); // bool(true)
?>
]]>
       </programlisting>
      </example>
     </para>
    </note>
    <para>
     La stessa sintassi può essere usata con funzioni che restituiscono
     riferimenti, e con l'operatore <literal>new</literal> (a partire da PHP
     4.0.4 e prima di PHP 5.0.0):
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$foo =& find_var($bar);
?>
]]>
      </programlisting>
     </informalexample>
     Da PHP 5, <link linkend="language.oop5.basic.new">new</link>
     restituisce automaticamente un riferimento, quindi
     usare <literal>=&amp;</literal> in questo contesto è deprecato e
     produce un messaggio <constant>E_DEPRECATED</constant> in PHP 5.3 e
     successivi, e un messaggio <constant>E_STRICT</constant> nelle versioni precedenti.
     (Tecnicamente, la differenza consiste nel fatto che, in PHP 5, le variabili object, come pure le
     risorse, sono semplici puntatori ai veri dati dell'oggetto, quindi questi
     riferimenti a oggetto non sono "riferimenti" nel senso usato in precedenza (alias).
     Per maggiori informazioni, vedere <link linkend="language.oop5.references">Oggetti
     e riferimenti</link>.
    </para>
    <warning>
     <para>
      Se si assegna un riferimento ad una varibile dichiarata <literal>global</literal>
      dall'interno di una funzione, il riferimento sarà visibile solo all'interno della funzione stessa.
      Si può evitare tutto ciò utilizzando la matrice <varname>$GLOBALS</varname>.
      <example>
       <title>Riferimenti di varibiali globali all'interno di una funzione</title>
       <programlisting role="php">
<![CDATA[
<?php
$var1 = "Example variable";
$var2 = "";

function global_references($use_globals)
{
    global $var1, $var2;
    if (!$use_globals) {
        $var2 =& $var1; // visible only inside the function
    } else {
        $GLOBALS["var2"] =& $var1; // visible also in global context
    }
}

global_references(false);
echo "var2 is set to '$var2'\n"; // var2 is set to ''
global_references(true);
echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
?>
]]>
       </programlisting>
      </example>
      Si pensi a <literal>global $var;</literal> come ad una scorciatoia per <literal>$var
        =&amp; $GLOBALS['var'];</literal>. Quindi assegnando altri riferimenti
      a <literal>$var</literal> si cambia soltanto il riferimento della variabile locale.
     </para>
    </warning>
    <note>
     <para>
      Se si assegna un valore ad una variabile con riferimenti in una istruzione
      &foreach;, anche la variabile a cui si fa riferimento sarà modificata.
      <example>
       <title>Riferimenti e istruzione foreach</title>
       <programlisting role="php">
<![CDATA[
<?php
$ref = 0;
$row =& $ref;
foreach (array(1, 2, 3) as $row) {
    // esegue qualcosa
}
echo $ref; // 3 - ultimo elemento dell'array
<?
]]>
       </programlisting>
      </example>
     </para>
    </note>
    <para>
     Anche se non sono esattamente un'assegnazione per riferimento, le espressioni create
     con il costrutto
     <link linkend="function.array"><literal>array()</literal></link> si possono
     comportare come tali anteponendo <literal>&amp;</literal> all'elemento
     da aggiungere. Esempio:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b = array(2, 3);
$arr = array(&$a, &$b[0], &$b[1]);
$arr[0]++; $arr[1]++; $arr[2]++;
/* $a == 2, $b == array(3, 4); */
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     Si noti che i riferimenti all'interno degli array sono potenzialmente pericolosi.
     Un'assegnazione normale (non per riferimento) di un riferimento nella parte destra
     dell'espressione non treasforma in riferimento la variabile nella parte sinistra, ma i riferimenti
     all'interno degli array sono comunque conservati in questo tipo di assegnazioni. Questo si applica
     anche alle chiamate a funzione dove l'array è passato per valore. Esempio:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
/* Assegnazione di variabili scalari */
$a = 1;
$b =& $a;
$c = $b;
$c = 7; //$c non è un riferimento; nessun cambiamento in $a o $b

/* Assegnazione di variabili array */
$arr = array(1);
$a =& $arr[0]; //$a e $arr[0] sono nello stesso insieme di riferimento
$arr2 = $arr; //non è un'assegnazione per riferimento!
$arr2[0]++;
/* $a == 2, $arr == array(2) */
/* Il contenuto di $arr è modificato anche se non è un riferimento! */
?>
]]>
      </programlisting>
     </informalexample>
     In altre parole, da un punto di vista dei riferimenti, il comportamento degli array è definito
     elemento per elemento; il comportamento di ogni singolo elemento
     è indipendente dallo stato di riferimento dell'array che lo contiene.
    </para>
   </sect2>
   <sect2 xml:id="language.references.whatdo.pass">
    <title>Passaggio per Riferimento</title>
    <para>
     Il secondo utilizzo del riferimento è il passaggio di una variabile
     per riferimento. Questo si fa dichiarando una variabile locale di una funzione e
     una variabile nell'ambito della chiamata del riferimento con lo stesso
     contenuto. Esempio:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
function foo(&$var)
{
    $var++;
}

$a=5;
foo($a);
?>
]]>
      </programlisting>
     </informalexample>
     <varname>$a</varname> assume il valore 6. Questo accade perché
     nella funzione <varname>foo</varname>, la variabile
     <varname>$var</varname> si riferisce allo stesso contenuto di
     <varname>$a</varname>. Si vedano le spiegazioni più dettagliate per <link
     linkend="language.references.pass">passaggio per
     riferimento</link>.
    </para>
   </sect2>
   <sect2 xml:id="language.references.whatdo.return">
    <title>Restituzione per Riferimento</title>
    <para>
     Il terzo utilizzo del riferimento è il <link
     linkend="language.references.return">ritorno per riferimento</link>.
    </para>
   </sect2>
  </sect1>

  <sect1 xml:id="language.references.arent">
   <title>Cosa i riferimenti non sono</title>
   <para>
    Come detto prima, i riferimenti non sono puntatori. Questo significa, che
    il seguente costrutto non fà quello che ci si aspetterebbe:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function foo(&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar); 
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    Nell'esempio <varname>$var</varname> in
    <varname>foo</varname> viene scambiato con
    <varname>$bar</varname> nella chiamata, e poi
    riscambiato con <varname>$GLOBALS["baz"]</varname>. Questo non è il modo
    per collegare <varname>$bar</varname> nell'ambito della chiamata con qualcos'altro
    usando il meccanismo di riferimento, poiché <varname>$bar</varname> non è
    disponibile nella funzione <varname>foo</varname> (è rappresentato da
    <varname>$var</varname>, ma <varname>$var</varname> possiede soltanto
    il contenuto della variabile e non il nome del valore collegato nella tabella
    dei simboli).
    Si può utilizzare <link linkend="language.references.return">restiture i
    riferimenti</link> per fare riferimenti a variabili selezionate dalla funzione.
   </simpara>
  </sect1>

  <sect1 xml:id="language.references.pass">
   <title>Passaggio per riferimento</title>
   <para>
   Si può passare una variabile ad una funzione per riferimento, modificandone gli argomenti.
   La sintassi è la seguente:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function foo(&$var)
{
    $var++;
}

$a=5;
foo($a);
// $a adesso è 6
?>
]]>
     </programlisting>
    </informalexample>
    <note>
     <simpara>
      Il simbolo del riferimento non si scrive nella chiamata della funzione, ma solo
      nella sua definizione. La definizione della funzione basta da sola
      per passare correttamente un argomento per riferimento. Dal PHP 5.3.0,
      si avrà un warning indicante che "call-time pass-by-reference" (il passaggio per riferimento al momento della chiamata) è
      deprecato quando si usa &amp; <literal>foo(&amp;$a);</literal>. 
      Da PHP 5.4.0, il passaggio per riferimento al momento della chiamata è stato rimosso, quindi
      usarlo provoca un errore fatale.
     </simpara>
    </note>
  </para>
  <para>
  Le seguenti cose possono essere passate per riferimento:
   <itemizedlist>
    <listitem>
     <simpara>
      Variabili, es. <literal>foo($a)</literal>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Operatore New, es. <literal>foo(new foobar())</literal>
     </simpara>
    </listitem>
    <listitem>
     <para>
      Riferimento restituito da una funzione, es.
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function foo(&$var)
{
    $var++;
}
function &bar()
{
    $a = 5;
    return $a;
}
foo(bar());
?>
]]>
     </programlisting>
    </informalexample>
    Vedere anche le spiegazioni sulla <link
    linkend="language.references.return">restituzione per riferimento</link>. 
     </para>
    </listitem>
  </itemizedlist>
  </para>
  <para>
  Nessun'altra espressione dovrebbe essere passata per riferimento, poiché
  il risultato sarebbe indefinito. Per esempio, i seguenti esempi di passaggio
  per riferimento non sono validi:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function foo(&$var)
{
    $var++;
}
function bar() // Notare l'assenza di &
{
    $a = 5;
    return $a;
}
foo(bar()); // Produce un errore fatale da PHP 5.0.5

foo($a = 5); // Expressione: non una variabile
foo(5); // Genera un errore fatale
?>
]]>
     </programlisting>
    </informalexample>
    Questi requisiti sono validi per PHP 4.0.4 e seguenti.
   </para>
  </sect1>

  <sect1 xml:id="language.references.return">
   <title>Restituzione per riferimento</title>
   <para>
    La restituzione per riferimento è utile quando si vuole usare una funzione
    per trovare quale variabile un riferimento dovrebbe limitare.
    <emphasis>Non</emphasis> utilizzare il ritorno per riferimento per incrementare le prestazioni,
    l'engine è capace di ottimizzare il codice per proprio conto. Restituire valori per riferimento
    solo se si hanno validi motivi tecnici. Per
    restituire per riferimento, si usa questa sintassi:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
class foo {
    public $value = 42;

    public function &getValue() {
        return $this->value;
    }
}

$obj = new foo;
$myValue = &$obj->getValue(); // $myValue è un riferimento a $obj->value, che vale 42.
$obj->value = 2;
echo $myValue;                // stampa il nuovo valore di $obj->value, es. 2.
?> 
]]>
     </programlisting>
    </informalexample>
    In questo esempio, la proprietà dell'oggetto restituito dalla funzione
    <varname>getValue</varname> viene impostata, non la
    copia, come sarebbe stato senza l'uso della sintassi del riferimento.
   </para>
   <note>
    <simpara>
     Diversamente dal passaggio di un parametro, bisogna utilizzare
     <literal>&amp;</literal> in entrambi i posti - nella dichiarazione per indicare che
     si vuole restituire per riferimento, e non per copia come di consueto, 
     e per indicare nella chiamata, il collegamento del riferimento, piuttosto che l'usuale 
     assegnazione che verrebbe fatta per <varname>$myValue</varname>.
    </simpara>
   </note>
   <note>
    <simpara>
     Se si tenta di restituire un valore per riferimento da una funzione con la sintassi:
     <literal>return ($this->value);</literal> questo <emphasis>non</emphasis>
     funzionerà poiché si sta tentando di restituire per riferimento il risultato di un'
     <emphasis>espressione</emphasis>, e non una variabile. Da una funzione, si possono restituire
     per riferimento solo le variabili.
     A partire da PHP 4.4.0 e PHP 5.1.0, un
     errore <constant>E_NOTICE</constant> è lanciato se il codice cerca di restituire
     un'espressione dinamica o un risultato dell'operatore <literal>new</literal>.
    </simpara>
   </note>
   <para>
   Per utilizzare il riferimento restituito, occorre usare l'assegnazione per riferimento:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function &collector() {
  static $collection = array();
  return $collection;
}
$collection = &collector();
$collection[] = 'foo';
?> 
]]>
     </programlisting>
    </informalexample>
   Al fine di passare il riferimento a un'altra funzione che richiede un riferimento
   si può usare questa sintassi:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
function &collector() {
  static $collection = array();
  return $collection;
}
array_push(collector(), 'foo');
?> 
]]>
     </programlisting>
    </informalexample>
   </para>
   <note>
    <simpara>
      Si noti che <literal>array_push(&amp;collector(), 'foo');</literal>
      <emphasis>non</emphasis> funzionerà, ma creerà un errore fatale.
    </simpara>
   </note>
  </sect1>

  <sect1 xml:id="language.references.unset">
   <title>Cancellare riferimenti</title>
   <para>
    Quando si cancella un riferimento, si rompe il collegamento tra il
    nome della variabile e il contenuto della variabile. Questo non significa
    che il contenuto della variabile venga distrutto. Per esempio:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b =& $a;
unset($a); 
?>
]]>
     </programlisting>
    </informalexample>
    non cancella <varname>$b</varname>, ma solo <varname>$a</varname>. 
   </para>
   <simpara>
    Di nuovo, può essere utile pensare a questo con un'analogia col comendo Unix
    <command>unlink</command>.
   </simpara>
  </sect1>

  <sect1 xml:id="language.references.spot">
   <title>Spotting References</title>
   <simpara>
    Diversi costrutti in PHP sono implementati attraverso il meccanismo dei
    riferimenti, dove ogni cosa detta precedentemente, si applica anche a
    questi costrutti. Alcuni, come il passaggio e la
    restituzione per riferimento, sono stati menzionati sopra, gli  
    altri sono:
   </simpara>

   <sect2 xml:id="references.global">
    <title>Il riferimento <literal>global</literal></title>
    <para>
     Quando si dichiara una variabile come <command>global $var</command> di fatto
     si crea un riferimento ad una variabile globale. Questo ha lo stesso significato,
     dell'espressione:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$var =& $GLOBALS["var"];
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     Questo significa, per esempio, che cancellando <varname>$var</varname>
     non si cancella la variabile globale.
    </simpara>
   </sect2>

   <sect2 xml:id="references.this">
    <title><literal>$this</literal></title>
    <simpara>
     In un metodo di un oggetto, <varname>$this</varname> è sempre un riferimento
     all'oggetto chiamante.
    </simpara>
   </sect2>
  </sect1>

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