archived-doc-it/language/constants.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 5a945dfef09a9595c83855cdb858ffa4a96af305 Maintainer: pastore Status: ready -->
<!-- CREDITS: cortesi -->
 <chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
  <title>Costanti</title>

  <simpara>
   Una costante è un identificatore (nome) per un valore. Come si può intuire,
   tale valore non può cambiare durante l'esecuzione dello
   script (fanno eccezione le <link linkend="language.constants.magic">
   costanti magiche</link>, che, in realtà, non sono costanti).
   Le costanti sono "case-sensitive". È convenzione comune che gli identificatori
   delle costanti siano sempre maiuscoli.
  </simpara>

  <note>
   <para>
    Prima di PHP 8.0.0, le costanti definite utilizzando la funzione
    <function>define</function> possono non fare distinzione tra maiuscole e minuscole.
   </para>
  </note>

  <para>
   In PHP il nome di una costante segue le regole di qualsiasi "etichetta".
   Un nome di costante valido inizia con una lettera o underscore, seguita
   da un numero qualsiasi di caratteri alfanumerici o underscore.
   L'espressione regolare che esprime questa convenzione è:
   <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
  </para>
  <para>
   È possibile eseguire la funzione <function>define</function> per definire costanti con nomi riservati o addirittura
   non validi, il cui valore può essere recuperato solo con la
   funzione <function>constant</function>. Tuttavia, non è consigliabile farlo.
  </para>
  &tip.userlandnaming;
  <para>
<!-- TODO Move into syntax section? -->
   <example>
    <title>Nomi di costanti validi ed errati</title>
    <programlisting role="php">
<![CDATA[
<?php

// Nomi validi
define("FOO",     "something");
define("FOO2",    "something else");
define("FOO_BAR", "something more")

// Nomi di costante errati
define("2FOO",    "something");

// Nomi validi, ma da evitare:
// un domani potrebbero essere utilizzati dal PHP per fornire costanti magiche
// e quindi si avrebbero problemi nello script
define("__FOO__", "something");

?>
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <simpara>
    In questo contesto una lettera è a-z, A-Z e i caratteri ASCII
    dal 128 al 255 (0x80-0xff).
   </simpara>
  </note>

  <simpara>
   Come le &link.superglobals;, costante è sempre globale.
   Si può accedere alle costanti da qualsiasi punto dello script senza tenere conto della visibilità.
   Per maggiori dettagli sulla visibilità, leggere la sezione
   <link linkend="language.variables.scope">scope della variable</link>.
  </simpara>

  <note>
   <simpara>
    A partire da PHP 7.1.0, le costanti di classe possono dichiarare una visibilità protetta
    o privata, rendendole disponibili solo nello scope gerarchico della
    classe in cui è definita.
   </simpara>
  </note>

  <sect1 xml:id="language.constants.syntax">
   <title>Sintassi</title>
   <simpara>
    Le costanti possono essere definite utilizzando la parola chiave <literal>const</literal>
    o utilizzando la funzione <function>define</function>.
    Mentre <function>define</function> permette di definire
    una costante in un'espressione arbitraria, la parola chiave <literal>const</literal> ha
    delle restrizioni come descritto nel paragrafo successivo.
    Una volta definita, una costante non può mai essere
    modificata o non definita.
   </simpara>
   <simpara>
    Quando si utilizza la parola chiave <literal>const</literal>,
    sono accettate solo espressioni scalari (<type>bool</type>,
    <type>int</type>, <type>float</type> e <type>string</type>) e
    <type>array</type> costanti contenenti solo espressioni scalari.
    È possibile definire costanti come una <type>resource</type>,
    ma questo dovrebbe essere evitato, poiché può causare risultati inaspettati.
   </simpara>
   <simpara>
    Si accede al valore di una costante semplicemente specificandone il nome.
    A differenza delle variabili, una costante <emphasis>non</emphasis> è preceduta
    da un <literal>$</literal>.
    È anche possibile utilizzare la funzione <function>costant</function> per
    leggere il valore di una costante se il nome della costante è ottenuto dinamicamente.
    Si utilizzi <function>get_defined_constants</function> per ottenere una lista
    di tutte le costanti definite.
   </simpara>

   <note>
    <simpara>
     Costanti e variabili (globali) si trovano in un "namespace" differente.
     Questo implica che generalmente &true; e
     <varname>$TRUE</varname> sono differenti.
    </simpara>
   </note>

   <simpara>
    Se si utilizza una costante non definita, viene generato un <classname>Error</classname>.
    Prima di PHP 8.0.0, le costanti non definite venivano interpretate come una semplice
    parola <type>string</type>, ovvero (COSTANTE vs "COSTANTE").
    Questo fallback è deprecato a partire da PHP 7.2.0, e quando si verifica
    viene emesso un errore di livello <constant>E_WARNING</constant>.
    Prima di PHP 7.2.0, è stato invece emesso un
    errore di livello <link linkend="ref.errorfunc">E_NOTICE</link>. 
    Si veda anche la voce del manuale sul perché
    <link linkend="language.types.array.foo-bar">$foo[bar]</link> è
    sbagliato (a meno che <literal>bar</literal> sia una costante).
    Questo non si applica alle <link
    linkend="language.namespaces.rules">costanti qualificate (completamente)</link>,
    che genereranno sempre un <classname>Error</classname> se non definite.
   </simpara>

   <note>
    <simpara>
     Per verificare che una costante sia impostata, utilizzare la funzione <function>defined</function>.
    </simpara>
   </note>

   <para>
    Di seguito sono riportate le principali differenze rispetto le variabili:
     <itemizedlist>
      <listitem>
       <simpara>
        Le costanti non iniziano con il segno del dollaro
        (<literal>$</literal>);
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Le costanti possono essere definite e utilizzate ovunque
        senza seguire le regole di visibilità;
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Una volta impostate, le costanti non posso essere redefinite
        e né annullate;
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Le costanti possono essere valutate solo come valori scalari o array.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>

   <para>
    <example>
     <title>Definizione di costanti</title>
     <programlisting>
<![CDATA[
<?php
define("COSTANTE", "Ciao mondo.");
echo COSTANTE; // stampa "Ciao mondo."
echo Costante; // Emette un errore: Undefined constant "Constant"
               // Prima di PHP 8.0.0, stampa "Constant" ed emette un avviso.
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Definizione di Costanti utilizzando la parola chiave <literal>const</literal></title>
     <programlisting role="php">
<![CDATA[
<?php
// Valore scalare semplice
const CONSTANT = 'Hello World';

echo CONSTANT;

// Espressione scalare
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
echo ANOTHER_CONST;

const ANIMALS = array('dog', 'cat', 'bird');
echo ANIMALS[1]; // visualizza "cat"

// Array costanti
define('ANIMALS', array(
    'dog',
    'cat',
    'bird'
));
echo ANIMALS[1]; // visualizza "cat"
?>
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
     Al contrario di definire costanti utilizzando <function>define</function>,
     le costanti definite utilizzando la parola chiave <literal>const</literal> devono essere
     dichiarate nella scope del livello superiore perchè sono definite in fase di compilazione.
     Questo significa che non possono essere dichiarate all'interno di funzioni, cicli,
     istruzioni <literal>if</literal> oppure blocchi
     <literal>try</literal>/ <literal>catch</literal>.
    </para>
   </note>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.constants">Costanti di Classe</link></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>
  
  <sect1 xml:id="language.constants.predefined">
   <title>Costanti predefinite</title>

   <simpara>
    PHP fornisce un grande numero di <link
    linkend="reserved.constants">costanti predefinite</link> per qualsiasi script
    che viene eseguito. Molte di queste costanti, comunque, sono create da
    varie estensioni, e saranno presenti solo quando queste estensioni
    sono disponibili, sia perchè vengono caricate dinamicamente e sia perchè
    sono state compilati in PHP.
   </simpara>
  </sect1>

  <sect1 xml:id="language.constants.magic">
   <title>Costanti magiche</title>
   <para>
    Ci sono nove costanti magiche che cambiano in base a
    dove vengono utilizzate.  Per esempio, il valore di
    <constant>__LINE__</constant> dipende dalla linea che sta
    utilizzando nel tuo script. Tutte queste costanti "magiche" vengono risolte
    in fase di compilazione, a differenza delle costanti regolari, che vengono risolte in fase di esecuzione.
    Queste costanti speciali non fanno distinzione tra maiuscole e minuscole e sono le seguenti:
   </para>
   <para>
    <table>
     <title>Costanti magiche di PHP</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>&Name;</entry>
        <entry>&Description;</entry>
       </row>
      </thead>
      <tbody>
       <row xml:id="constant.line">
        <entry><constant>__LINE__</constant></entry>
        <entry>
         Il numero della riga corrente del file.
        </entry>
       </row>
       <row xml:id="constant.file">
        <entry><constant>__FILE__</constant></entry>
        <entry>
         Il percorso completo e il nome del file con i link simbolici risolti. Se utilizzato all'interno di un'inclusione,
         viene restituito il nome del file incluso.
        </entry>
       </row>
       <row xml:id="constant.dir">
        <entry><constant>__DIR__</constant></entry>
        <entry>
         La cartella del file.  Se utilizzato all'interno di un'inclusione,
         viene restituita la cartella del file incluso. Questo è equivalente
         a <literal>dirname(__FILE__)</literal>. Il nome della cartella
         non ha slash a meno che non sia la directory root.
        </entry>
       </row>
       <row xml:id="constant.function">
        <entry><constant>__FUNCTION__</constant></entry>
        <entry>
         Il nome della funzione, o <literal>{closure}</literal> per le funzioni anonime.
        </entry>
       </row>
       <row xml:id="constant.class">
        <entry><constant>__CLASS__</constant></entry>
        <entry>
         Il nome della classe. Il nome della classe include il namespace
         in cui è stata dichiarata (es. <literal>Foo\Bar</literal>).
         Quando usata
         in un metodo trait, __CLASS__ è il nome della classe in cui il trait
         è usato.
        </entry>
       </row>
       <row xml:id="constant.trait">
        <entry><constant>__TRAIT__</constant></entry>
        <entry>
         Il nome del trait. Il nome del trait include il namespace
         in cui è stato dichiarato (es. <literal>Foo\Bar</literal>).
        </entry>
       </row>
       <row xml:id="constant.method">
        <entry><constant>__METHOD__</constant></entry>
        <entry>
         Il nome del metodo della classe. 
        </entry>
       </row>
       <row xml:id="constant.namespace">
        <entry><constant>__NAMESPACE__</constant></entry>
        <entry>
         Il nome del namespace corrente.
        </entry>
       </row>
       <row xml:id="constant.coloncolonclass">
        <entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
        <entry>
         Il nome completo della classe.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.basic.class.class">::class</link></member>
      <member><function>get_class</function></member>
      <member><function>get_object_vars</function></member>
      <member><function>file_exists</function></member>
      <member><function>function_exists</function></member>
     </simplelist>
    </para>
   </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
-->