<!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: Basics</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.namespaces.definitionmultiple.html">Defining multiple namespaces in the same file</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.namespaces.dynamic.html">Namespaces and dynamic language features</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.basics" class="sect1">
<h2 class="title">Using namespaces: Basics</h2>
<p class="verinfo">(PHP 5 >= 5.3.0)</p>
<p class="para">
Before discussing the use of namespaces, it is important to understand how PHP
knows which namespaced element your code is requesting. A simple analogy can be made
between PHP namespaces and a filesystem. There are three ways to access a file in a
file system:
<ol type="1">
<li class="listitem">
<span class="simpara">
Relative file name like <em>foo.txt</em>. This resolves to
<em>currentdirectory/foo.txt</em> where currentdirectory is the
directory currently occupied. So if the current directory is
<em>/home/foo</em>, the name resolves to <em>/home/foo/foo.txt</em>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Relative path name like <em>subdirectory/foo.txt</em>. This resolves
to <em>currentdirectory/subdirectory/foo.txt</em>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Absolute path name like <em>/main/foo.txt</em>. This resolves
to <em>/main/foo.txt</em>.
</span>
</li>
</ol>
The same principle can be applied to namespaced elements in PHP. For
example, a class name can be referred to in three ways:
<ol type="1">
<li class="listitem">
<span class="simpara">
Unqualified name, or an unprefixed class name like
<em>$a = new foo();</em> or
<em>foo::staticmethod();</em>. If the current namespace is
<em>currentnamespace</em>, this resolves to
<em>currentnamespace\foo</em>. If
the code is global, non-namespaced code, this resolves to <em>foo</em>.
</span>
<span class="simpara">
One caveat: unqualified names for functions and constants will
resolve to global functions and constants if the namespaced function or constant
is not defined. See <a href="language.namespaces.fallback.html" class="link">Using namespaces:
fallback to global function/constant</a> for details.
</span>
</li>
<li class="listitem">
<span class="simpara">
Qualified name, or a prefixed class name like
<em>$a = new subnamespace\foo();</em> or
<em>subnamespace\foo::staticmethod();</em>. If the current namespace is
<em>currentnamespace</em>, this resolves to
<em>currentnamespace\subnamespace\foo</em>. If
the code is global, non-namespaced code, this resolves to <em>subnamespace\foo</em>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Fully qualified name, or a prefixed name with global prefix operator like
<em>$a = new \currentnamespace\foo();</em> or
<em>\currentnamespace\foo::staticmethod();</em>. This always resolves
to the literal name specified in the code, <em>currentnamespace\foo</em>.
</span>
</li>
</ol>
</p>
<p class="para">
Here is an example of the three kinds of syntax in actual code:
<div class="informalexample">
<p class="simpara">file1.php</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">\</span><span style="color: #0000BB">Bar</span><span style="color: #007700">\</span><span style="color: #0000BB">subnamespace</span><span style="color: #007700">;<br /><br />const </span><span style="color: #0000BB">FOO </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br />function </span><span style="color: #0000BB">foo</span><span style="color: #007700">() {}<br />class </span><span style="color: #0000BB">foo<br /></span><span style="color: #007700">{<br /> static function </span><span style="color: #0000BB">staticmethod</span><span style="color: #007700">() {}<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<p class="simpara">file2.php</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">\</span><span style="color: #0000BB">Bar</span><span style="color: #007700">;<br />include </span><span style="color: #DD0000">'file1.php'</span><span style="color: #007700">;<br /><br />const </span><span style="color: #0000BB">FOO </span><span style="color: #007700">= </span><span style="color: #0000BB">2</span><span style="color: #007700">;<br />function </span><span style="color: #0000BB">foo</span><span style="color: #007700">() {}<br />class </span><span style="color: #0000BB">foo<br /></span><span style="color: #007700">{<br /> static function </span><span style="color: #0000BB">staticmethod</span><span style="color: #007700">() {}<br />}<br /><br /></span><span style="color: #FF8000">/* Unqualified name */<br /></span><span style="color: #0000BB">foo</span><span style="color: #007700">(); </span><span style="color: #FF8000">// resolves to function Foo\Bar\foo<br /></span><span style="color: #0000BB">foo</span><span style="color: #007700">::</span><span style="color: #0000BB">staticmethod</span><span style="color: #007700">(); </span><span style="color: #FF8000">// resolves to class Foo\Bar\foo, method staticmethod<br /></span><span style="color: #007700">echo </span><span style="color: #0000BB">FOO</span><span style="color: #007700">; </span><span style="color: #FF8000">// resolves to constant Foo\Bar\FOO<br /><br />/* Qualified name */<br /></span><span style="color: #0000BB">subnamespace</span><span style="color: #007700">\</span><span style="color: #0000BB">foo</span><span style="color: #007700">(); </span><span style="color: #FF8000">// resolves to function Foo\Bar\subnamespace\foo<br /></span><span style="color: #0000BB">subnamespace</span><span style="color: #007700">\</span><span style="color: #0000BB">foo</span><span style="color: #007700">::</span><span style="color: #0000BB">staticmethod</span><span style="color: #007700">(); </span><span style="color: #FF8000">// resolves to class Foo\Bar\subnamespace\foo,<br /> // method staticmethod<br /></span><span style="color: #007700">echo </span><span style="color: #0000BB">subnamespace</span><span style="color: #007700">\</span><span style="color: #0000BB">FOO</span><span style="color: #007700">; </span><span style="color: #FF8000">// resolves to constant Foo\Bar\subnamespace\FOO<br /> <br />/* Fully qualified name */<br /></span><span style="color: #007700">\</span><span style="color: #0000BB">Foo</span><span style="color: #007700">\</span><span style="color: #0000BB">Bar</span><span style="color: #007700">\</span><span style="color: #0000BB">foo</span><span style="color: #007700">(); </span><span style="color: #FF8000">// resolves to function Foo\Bar\foo<br /></span><span style="color: #007700">\</span><span style="color: #0000BB">Foo</span><span style="color: #007700">\</span><span style="color: #0000BB">Bar</span><span style="color: #007700">\</span><span style="color: #0000BB">foo</span><span style="color: #007700">::</span><span style="color: #0000BB">staticmethod</span><span style="color: #007700">(); </span><span style="color: #FF8000">// resolves to class Foo\Bar\foo, method staticmethod<br /></span><span style="color: #007700">echo \</span><span style="color: #0000BB">Foo</span><span style="color: #007700">\</span><span style="color: #0000BB">Bar</span><span style="color: #007700">\</span><span style="color: #0000BB">FOO</span><span style="color: #007700">; </span><span style="color: #FF8000">// resolves to constant Foo\Bar\FOO<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
Note that to access any global
class, function or constant, a fully qualified name can be used, such as
<span class="function"><strong>\strlen()</strong></span> or <strong class="classname">\Exception</strong> or
<em>\INI_ALL</em>.
<div class="example" id="example-241">
<p><strong>Example #1 Accessing global classes, functions and constants from within a namespace</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 /><br />function </span><span style="color: #0000BB">strlen</span><span style="color: #007700">() {}<br />const </span><span style="color: #0000BB">INI_ALL </span><span style="color: #007700">= </span><span style="color: #0000BB">3</span><span style="color: #007700">;<br />class </span><span style="color: #0000BB">Exception </span><span style="color: #007700">{}<br /><br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= \</span><span style="color: #0000BB">strlen</span><span style="color: #007700">(</span><span style="color: #DD0000">'hi'</span><span style="color: #007700">); </span><span style="color: #FF8000">// calls global function strlen<br /></span><span style="color: #0000BB">$b </span><span style="color: #007700">= \</span><span style="color: #0000BB">INI_ALL</span><span style="color: #007700">; </span><span style="color: #FF8000">// accesses global constant INI_ALL<br /></span><span style="color: #0000BB">$c </span><span style="color: #007700">= new \</span><span style="color: #0000BB">Exception</span><span style="color: #007700">(</span><span style="color: #DD0000">'error'</span><span style="color: #007700">); </span><span style="color: #FF8000">// instantiates global class Exception<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.namespaces.definitionmultiple.html">Defining multiple namespaces in the same file</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.namespaces.dynamic.html">Namespaces and dynamic language features</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>
