Uso de los espacios de nombres: apodar/importar
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
La capacidad de referirse a un nombre completamente cualificado externo con un alias, o importar,
es una característca importante de los espacios de nombres. Esto es similar a la capacidad
de los sistemas de ficheros basados en Unix de crear enlaces simbólicos a un fichero o directorio.
Todas las versiones de PHP que tienen soporte para espacios de nombres admiten tres tipos de alias
o importación: apodar un nombre de clase, apodar un nombre de interfaz, y
apodar un nombre de espacio de nombres. PHP 5.6+ también permite apodar o importar
nombres de funciones y constantes.
En PHP, la acción de apodar se lleva a cabo con el operador use
.
Aquí hay un ejemplo que muestra los cinco tipos de importación:
Ejemplo #1 Importar/apodar con el operador use
<?php
namespace foo;
use Mi\Completo\NombreDeClase as Otra;
// esto es lo mismo que utilizar Mi\Completo\NombreEN as NombreEN
use Mi\Completo\NombreEN;
// importar una clase global
use ArrayObject;
// importar una función (PHP 5.6+)
use function Mi\Completo\nombreDeFunción;
// apodar una función (PHP 5.6+)
use function Mi\Completo\nombreDeFunción as func;
// importar una constante (PHP 5.6+)
use const Mi\Completa\CONSTANTE;
$obj = new namespace\Otra; // instancia un objeto de la clase foo\Otra
$obj = new Otra; // instancia un objeto de la clase class Mi\Completo\NombreDeClase
NombreEN\suben\func(); // llama a la función Mi\Completo\NombreEN\subes\func
$a = new ArrayObject(array(1)); // instancia un objeto de la clase ArrayObject
// sin el "use ArrayObject" instanciaríamos un objeto de la clase foo\ArrayObject
func(); // llama a la función Mi\Completo\nombreDeFunción
echo CONSTANT; // imprime el valor de Mi\Completa\CONSTANTE;
?>
Observe que para los nombres de espacios de nombres (nombres de espacios de nombres completamente
cualificados que contienen el separador de espacios de nombres, como
Foo\Bar
, en
oposición a los nombres globales que no lo contienen, como
FooBar
), no es necesaria
y no está recomendada la barra invertida inicial, ya que los nombres importados
deben ser completamente cualificados, por lo que no son procesados en relación al espacio de nombres actual.
PHP admite además un atajo para poner varias sentencias use
en la misma línea
Ejemplo #2 Importar/apodar con el operador use, varias sentencias use combinadas
<?php
use Mi\Completo\NombreDeClase as Otra, Mi\Completo\NombreEN;
$obj = new Otra; // instancia un objeto de la clase Mi\Completo\NombreDeClase
NombreEN\suben\func(); // llama a la función Mi\Completo\NombreEN\suben\func
?>
La importación se realiza durante la compilación, por lo que no afecta a los nombres de clases,
funciones o constantes.
Ejemplo #3 La importación y los nombres dinámicos
<?php
use Mi\Completo\NombreDeClase as Otra, Mi\Completo\NombreEN;
$obj = new Otra; // instancia un objeto de la clase Mi\Completo\NombreDeClase
$a = 'Otra';
$obj = new $a; // instancia un objeto de la clase Otra
?>
Además, la importación sólo afecta a los nombres cualificados y no cualificados. Los nombres
completamente cualificados son absolutos, por lo que no se ven afectados por la importación.
Ejemplo #4 La importación y los nombres completamente cualificados
<?php
use Mi\Completo\NombreDeClase as Otra, Mi\Completo\NombreEN;
$obj = new Otra; // instancia un objeto de la clase Mi\Completo\NombreDeClase
$obj = new \Otra; // instancia un objeto de la clase Otra
$obj = new Otra\cosa; // instancia un objeto de la clase Mi\Completo\NombreDeClase\cosa
$obj = new \Otra\cosa; // instancia un objeto de la clase Otra\cosa
?>
Reglas de ámbito para la importación
La palabra reservada use
debe ser declarada en el
ámbito exterior de un fichero (el ámbito global) o dentro de declaraciones
de espacios de nombres. Esto es así debido a que la importación se realiza durante
la compilación y no durante la ejecución, por lo que no puede ser utilizada en un ámbito de bloque. El siguiente
ejemplo muestra un uso ilegal de la palabra reservada
use
:
Ejemplo #5 Regla de importación ilegal
<?php
namespace Idiomas;
function aGroenlandés
{
use Idiomas\Danés;
// ...
}
?>
Nota:
Las reglas de importación tiene una base por fichero, lo que significa que los ficheros incluidos
NO heredarán las reglas de importación del padre.
Declaraciones de use
en grupo
Desde PHP 7.0 en adelante, las clases, funciones y constantes importadas desde
el mismo namespace
pueden ser agrupadas en una única sentencia
use
.