Using namespaces: Aliasing/Importing

(PHP 5 >= 5.3.0, PHP 7)

The ability to refer to an external fully qualified name with an alias, or importing,
is an important feature of namespaces. This is similar to the
ability of unix-based filesystems to create symbolic links to a file or to a directory.

All versions of PHP that support namespaces support three kinds of aliasing
or importing: aliasing a class name, aliasing an interface name, and
aliasing a namespace name. PHP 5.6+ also allows aliasing or importing
function and constant names.

In PHP, aliasing is accomplished with the use operator. Here
is an example showing all 5 kinds of importing:

Example #1 importing/aliasing with the use operator

<?phpnamespace foo;use My\Full\Classname as Another;

// this is the same as use My\Full\NSname as NSnameuse My\Full\NSname;

Note that for namespaced names (fully qualified namespace names containing
namespace separator, such as Foo\Bar as opposed to global names that
do not, such as FooBar), the leading backslash is unnecessary and not
recommended, as import names
must be fully qualified, and are not processed relative to the current namespace.

PHP additionally supports a convenience shortcut to place multiple use statements
on the same line

Example #2 importing/aliasing with the use operator, multiple use statements combined

Scoping rules for importing

The use keyword must be declared in the
outermost scope of a file (the global scope) or inside namespace
declarations. This is because the importing is done at compile
time and not runtime, so it cannot be block scoped. The following
example will show an illegal use of the use
keyword:

Example #5 Illegal importing rule

<?phpnamespace Languages;

function toGreenlandic(){ use Languages\Danish;

// ...}?>

Note:

Importing rules are per file basis, meaning included files will
NOT inherit the parent file's importing rules.

Group use declarations

From PHP 7.0 onwards, classes, functions and constants being imported from
the same namespace can be grouped together in a single use
statement.

User Contributed Notes 16 notes

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.

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:

<?phpnamespace 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:

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.

For those hoping for an easy fix of DRY with {} unfortunately you can't nest it or do anything cool with it. In case you can only have one per use and if you don't have one then the whole use is assumed to be wrapped in brackets. That means if you do have one you can't use , as normal with use!