Uso de los espacios de nombres: apodar/importar

(PHP 5 >= 5.3.0, PHP 7)

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.


<?php

// Código anterir a PHP 7
use un\espacioDeNombres\ClaseA;
use un\espacioDeNombres\ClaseB;
use un\espacioDeNombres\ClaseC as C;

use function un\espacioDeNombres\fn_a;
use function un\espacioDeNombres\fn_b;
use function un\espacioDeNombres\fn_c;

use const un\espacioDeNombres\ConstA;
use const un\espacioDeNombres\ConstB;
use const un\espacioDeNombres\ConstC;

// Código de PHP 7+
use un\espacioDeNombres\{ClaseA, ClaseB, ClaseC as C};
use function un\espacioDeNombres\{fn_a, fn_b, fn_c};
use const un\espacioDeNombres\{ConstA, ConstB, ConstC};