<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Using namespaces: Aliasing/Importing</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.namespaces.nsconstants.html">namespace keyword and __NAMESPACE__ constant</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.namespaces.global.html">Global space</a></div>
<div class="up"><a href="language.namespaces.html">Namespaces</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="language.namespaces.importing" class="sect1">
<h2 class="title">Using namespaces: Aliasing/Importing</h2>
<p class="verinfo">(PHP 5 >= 5.3.0)</p>
<p class="para">
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.
</p>
<p class="para">
PHP namespaces support
three kinds of aliasing or importing: aliasing a class name, aliasing an interface name,
and aliasing a namespace name.
Note that importing a function or constant is not supported.
</p>
<p class="para">
In PHP, aliasing is accomplished with the <em>use</em> operator. Here
is an example showing all 3 kinds of importing:
<div class="example" id="example-249">
<p><strong>Example #1 importing/aliasing with the use operator</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">namespace </span><span style="color: #0000BB">foo</span><span style="color: #007700">;<br />use </span><span style="color: #0000BB">My</span><span style="color: #007700">\</span><span style="color: #0000BB">Full</span><span style="color: #007700">\</span><span style="color: #0000BB">Classname </span><span style="color: #007700">as </span><span style="color: #0000BB">Another</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">// this is the same as use My\Full\NSname as NSname<br /></span><span style="color: #007700">use </span><span style="color: #0000BB">My</span><span style="color: #007700">\</span><span style="color: #0000BB">Full</span><span style="color: #007700">\</span><span style="color: #0000BB">NSname</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">// importing a global class<br /></span><span style="color: #007700">use </span><span style="color: #0000BB">ArrayObject</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new namespace\</span><span style="color: #0000BB">Another</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class foo\Another<br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">Another</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class My\Full\Classname<br /></span><span style="color: #0000BB">NSname</span><span style="color: #007700">\</span><span style="color: #0000BB">subns</span><span style="color: #007700">\</span><span style="color: #0000BB">func</span><span style="color: #007700">(); </span><span style="color: #FF8000">// calls function My\Full\NSname\subns\func<br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= new </span><span style="color: #0000BB">ArrayObject</span><span style="color: #007700">(array(</span><span style="color: #0000BB">1</span><span style="color: #007700">)); </span><span style="color: #FF8000">// instantiates object of class ArrayObject<br />// without the "use ArrayObject" we would instantiate an object of class foo\ArrayObject<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
Note that for namespaced names (fully qualified namespace names containing
namespace separator, such as <em>Foo\Bar</em> as opposed to global names that
do not, such as <em>FooBar</em>), the leading backslash is unnecessary and not
recommended, as import names
must be fully qualified, and are not processed relative to the current namespace.
</p>
<p class="para">
PHP additionally supports a convenience shortcut to place multiple use statements
on the same line
<div class="example" id="example-250">
<p><strong>Example #2 importing/aliasing with the use operator, multiple use statements combined</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">use </span><span style="color: #0000BB">My</span><span style="color: #007700">\</span><span style="color: #0000BB">Full</span><span style="color: #007700">\</span><span style="color: #0000BB">Classname </span><span style="color: #007700">as </span><span style="color: #0000BB">Another</span><span style="color: #007700">, </span><span style="color: #0000BB">My</span><span style="color: #007700">\</span><span style="color: #0000BB">Full</span><span style="color: #007700">\</span><span style="color: #0000BB">NSname</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">Another</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class My\Full\Classname<br /></span><span style="color: #0000BB">NSname</span><span style="color: #007700">\</span><span style="color: #0000BB">subns</span><span style="color: #007700">\</span><span style="color: #0000BB">func</span><span style="color: #007700">(); </span><span style="color: #FF8000">// calls function My\Full\NSname\subns\func<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
Importing is performed at compile-time, and so does not affect dynamic class, function
or constant names.
<div class="example" id="example-251">
<p><strong>Example #3 Importing and dynamic names</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">use </span><span style="color: #0000BB">My</span><span style="color: #007700">\</span><span style="color: #0000BB">Full</span><span style="color: #007700">\</span><span style="color: #0000BB">Classname </span><span style="color: #007700">as </span><span style="color: #0000BB">Another</span><span style="color: #007700">, </span><span style="color: #0000BB">My</span><span style="color: #007700">\</span><span style="color: #0000BB">Full</span><span style="color: #007700">\</span><span style="color: #0000BB">NSname</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">Another</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class My\Full\Classname<br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= </span><span style="color: #DD0000">'Another'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">$a</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class Another<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
In addition, importing only affects unqualified and qualified names. Fully qualified
names are absolute, and unaffected by imports.
<div class="example" id="example-252">
<p><strong>Example #4 Importing and fully qualified names</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">use </span><span style="color: #0000BB">My</span><span style="color: #007700">\</span><span style="color: #0000BB">Full</span><span style="color: #007700">\</span><span style="color: #0000BB">Classname </span><span style="color: #007700">as </span><span style="color: #0000BB">Another</span><span style="color: #007700">, </span><span style="color: #0000BB">My</span><span style="color: #007700">\</span><span style="color: #0000BB">Full</span><span style="color: #007700">\</span><span style="color: #0000BB">NSname</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">Another</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class My\Full\Classname<br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new \</span><span style="color: #0000BB">Another</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class Another<br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">Another</span><span style="color: #007700">\</span><span style="color: #0000BB">thing</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class My\Full\Classname\thing<br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new \</span><span style="color: #0000BB">Another</span><span style="color: #007700">\</span><span style="color: #0000BB">thing</span><span style="color: #007700">; </span><span style="color: #FF8000">// instantiates object of class Another\thing<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<div class="sect2" id="language.namespaces.importing.scope">
<h3 class="title">Scoping rules for importing</h3>
<p class="para">
The <em>use</em> 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 <em>use</em>
keyword:
</p>
<p class="para">
<div class="example" id="example-253">
<p><strong>Example #5 Illegal importing rule</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">namespace </span><span style="color: #0000BB">Languages</span><span style="color: #007700">;<br /><br />class </span><span style="color: #0000BB">Greenlandic<br /></span><span style="color: #007700">{<br /> use </span><span style="color: #0000BB">Languages</span><span style="color: #007700">\</span><span style="color: #0000BB">Danish</span><span style="color: #007700">;<br /><br /> ...<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Importing rules are per file basis, meaning included files will
<em class="emphasis">NOT</em> inherit the parent file's importing rules.
</p>
</p></blockquote>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.namespaces.nsconstants.html">namespace keyword and __NAMESPACE__ constant</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.namespaces.global.html">Global space</a></div>
<div class="up"><a href="language.namespaces.html">Namespaces</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
