constants.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: f4f96ef8b2a95283c92ea2183fe1dedf06f3ad22 Maintainer: leonardolara Status: ready --><!-- CREDITS: ae,thiago,lcobucci,fabioluciano,lisaldo,geekcom,gabrielsanva,leonardolara -->
 <chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
  <title>Constantes</title>

  <simpara>
   Uma constante é um identificador (nome) para um valor simples. Como o nome
   sugere, esse valor não pode mudar durante a execução do
   script (exceto para as <link linkend="language.constants.magic">
   constantes mágicas</link>, que na verdade não são constantes).
   As constantes diferenciam maiúsculas de minúsculas. Por convenção,
   identificadores de constantes são sempre em maiúsculas.
  </simpara>

  <note>
   <para>
    Antes do PHP 8.0.0, as constantes definidas usando a função <function>define</function>
    podem não diferenciar maiúsculas de minúsculas.
   </para>
  </note>

  <para>
   O nome de uma constante segue as mesmas regras de qualquer rótulo no PHP. Um
   nome de constante válido começa com uma letra ou sublinhado, seguido
   por qualquer número de letras, números ou sublinhados. Como uma expressão
   regular, seria expresso assim:
   <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
  </para>
  <para>
   É possível usar <function>define</function> para definir constantes com nomes reservados
   ou mesmo inválidos, cujo valor só pode ser recuperado com
   a função <function>constant</function>. No entanto, isso não é recomendado.
  </para>
  &tip.userlandnaming;
  <para>
<!-- TODO Move into syntax section? -->
   <example>
    <title>Nomes de constantes válidos e inválidos</title>
    <programlisting role="php">
<![CDATA[
<?php

// Nomes de constantes válidos
define("FOO",     "alguma coisa");
define("FOO2",    "alguma outra coisa");
define("FOO_BAR", "alguma coisa mais");

// Nomes de constantes inválidos
define("2FOO",    "alguma coisa");

// Isso é válido, mas deve ser evitado:
// O PHP pode um dia fornecer uma constante mágica
// que quebrará seu script
define("__FOO__", "alguma coisa");

?>
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <simpara>
    Para os exemplos aqui, uma letra é a-z, A-Z e os caracteres ASCII
    de 128 a 255 (0x80-0xff).
   </simpara>
  </note>

  <simpara>
   Como as &link.superglobals;, o escopo de uma constante é global.
   As constantes podem ser acessadas de qualquer lugar em um script, independentemente do escopo.
   Para mais informações sobre escopo, leia a seção
   do manual <link linkend="language.variables.scope">escopo de variáveis</link>.
  </simpara>

  <note>
   <simpara>
    A partir do PHP 7.1.0, as constantes de classe podem ser declaradas com visibilidade protected
    ou private, tornando-as disponíveis apenas no escopo hierárquico da
    classe em que foram definidas.
   </simpara>
  </note>

  <sect1 xml:id="language.constants.syntax">
   <title>Sintaxe</title>
   <simpara>
    As constantes podem ser definidas usando a palavra-chave <literal>const</literal>
    ou usando a função <function>define</function>.
    Enquanto <function>define</function> permite que uma constante seja
    definida usando uma expressão arbitrária, a palavra-chave <literal>const</literal> possui
    restrições, conforme descrito no próximo parágrafo.
    Uma vez definida, a constante nunca poderá ser modificada ou
    anulada.
   </simpara>
   <simpara>
    Ao usar a palavra-chave <literal>const</literal>,
    somente expressões escalares (<type>bool</type>, <type>int</type>,
    <type>float</type> e <type>string</type>) e
    <type>array</type>s constantes contendo apenas expressões escalares são aceitos.
    É possível definir constantes como um <type>resource</type>,
    mas isso deve ser evitado, pois pode causar resultados inesperados.
   </simpara>
   <simpara>
    O valor de uma costante é acessado simplesmente informando seu nome.
    Ao contrário das variáveis, uma constante <emphasis>não</emphasis> é precedida
    por um <literal>$</literal>.
    Também é possível usar a função <function>constant</function> para
    ler o valor de uma constante se o nome da constante for obtido dinamicamente.
    Use <function>get_defined_constants</function> para obter uma lista de
    todas as constantes definidas.
   </simpara>

   <note>
    <simpara>
     As constantes e variáveis (globais) estão em espaços de nomes diferentes.
     Isso implica que, por exemplo, &true; e
     <varname>$TRUE</varname> são geralmente diferentes.
    </simpara>
   </note>

   <simpara>
    Se uma constante indefinida for usada, um erro <classname>Error</classname> será lançado.
    Antes do PHP 8.0.0, constantes indefinidas eram interpretadas como uma simples
    <type>string</type>, ou seja, CONSTANTE vs. "CONSTANTE".
    Esse mecanismo alternativo foi descontinuado a partir do PHP 7.2.0 e um alerta de nível
    <constant>E_WARNING</constant> será lançado quando isso acontecer.
    Antes do PHP 7.2.0, um erro de nível
    <link linkend="ref.errorfunc">E_NOTICE</link> era lançado.
    Veja também por que
    <link linkend="language.types.array.foo-bar">$foo[bar]</link> é
    errado (a não ser que <literal>bar</literal> seja uma constante).
    Isso não se aplica às <link
    linkend="language.namespaces.rules">constantes (totalmente) qualificadas</link>,
    que sempre lançarão um <classname>Error</classname> se forem indefinidas.
   </simpara>

   <note>
    <simpara>
     Para verificar se uma constante está definida, use a função <function>defined</function>.
    </simpara>
   </note>

   <para>
    Estas são as diferenças entre constantes e variáveis:
    <itemizedlist>
     <listitem>
      <simpara>
       Constantes não têm um cifrão (<literal>$</literal>)
       antes delas;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Constantes podem ser definidas e acessadas em qualquer lugar sem considerar
       as regras de escopo de variáveis;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Constantes não podem ser redefinidas ou anuladas depois de
       definidas; e
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Constantes só podem ter valores escalares ou arrays.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    <example>
     <title>Definindo Constantes</title>
     <programlisting role="php">
<![CDATA[
<?php
define("CONSTANTE", "Olá Mundo.");
echo CONSTANTE; // imprime "Olá Mundo."
echo Constante; // Lança um erro Error: Undefined constant "Constante"
               // Antes do PHP 8.0.0, imprime "Constante" e emite um aviso.
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Definindo Constantes usando a palavra-chave <literal>const</literal></title>
     <programlisting role="php">
<![CDATA[
<?php
// Valor escalar simples
const CONSTANTE = 'Olá Mundo';

echo CONSTANTE;

// Expressão escalar
const OUTRA_CONSTANTE = CONSTANTE . '; Adeus Mundo';
echo OUTRA_CONSTANTE;

const ANIMAIS = array('cachorro', 'gato', 'pássaro');
echo ANIMAIS[1]; // imprime "gato"

// Array constante
define('ANIMAIS', array(
    'cachorro',
    'gato',
    'pássaro'
));
echo ANIMAIS[1]; // imprime "gato"
?>
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
     Ao contrário das constantes definidas usando <function>define</function>,
     as constantes definidas usando a palavra-chave <literal>const</literal> devem
     ser declaradas no escopo mais externo porque são definidas em tempo de compilação.
     Isto significa que constantes não podem ser declaradas dentro de funções, loops,
     declarações <literal>if</literal> ou
     blocos <literal>try</literal>/<literal>catch</literal>.
    </para>
   </note>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.constants">Constantes de Classe</link></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>

  <sect1 xml:id="language.constants.predefined">
   <title>Constantes Predefinidas</title>

   <simpara>
    O PHP fornece um grande número de <link
    linkend="reserved.constants">constantes predefinidas</link> para qualquer
    script executado. Muitas dessas constantes, no entanto, são criadas por
    várias extensões e só estarão presentes quando essas extensões
    estiverem disponíveis, seja por carregamento dinâmico ou porque foram
    compiladas.
   </simpara>
  </sect1>

  <sect1 xml:id="language.constants.magic">
   <title>Constantes Mágicas</title>
   <para>
    Existem algumas constantes mágicas que mudam dependendo de
    onde são usadas. Por exemplo, o valor de
    <constant>__LINE__</constant> depende da linha em que é
    usada no script. Todas essas constantes "mágicas" são resolvidas
    em tempo de compilação, ao contrário das constantes regulares, que são resolvidas em tempo de execução.
    Essas constantes especiais não diferenciam maiúsculas de minúsculas e são as seguintes:
   </para>
   <para>
    <table>
     <title>Constantes Mágicas do 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>
         O número da linha atual do arquivo.
        </entry>
       </row>
       <row xml:id="constant.file">
        <entry><constant>__FILE__</constant></entry>
        <entry>
         O caminho completo e o nome do arquivo com links simbólicos resolvidos. Se usada dentro de um include,
         o nome do arquivo incluído será retornado.
        </entry>
       </row>
       <row xml:id="constant.dir">
        <entry><constant>__DIR__</constant></entry>
        <entry>
         O diretório do arquivo. Se usada dentro de um include,
         o diretório do arquivo incluído será retornado. Isso é equivalente
         a <literal>dirname(__FILE__)</literal>. O nome do diretório
         não possui barra no final, a menos que seja o diretório raiz.
        </entry>
       </row>
       <row xml:id="constant.function">
        <entry><constant>__FUNCTION__</constant></entry>
        <entry>
         O nome da função ou <literal>{closure}</literal> para funções anônimas.
        </entry>
       </row>
       <row xml:id="constant.class">
        <entry><constant>__CLASS__</constant></entry>
        <entry>
         O nome da classe. O nome da classe inclui o namespace
         em que foi declarada (por exemplo, <literal>Foo\Bar</literal>).
         Quando usada dentro de um método de trait,
         <constant>__CLASS__</constant> é o nome da classe em que o trait
         for usado.
        </entry>
       </row>
       <row xml:id="constant.trait">
        <entry><constant>__TRAIT__</constant></entry>
        <entry>
         O nome do trait. O nome do trait inclui o namespace em
         que foi declarado (por exemplo, <literal>Foo\Bar</literal>).
        </entry>
       </row>
       <row xml:id="constant.method">
        <entry><constant>__METHOD__</constant></entry>
        <entry>
         O nome do método da classe.
        </entry>
       </row>
       <row xml:id="constant.property">
        <entry><constant>__PROPERTY__</constant></entry>
        <entry>
         Válido somente dentro de um
         <link linkend="language.oop5.property-hooks">gancho de propriedade</link>.
         É igual ao nome da propriedade.
        </entry>
       </row>
       <row xml:id="constant.namespace">
        <entry><constant>__NAMESPACE__</constant></entry>
        <entry>
         O nome do namespace atual.
        </entry>
       </row>
       <row xml:id="constant.coloncolonclass">
        <entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
        <entry>
         O nome totalmente qualificado da 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
-->