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

<chapter xml:id="language.namespaces" xmlns="http://docbook.org/ns/docbook"

version="1.1">

<title>Los espacios de nombres</title>

<sect1 xml:id="language.namespaces.rationale">

<title>Introducción a los espacios de nombres</title>

<titleabbrev>Introducción</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<simpara>

¿Qué son los espacios de nombres? En su definición más amplia, representan

un medio para encapsular elementos. Esto puede concebirse como un concepto

abstracto, por varias razones. Por ejemplo, en un sistema de archivos, los

directorios representan un grupo de archivos asociados y sirven como espacio de nombres

para los archivos que contienen. Un ejemplo concreto es que el archivo

<literal>foo.txt</literal> puede existir en ambos directorios

<literal>/home/greg</literal> y <literal>/home/other</literal>, pero que

las dos copias de <literal>foo.txt</literal> no pueden coexistir

en el mismo directorio. Además, para acceder al archivo <literal>foo.txt</literal>

desde fuera del directorio <literal>/home/greg</literal>, es necesario especificar

el nombre del directorio utilizando un separador de directorios, como

<literal>/home/greg/foo.txt</literal>. El mismo principio se aplica a los

espacios de nombres en el mundo de la programación.

</simpara>

<simpara>

En el mundo de PHP, los espacios de nombres están diseñados para resolver dos problemas

que enfrentan los autores de bibliotecas y aplicaciones al reutilizar elementos

como clases o bibliotecas de funciones:

</simpara>

<para>

<orderedlist>

<listitem>

<simpara>

Colisiones de nombres entre el código que se crea, las clases, funciones

o constantes internas de PHP, o las de bibliotecas de terceros.

</simpara>

</listitem>

<listitem>

<simpara>

La capacidad de crear alias o acortar nombres como Nombres_Extremadamente_Largos

para ayudar a resolver el primer problema y mejorar la legibilidad

del código.

</simpara>

</listitem>

</orderedlist>

</para>

<simpara>

Los espacios de nombres de PHP proporcionan un medio para agrupar clases, interfaces,

funciones o constantes. Aquí hay un ejemplo de sintaxis de los espacios de nombres de PHP:

</simpara>

<example>

<title>Ejemplo de sintaxis de espacios de nombres</title>

<titleabbrev>Espacios de nombres</titleabbrev>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

<note>

<simpara>

Los nombres de espacios de nombres no son sensibles a mayúsculas/minúsculas.

</simpara>

</note>

<note>

<para>

Los espacios de nombres <literal>PHP</literal>, así como los nombres compuestos

que comienzan con estos nombres (como <literal>PHP\Classes</literal>)

están reservados para el uso interno del lenguaje y no deben usarse

en el código del espacio de usuario.

</para>

</note>

</sect1>

<sect1 xml:id="language.namespaces.definition">

<title>Definición de espacios de nombres</title>

<?phpdoc print-version-for="namespaces"?>

<para>

Aunque el código PHP válido puede contenerse en un espacio de nombres,

solo los siguientes tipos de código pueden verse afectados por los espacios de nombres:

las clases (incluyendo las abstractas, los traits y los enums), las interfaces,

las funciones y las constantes.

</para>

<para>

Los espacios de nombres se declaran con la palabra clave <literal>namespace</literal>.

Un archivo que contiene un espacio de nombres debe declarar el espacio al principio

del archivo, antes de cualquier otro código, con una sola excepción: la palabra

clave <xref linkend="control-structures.declare" />.

<example>

<title>Declaración de un espacio de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

<note>

<simpara>

Los nombres completamente calificados (es decir, los nombres que comienzan con un backslash)

no están autorizados en las declaraciones de espacios de nombres, ya que tales

construcciones se interpretan como expresiones de espacio de nombres relativo.

</simpara>

</note>

El único elemento autorizado antes de la declaración de espacio de nombres es la instrucción

<literal>declare</literal>, para definir la codificación del archivo fuente. Además,

ningún código no-PHP puede preceder a la declaración de espacio de nombres, incluyendo

espacios:

<example>

<title>Error de declaración de un espacio de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Además, a diferencia de otras estructuras de PHP, el mismo espacio de nombres puede

definirse en varios archivos, lo que permite dividir el contenido de un

espacio de nombres en varios archivos.

</para>

</sect1>

<sect1 xml:id="language.namespaces.nested">

<title>Declaración de un subespacio de nombres</title>

<titleabbrev>Subespacio de nombres</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Al igual que con los archivos y los directorios, los espacios de nombres también

son capaces de especificar una jerarquía de espacios de nombres. Por lo tanto,

un nombre de espacio de nombres puede definirse con sus subniveles:

<example>

<title>Declaración de un espacio de nombres con jerarquía</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

En el ejemplo anterior, se crean la constante <literal>MonProjet\Sous\Niveau\CONNEXION_OK</literal>,

la clase <literal>MonProjet\Sous\Niveau\Connexion</literal> y la función

<literal>MonProjet\Sous\Niveau\connecte</literal>.

</para>

</sect1>

<sect1 xml:id="language.namespaces.definitionmultiple">

<title>Definición de varios espacios de nombres en el mismo archivo</title>

<titleabbrev>Definición de varios espacios de nombres en el mismo archivo</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

También pueden declararse varios espacios de nombres en el mismo archivo.

Hay dos sintaxis autorizadas.

</para>

<para>

<example>

<title>Declaración de varios espacios de nombres, sintaxis de combinación simple</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Esta sintaxis no se recomienda para combinar espacios de nombres

en un solo archivo. En su lugar, se recomienda utilizar

la sintaxis de llaves.

</para>

<para>

<example>

<title>Declaración de varios espacios de nombres, sintaxis de llaves</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Se recomienda encarecidamente, como práctica de codificación, no mezclar

varios espacios de nombres en el mismo archivo. El uso recomendado es combinar

varios scripts PHP en el mismo archivo.

</para>

<para>

Para combinar varios códigos sin espacios de nombres en código con espacio de nombres,

solo se admite la sintaxis de llaves. El código global debe estar encerrado por un

espacio de nombres sin nombre, como este:

<example>

<title>Declaración de varios espacios de nombres con un espacio sin nombre</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

No puede existir ningún código PHP fuera de las llaves del espacio de nombres,

excepto para abrir una nueva instrucción <literal>declare</literal>.

<example>

<title>Declaración de varios espacios de nombres con un espacio sin nombre (2)</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.basics">

<title>Uso de espacios de nombres: introducción</title>

<titleabbrev>Introducción</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Antes de discutir el uso de espacios de nombres, es importante comprender

cómo PHP deduce qué espacio de nombres está utilizando su código. Puede hacerse

una analogía simple entre los espacios de nombres de PHP y un sistema de archivos.

Hay tres formas de acceder a un archivo en un sistema de archivos:

<orderedlist>

<listitem>

<simpara>

Un nombre de archivo relativo, como <literal>foo.txt</literal>. Esto se resuelve

en <literal>dossiercourant/foo.txt</literal> donde <literal>dossiercourant</literal> es el

directorio de trabajo. Si el directorio actual es <literal>/home/foo</literal>,

este nombre se resuelve en <literal>/home/foo/foo.txt</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Una ruta relativa, como <literal>sub-dossier/foo.txt</literal>. Esto se

resuelve en <literal>dossiercourant/sub-dossier/foo.txt</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Una ruta absoluta, como <literal>/main/foo.txt</literal>. Esto se resuelve

en <literal>/main/foo.txt</literal>.

</simpara>

</listitem>

</orderedlist>

El mismo principio puede aplicarse a los espacios de nombres de PHP.

Por ejemplo, puede hacer referencia a una clase de tres maneras:

<orderedlist>

<listitem>

<simpara>

Un nombre sin calificador, o una clase sin prefijo, como

<literal>$a = new foo();</literal> o

<literal>foo::methodestatique();</literal>. Si el espacio de nombres actual

es <literal>espacedenomscourant</literal>, esto se resuelve en

<literal>espacedenomscourant\foo</literal>. Si el espacio de nombres es

global, es decir, el espacio de nombres sin nombre, esto se convierte en <literal>foo</literal>.

</simpara>

<simpara>

Una advertencia: los nombres sin calificador para funciones y constantes

se tomarán del espacio de nombres global, si la función

no está definida en el espacio de nombres actual. Ver

<link linkend="language.namespaces.fallback">Uso de espacios de nombres:

retorno al espacio de nombres global para funciones y constantes</link> para

más detalles.

</simpara>

</listitem>

<listitem>

<simpara>

Un nombre calificado, o una clase con prefijo como

<literal>$a = new sousespacedenoms\foo();</literal> o

<literal>sousespacedenoms\foo::methodestatique();</literal>. Si el espacio de nombres actual

es <literal>espacedenomscourant</literal>, esto se convierte

en <literal>espacedenomscourant\sousespacedenoms\foo</literal>. Si

el código es global, es decir, el espacio de nombres sin nombre,

esto se convierte en <literal>sousespacedenoms\foo</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Un nombre absoluto, o un nombre con prefijo con un operador global como

<literal>$a = new \espacedenomscourant\foo();</literal> o

<literal>\espacedenomscourant\foo::methodestatique();</literal>. Esto siempre

hace referencia al nombre literal especificado en el código: <literal>espacedenomscourant\foo</literal>.

</simpara>

</listitem>

</orderedlist>

</para>

<para>

Aquí hay un ejemplo de las tres sintaxis, en código real:

<informalexample>

<simpara>file1.php</simpara>

<programlisting role="php">

<![CDATA[

</programlisting>

<simpara>file2.php</simpara>

<programlisting role="php">

<![CDATA[

</programlisting>

</informalexample>

</para>

<para>

Tenga en cuenta que para acceder a cualquier clase, función o constante

global, puede utilizarse un nombre absoluto, como

<function>\strlen</function> o <classname>\Exception</classname> o

\<constant>INI_ALL</constant>.

<example>

<title>Acceso a clases, funciones y constantes globales desde un espacio de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.dynamic">

<title>Espacios de nombres y lenguaje dinámico</title>

<titleabbrev>Espacios de nombres y lenguaje dinámico</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

La implementación de espacios de nombres de PHP está influenciada por su naturaleza

dinámica como lenguaje de programación. Por lo tanto, para convertir código como el

del siguiente ejemplo en un espacio de nombres:

<example>

<title>Acceso dinámico a elementos</title>

<simpara>example1.php:</simpara>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

Es necesario utilizar un nombre absoluto (el nombre de la clase, con su prefijo de espacio de nombres).

Tenga en cuenta que no hay diferencia entre un nombre absoluto y un nombre calificado

en un nombre de clase, función o constante dinámica, lo que hace que el backslash

inicial no sea necesario.

<example>

<title>Acceso dinámico a espacios de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Se recomienda leer la <link linkend="language.namespaces.faq.quote">nota sobre la protección de espacios de nombres en cadenas</link>.

</para>

</sect1>

<sect1 xml:id="language.namespaces.nsconstants">

<title>El comando namespace y la constante __NAMESPACE__</title>

<titleabbrev>Comando namespace y __NAMESPACE__</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

PHP admite dos medios para acceder de manera abstracta a los elementos

en el espacio de nombres actual, a saber, la constante mágica

<constant>__NAMESPACE__</constant> y el comando <literal>namespace</literal>.

</para>

<para>

El valor de <constant>__NAMESPACE__</constant> es una cadena que contiene el nombre

del espacio de nombres actual. En el espacio global, sin nombre, contiene

una cadena vacía.

<example>

<title>Ejemplo con __NAMESPACE__, en un código con espacio de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

<example>

<title>Ejemplo con __NAMESPACE__, en un código con espacio de nombres global</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

La constante <constant>__NAMESPACE__</constant> es útil para construir

dinámicamente nombres, como:

<example>

<title>Uso de __NAMESPACE__ para una construcción dinámica de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

El comando <literal>namespace</literal> también puede usarse para

solicitar explícitamente un elemento del espacio de nombres actual, o de un

subespacio. Es el equivalente para los espacios de nombres del operador

<literal>self</literal> de las clases.

<example>

<title>El operador namespace, en un espacio de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

<example>

<title>El operador namespace, en el espacio de nombres global</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.importing">

<?phpdoc print-version-for="namespaces"?>

<title>Uso de espacios de nombres: importación y alias</title>

<titleabbrev>Importación y alias</titleabbrev>

<para>

La capacidad de hacer referencia a un nombre absoluto con un alias o importando

un espacio de nombres es estratégica. Es un beneficio similar a los enlaces

simbólicos en un sistema de archivos.

</para>

<para>

PHP puede crear alias(/importar) constantes, funciones, clases, interfaces,

traits, enumeraciones y espacios de nombres.

</para>

<para>

Un alias se crea con el operador <literal>use</literal>.

Aquí hay un ejemplo que presenta los cinco tipos de importación:

<example>

<title>Importación y alias con el operador use</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

Tenga en cuenta que para los nombres con ruta (los nombres absolutos que contienen

separadores de espacios, como <literal>Foo\Bar</literal>, en comparación con

los nombres globales, como <literal>FooBar</literal>, que no los contienen),

el backslash inicial no es necesario y no se recomienda, ya que los nombres importados

deben ser absolutos y no se resuelven relativamente al espacio de nombres actual.

</para>

<para>

Además, PHP admite atajos prácticos, como las instrucciones use múltiples.

<example>

<title>Importación y alias múltiples con el operador use</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

La importación se realiza durante la compilación, por lo que no afecta

a las clases, funciones y constantes dinámicas.

<example>

<title>Importación y nombres de espacios dinámicos</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Además, la importación solo afecta a los nombres sin calificación. Los nombres

absolutos siguen siendo absolutos y no se modifican por una importación.

<example>

<title>Importación y nombres de espacios absolutos</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<sect2 xml:id="language.namespaces.importing.scope">

<title>Reglas de contexto para la importación</title>

<para>

La palabra clave <literal>use</literal> debe declararse en el contexto más

externo de un archivo (el contexto global) o en las declaraciones de espacio

de nombres. Esto se debe a que la importación se realiza durante la compilación

y no durante la ejecución, por lo que no se pueden apilar los contextos. El ejemplo

siguiente muestra usos incorrectos de la palabra clave <literal>use</literal>:

</para>

<para>

<example>

<title>Reglas de importación incorrectas</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<note>

<para>

Las reglas de importación se basan en archivos, lo que significa que los archivos

incluidos no heredarán <emphasis>PAS</emphasis> las reglas de importación del archivo padre.

</para>

</note>

</sect2>

<sect2 xml:id="language.namespaces.importing.group">

<title>Declaración del grupo <literal>use</literal></title>

<para>

Las clases, funciones y constantes importadas desde

el mismo &namespace; pueden agruparse en una

sola instrucción &use.namespace;.

</para>

<informalexample>

<programlisting role="php">

</programlisting>

</informalexample>

</sect2>

</sect1>

<sect1 xml:id="language.namespaces.global">

<title>Espacio de nombres global</title>

<titleabbrev>Global</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Sin ninguna definición de espacio de nombres, todas las clases y las funciones

se colocan en el espacio de nombres global: como en PHP antes de que los espacios

de nombres fueran introducidos. Al prefijar un nombre con un backslash

<literal>\</literal>, se puede solicitar el uso del espacio de nombres

global, incluso en un contexto de espacio de nombres específico.

<example>

<title>Especificación de espacio de nombres global</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.fallback">

<title>Uso de espacios de nombres: retorno al espacio global para funciones y constantes</title>

<titleabbrev>Retorno al espacio global</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

En un espacio de nombres, cuando PHP encuentra un nombre sin calificación,

ya sea una clase, una función o una constante, lo resuelve con diferentes

prioridades. Los nombres de clases siempre se resuelven con el espacio de nombres actual.

Para acceder a clases internas o a clases que no están en

un espacio de nombres, es necesario representarlas con su nombre absoluto, como:

<example>

<title>Acceso a clases globales desde un espacio de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

<para>

Para las funciones y constantes, PHP las buscará en el espacio

global si no puede encontrarlas en el espacio de nombres actual.

<example>

<title>Acceso a funciones y constantes globales en un espacio de nombres</title>

<programlisting role="php">

<![CDATA[

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.rules">

<title>Reglas de resolución de nombres</title>

<titleabbrev>Reglas de resolución de nombres</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

En el contexto de las reglas de resolución, hay varias definiciones importantes:

<variablelist>

<title>Definiciones para espacios de nombres</title>

<varlistentry>

<term>nombre no calificado</term>

<listitem>

<para>

Esto es un identificador que no contiene un separador de espacio de nombres.

Por ejemplo: <literal>Foo</literal>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>nombre calificado</term>

<listitem>

<para>

Esto es un identificador que contiene un separador de espacio de nombres.

Por ejemplo: <literal>Foo\Bar</literal>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Nombre absoluto</term>

<listitem>

<para>

Esto es un identificador que comienza con un separador de espacio de nombres.

Por ejemplo: <literal>\Foo\Bar</literal>. El espacio de nombres <literal>Foo</literal>

también es un nombre absoluto.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Nombre Relativo</term>

<listitem>

<para>

Es un identificador que comienza con <literal>namespace</literal>, como

<literal>namespace\Foo\Bar</literal>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>

Los nombres se resuelven siguiendo las siguientes reglas:

<orderedlist>

<listitem>

<simpara>

Los nombres absolutos siempre se traducen a nombres sin el separador de namespace.

Por ejemplo, <literal>\A\B</literal> se traduce a <literal>A\B</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Todos los nombres que no son absolutos se traducen con

<literal>namespace</literal> reemplazado por el namespace actual.

Si el nombre aparece en el namespace global, el prefijo

<literal>namespace\</literal> se elimina. Por ejemplo <literal>namespace\A</literal>

en el namespace <literal>X\Y</literal> se traduce a <literal>X\Y\A</literal>.

El mismo nombre en el namespace global se traduce a <literal>A</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Para los nombres absolutos, el primer segmento se traduce

de acuerdo con la clase/namespace de la tabla de importación.

Por ejemplo, si el namespace <literal>A\B\C</literal> se importa como <literal>C</literal>, el nombre <literal>C\D\E</literal> se traduce a <literal>A\B\C\D\E</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Para los nombres absolutos, si ninguna regla de importación

se aplica, el namespace actual se prefiere al nombre.

Por ejemplo, el nombre <literal>C\D\E</literal> en el namespace <literal>A\B</literal>,

se traduce a <literal>A\B\C\D\E</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Para los nombres absolutos, el nombre se traduce en relación con la tabla actual de importación para el tipo de símbolo respectivo.

Esto significa que un nombre que se asemeja a una clase se traduce de acuerdo con la tabla de importación de

class/namespace, los nombres de funciones utilizando la

tabla de importación de funciones, y las constantes utilizando la tabla de importación de constantes.

Por ejemplo, después

<literal>use A\B\C;</literal> un uso como <literal>new C()</literal> corresponde al nombre

<literal>A\B\C()</literal>. De manera similar, después de <literal>use function A\B\foo;</literal> un uso

como <literal>foo()</literal> corresponde al nombre <literal>A\B\foo</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Para los nombres relativos, si ninguna regla se aplica, y el nombre

hace referencia a una clase, el namespace actual sirve como prefijo.

Por ejemplo <literal>new C()</literal> en el namespace

<literal>A\B</literal> corresponde al nombre <literal>A\B\C</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Para los nombres relativos, si ninguna regla se aplica, y el nombre

hace referencia a una función o constante, y el código está

fuera del namespace global, el nombre se resuelve durante la ejecución.

Supongamos que el código está en el namespace

<literal>A\B</literal>, aquí es cómo se resuelve una llamada a la función <literal>foo()</literal>:

</simpara>

<orderedlist>