archived-doc-es/language/constants.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: f4f96ef8b2a95283c92ea2183fe1dedf06f3ad22 Maintainer: lacatoire Status: ready -->
<!-- Reviewed: yes -->
 <chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
  <title>Constantes</title>

  <simpara>
   Una constante es un identificador (nombre) para un valor simple. Como su
   nombre sugiere, ese valor no puede cambiar durante la ejecución del
   script (excepto las <link linkend="language.constants.magic">
   constantes mágicas</link>, que en realidad no son constantes).
   Las constantes distinguen entre mayúsculas y minúsculas. Por convención,
   los identificadores de constantes se escriben siempre en mayúsculas.
  </simpara>

  <note>
   <para>
    Antes de PHP 8.0.0, las constantes definidas con la función
    <function>define</function> podían no distinguir entre mayúsculas
    y minúsculas.
   </para>
  </note>

  <para>
   El nombre de una constante sigue las mismas reglas que cualquier etiqueta
   en PHP. Un nombre de constante válido comienza con una letra o guion bajo,
   seguido de cualquier cantidad de letras, números o guiones bajos. Como
   expresión regular, se expresaría así:
   <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
  </para>
  <para>
   Es posible definir constantes con <function>define</function> usando nombres
   reservados o incluso inválidos, cuyo valor solo puede obtenerse con la
   función <function>constant</function>. Sin embargo, no se recomienda hacerlo.
  </para>
  &tip.userlandnaming;
  <para>
<!-- TODO Move into syntax section? -->
   <example>
    <title>Nombres de constantes válidos e inválidos</title>
    <programlisting role="php">
<![CDATA[
<?php

// Nombres de constantes válidos
define("FOO",     "something");
define("FOO2",    "something else");
define("FOO_BAR", "something more");

// Nombres de constantes inválidos
define("2FOO",    "something");

// Esto es válido, pero debe evitarse:
// PHP podría algún día proporcionar una constante mágica
// que rompa el script
define("__FOO__", "something");

?>
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <simpara>
    Para estos propósitos, una letra es a-z, A-Z y los caracteres
    ASCII del 128 al 255 (0x80-0xff).
   </simpara>
  </note>

  <simpara>
   Al igual que las &link.superglobals;, el ámbito de una constante es global.
   Las constantes pueden ser accedidas desde cualquier lugar del script sin
   importar el ámbito. Para más información sobre el ámbito, consulte la
   sección del manual sobre
   <link linkend="language.variables.scope">ámbito de las variables</link>.
  </simpara>

  <note>
   <simpara>
    A partir de PHP 7.1.0, las constantes de clase pueden declarar una
    visibilidad protected o private, haciéndolas disponibles únicamente en
    el ámbito jerárquico de la clase en la que se definen.
   </simpara>
  </note>

  <sect1 xml:id="language.constants.syntax">
   <title>Sintaxis</title>
   <simpara>
    Las constantes pueden definirse usando la palabra clave
    <literal>const</literal> o usando la función <function>define</function>.
    Mientras que <function>define</function> permite definir una constante
    con una expresión arbitraria, la palabra clave <literal>const</literal>
    tiene restricciones como se describe en el siguiente párrafo.
    Una vez definida, una constante no puede ser modificada ni eliminada.
   </simpara>
   <simpara>
    Al usar la palabra clave <literal>const</literal>, solo se aceptan
    expresiones escalares (<type>bool</type>, <type>int</type>,
    <type>float</type> y <type>string</type>) y <type>array</type>s
    constantes que contengan únicamente expresiones escalares.
    Es posible definir constantes como <type>resource</type>,
    pero debe evitarse, ya que puede causar resultados inesperados.
   </simpara>
   <simpara>
    El valor de una constante se obtiene simplemente especificando su nombre.
    A diferencia de las variables, una constante <emphasis>no</emphasis>
    va precedida de un signo <literal>$</literal>.
    También es posible usar la función <function>constant</function> para
    leer el valor de una constante si su nombre se obtiene dinámicamente.
    Use <function>get_defined_constants</function> para obtener una lista de
    todas las constantes definidas.
   </simpara>

   <note>
    <simpara>
     Las constantes y las variables (globales) se encuentran en espacios de
     nombres diferentes. Esto implica que, por ejemplo, &true; y
     <varname>$TRUE</varname> son generalmente diferentes.
    </simpara>
   </note>

   <simpara>
    Si se usa una constante no definida, se lanza un <classname>Error</classname>.
    Antes de PHP 8.0.0, las constantes no definidas se interpretaban como una
    cadena (<type>string</type>) sin comillas, es decir (CONSTANT vs "CONSTANT").
    Este comportamiento está obsoleto desde PHP 7.2.0, y se emite un error de
    nivel <constant>E_WARNING</constant> cuando ocurre.
    Antes de PHP 7.2.0, se emitía un error de nivel
    <link linkend="ref.errorfunc">E_NOTICE</link>.
    Consulte también la entrada del manual sobre por qué
    <link linkend="language.types.array.foo-bar">$foo[bar]</link> es
    incorrecto (a menos que <literal>bar</literal> sea una constante).
    Esto no se aplica a las <link
    linkend="language.namespaces.rules">constantes (totalmente) cualificadas</link>,
    que siempre lanzarán un <classname>Error</classname> si no están definidas.
   </simpara>

   <note>
    <simpara>
     Para comprobar si una constante está definida, use la función
     <function>defined</function>.
    </simpara>
   </note>

   <para>
    Estas son las diferencias entre constantes y variables:
    <itemizedlist>
     <listitem>
      <simpara>
       Las constantes no llevan el signo de dólar (<literal>$</literal>)
       delante;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Las constantes pueden definirse y accederse desde cualquier lugar
       sin importar las reglas de ámbito de las variables;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Las constantes no pueden redefinirse ni eliminarse una vez
       establecidas; y
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Las constantes solo pueden evaluarse a valores escalares o arrays.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    <example>
     <title>Definición de constantes</title>
     <programlisting role="php">
<![CDATA[
<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // muestra "Hello world."
echo Constant; // Lanza un Error: Undefined constant "Constant"
               // Antes de PHP 8.0.0, muestra "Constant" y emite una advertencia.
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Definición de constantes usando la palabra clave <literal>const</literal></title>
     <programlisting role="php">
<![CDATA[
<?php
// Valor escalar simple
const CONSTANT = 'Hello World';

echo CONSTANT;

// Expresión escalar
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
echo ANOTHER_CONST;

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

// Arrays constantes
define('ANIMALS', array(
    'dog',
    'cat',
    'bird'
));
echo ANIMALS[1]; // muestra "cat"
?>
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
     A diferencia de la definición de constantes con <function>define</function>,
     las constantes definidas con la palabra clave <literal>const</literal>
     deben declararse en el ámbito de nivel superior porque se definen en
     tiempo de compilación. Esto significa que no pueden declararse dentro
     de funciones, bucles, instrucciones <literal>if</literal> o bloques
     <literal>try</literal>/<literal>catch</literal>.
    </para>
   </note>

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

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

   <simpara>
    PHP proporciona un gran número de <link
    linkend="reserved.constants">constantes predefinidas</link> a cualquier
    script que ejecuta. Muchas de estas constantes, sin embargo, son creadas
    por diversas extensiones, y solo estarán presentes cuando esas extensiones
    estén disponibles, ya sea mediante carga dinámica o porque se han
    compilado con PHP.
   </simpara>
  </sect1>

  <sect1 xml:id="language.constants.magic">
   <title>Constantes mágicas</title>
   <para>
    Existen varias constantes mágicas que cambian dependiendo de
    dónde se utilicen. Por ejemplo, el valor de
    <constant>__LINE__</constant> depende de la línea en la que se
    use en el script. Todas estas constantes "mágicas" se resuelven
    en tiempo de compilación, a diferencia de las constantes regulares,
    que se resuelven en tiempo de ejecución.
    Estas constantes especiales no distinguen entre mayúsculas y minúsculas
    y son las siguientes:
   </para>
   <para>
    <table>
     <title>Constantes mágicas de 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>
         El número de línea actual del archivo.
        </entry>
       </row>
       <row xml:id="constant.file">
        <entry><constant>__FILE__</constant></entry>
        <entry>
         La ruta completa y el nombre del archivo con los enlaces simbólicos
         resueltos. Si se usa dentro de un include, se devuelve el nombre
         del archivo incluido.
        </entry>
       </row>
       <row xml:id="constant.dir">
        <entry><constant>__DIR__</constant></entry>
        <entry>
         El directorio del archivo. Si se usa dentro de un include,
         se devuelve el directorio del archivo incluido. Es equivalente a
         <literal>dirname(__FILE__)</literal>. El nombre del directorio
         no incluye la barra final a menos que sea el directorio raíz.
        </entry>
       </row>
       <row xml:id="constant.function">
        <entry><constant>__FUNCTION__</constant></entry>
        <entry>
         El nombre de la función, o <literal>{closure}</literal> para
         las funciones anónimas.
        </entry>
       </row>
       <row xml:id="constant.class">
        <entry><constant>__CLASS__</constant></entry>
        <entry>
         El nombre de la clase. El nombre de la clase incluye el espacio de
         nombres en el que fue declarada (p. ej. <literal>Foo\Bar</literal>).
         Cuando se usa en un método de trait, <constant>__CLASS__</constant>
         es el nombre de la clase en la que se utiliza el trait.
        </entry>
       </row>
       <row xml:id="constant.trait">
        <entry><constant>__TRAIT__</constant></entry>
        <entry>
         El nombre del trait. El nombre del trait incluye el espacio de
         nombres en el que fue declarado (p. ej. <literal>Foo\Bar</literal>).
        </entry>
       </row>
       <row xml:id="constant.method">
        <entry><constant>__METHOD__</constant></entry>
        <entry>
         El nombre del método de la clase.
        </entry>
       </row>
       <row xml:id="constant.property">
        <entry><constant>__PROPERTY__</constant></entry>
        <entry>
         Solo es válido dentro de un <link linkend="language.oop5.property-hooks">hook
         de propiedad</link>. Es igual al nombre de la propiedad.
        </entry>
       </row>
       <row xml:id="constant.namespace">
        <entry><constant>__NAMESPACE__</constant></entry>
        <entry>
         El nombre del espacio de nombres actual.
        </entry>
       </row>
       <row xml:id="constant.coloncolonclass">
        <entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
        <entry>
         El nombre completo cualificado de la clase.
        </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
-->