PHP 8.4.0 RC2 available for testing

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.

<?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};
add a note

User Contributed Notes 17 notes

up
194
dominic_mayers at yahoo dot com
8 years ago
The keyword "use" has been recycled for three distinct applications:
1- to import/alias classes, traits, constants, etc. in namespaces,
2- to insert traits in classes,
3- to inherit variables in closures.
This page is only about the first application: importing/aliasing. Traits can be inserted in classes, but this is different from importing a trait in a namespace, which cannot be done in a block scope, as pointed out in example 5. This can be confusing, especially since all searches for the keyword "use" are directed to the documentation here on importing/aliasing.
up
156
anon
10 years ago
The <?php use ?> statement does not load the class file. You have to do this with the <?php require ?> statement or by using an autoload function.
up
56
Mawia HL
6 years ago
Here is a handy way of importing classes, functions and conts using a single use keyword:

<?php
use Mizo\Web\ {
Php\WebSite,
Php\KeyWord,
Php\UnicodePrint,
JS\JavaScript,
function
JS\printTotal,
function
JS\printList,
const
JS\BUAIKUM,
const
JS\MAUTAM
};
?>
up
80
k at webnfo dot com
11 years ago
Note that you can not alias global namespace:

use \ as test;

echo test\strlen('');

won't work.
up
33
xzero at elite7hackers dot net
7 years ago
I couldn't find answer to this question so I tested myself.
I think it's worth noting:

<?php
use ExistingNamespace\NonExsistingClass;
use
ExistingNamespace\NonExsistingClass as whatever;
use
NonExistingNamespace\NonExsistingClass;
use
NonExistingNamespace\NonExsistingClass as whatever;
?>

None of above will actually cause errors unless you actually try to use class you tried to import.

<?php
// And this code will issue standard PHP error for non existing class.
use ExistingNamespace\NonExsistingClass as whatever;
$whatever = new whatever();
?>
up
23
me at ruslanbes dot com
8 years ago
Note the code `use ns1\c1` may refer to importing class `c1` from namespace `ns1` as well as importing whole namespace `ns1\c1` or even import both of them in one line. Example:

<?php
namespace ns1;

class
c1{}

namespace
ns1\c1;

class
c11{}

namespace
main;

use
ns1\c1;

$c1 = new c1();
$c11 = new c1\c11();

var_dump($c1); // object(ns1\c1)#1 (0) { }
var_dump($c11); // object(ns1\c1\c11)#2 (0) { }
up
28
c dot 1 at smithies dot org
13 years ago
If you are testing your code at the CLI, note that namespace aliases do not work!

(Before I go on, all the backslashes in this example are changed to percent signs because I cannot get sensible results to display in the posting preview otherwise. Please mentally translate all percent signs henceforth as backslashes.)

Suppose you have a class you want to test in myclass.php:

<?php
namespace my%space;
class
myclass {
// ...
}
?>

and you then go into the CLI to test it. You would like to think that this would work, as you type it line by line:

require 'myclass.php';
use my%space%myclass; // should set 'myclass' as alias for 'my%space%myclass'
$x = new myclass; // FATAL ERROR

I believe that this is because aliases are only resolved at compile time, whereas the CLI simply evaluates statements; so use statements are ineffective in the CLI.

If you put your test code into test.php:
<?php
require 'myclass.php';
use
my%space%myclass;
$x = new myclass;
//...
?>
it will work fine.

I hope this reduces the number of prematurely bald people.
up
20
x at d dot a dot r dot k dot REMOVEDOTSANDTHIS dot gray dot org
11 years ago
You are allowed to "use" the same resource multiple times as long as it is imported under a different alias at each invocation.

For example:

<?php
use Lend;
use
Lend\l1;
use
Lend\l1 as l3;
use
Lend\l2;
use
Lend\l1\Keller;
use
Lend\l1\Keller as Stellar;
use
Lend\l1\Keller as Zellar;
use
Lend\l2\Keller as Dellar;

...

?>

In the above example, "Keller", "Stellar", and "Zellar" are all references to "\Lend\l1\Keller", as are "Lend\l1\Keller", "l1\Keller", and "l3\Keller".
up
16
cl
11 years ago
Something that is not immediately obvious, particular with PHP 5.3, is that namespace resolutions within an import are not resolved recursively. i.e.: if you alias an import and then use that alias in another import then this latter import will not be fully resolved with the former import.

For example:
use \Controllers as C;
use C\First;
use C\Last;

Both the First and Last namespaces are NOT resolved as \Controllers\First or \Controllers\Last as one might intend.
up
3
ultimater at gmail dot com
8 years ago
Note that "use" importing/aliasing only applies to the current namespace block.

<?php

namespace SuperCoolLibrary
{
class
Meta
{
static public function
getVersion()
{
return
'2.7.1';
}
}
}

namespace
{
use
SuperCoolLibrary\Meta;
echo
Meta::getVersion();//outputs 2.7.1
}

namespace
{
echo
Meta::getVersion();//fatal error
}

?>

To get the expected behavior, you'd use:
class_alias('SuperCoolLibrary\Meta','Meta');
up
1
ZhangLiang
7 years ago
In Chinese,there is an error in translation:
// 如果不使用 "use \ArrayObject" ,则实例化一个 foo\ArrayObject 对象
it should be
// 如果不使用 "use ArrayObject" ,则实例化一个 foo\ArrayObject 对象

/*********************************************/
中文下翻译有错误
// 如果不使用 "use \ArrayObject" ,则实例化一个 foo\ArrayObject 对象
这句话应该是
// 如果不使用 "use ArrayObject" ,则实例化一个 foo\ArrayObject 对象
up
0
eithed at google mail
3 years ago
Bear in mind that it's perfectly fine to alias namespaces, ie:

<?php
use A\B\C\D\E\User;

new
User();
?>

can be also written as:

<?php
use A\B\C\D\E as ENamespace;

new
ENamespace\User();
?>

however following will not work:

<?php
use A\B\C\D\E as ENamespace;
use
ENamespace\User;

new
User();
?>

> PHP Error: Class "ENamespace\User" not found
up
0
thinice at gmail.com
13 years ago
Because imports happen at compile time, there's no polymorphism potential by embedding the use keyword in a conditonal.

e.g.:

<?php
if ($objType == 'canine') {
use
Animal\Canine as Beast;
}
if (
$objType == 'bovine') {
use
Animal\Bovine as Beast;
}

$oBeast = new Beast;
$oBeast->feed();
?>
up
-2
dominic_mayers at yahoo dot com
8 years ago
To clarify the distinction between inserting a trait in a class and importing a trait in a namespace, here is an example where we first import and then insert a trait.

<?php
namespace ns1;
trait
T {
static
$a = "In T";
}

namespace
ns2;
use
ns1\T; // Importing the name of trait ns1\T in the namespace ns2
class C {
use
T; // Inserting trait T in the class C, making use of the imported name.
}

namespace
main;
use
ns2\C;
echo
C::$a; // In T;
up
-5
kelerest123 at gmail dot com
9 years ago
For the fifth example (example #5):

When in block scope, it is not an illegal use of use keyword, because it is used for sharing things with traits.
up
-3
info at ensostudio dot ru
4 years ago
Note: you can import not existed items without errors:
<?php
use UndefinedClass;
use function
undefined_fn;
use const
UNDEFINED_CONST;
?>
but you cant use/call they:
<?php
$new UndefinedClass
; // Error: Use of undefined class
use function undefined_fn; // Error: Use of undefined function
use const UNDEFINED_CONST; // Error: Use of undefined constant
?>
up
-3
tuxedobob
2 years ago
Note that because this is processed at compile time, this doesn't work when running PHP in interactive mode. use commands won't throw an error, but they won't do anything, either.
To Top