<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$TOC_DEPRECATED = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/language.namespaces.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'it',
),
'this' =>
array (
0 => 'language.namespaces.basics.php',
1 => 'Basics',
),
'up' =>
array (
0 => 'language.namespaces.php',
1 => 'Namespaces',
),
'prev' =>
array (
0 => 'language.namespaces.definitionmultiple.php',
1 => 'Defining multiple namespaces in the same file',
),
'next' =>
array (
0 => 'language.namespaces.dynamic.php',
1 => 'Namespaces and dynamic language features',
),
'alternatives' =>
array (
),
'source' =>
array (
'lang' => 'en',
'path' => 'language/namespaces.xml',
),
'history' =>
array (
),
);
$setup["toc"] = $TOC;
$setup["toc_deprecated"] = $TOC_DEPRECATED;
$setup["parents"] = $PARENTS;
manual_setup($setup);
contributors($setup);
?>
<div id="language.namespaces.basics" class="sect1">
<h2 class="title">Using namespaces: Basics</h2>
<p class="verinfo">(PHP 5 >= 5.3.0, PHP 7, PHP 8)</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 <code class="literal">foo.txt</code>. This resolves to
<code class="literal">currentdirectory/foo.txt</code> where <code class="literal">currentdirectory</code> is the
directory currently occupied. So if the current directory is
<code class="literal">/home/foo</code>, the name resolves to <code class="literal">/home/foo/foo.txt</code>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Relative path name like <code class="literal">subdirectory/foo.txt</code>. This resolves
to <code class="literal">currentdirectory/subdirectory/foo.txt</code>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Absolute path name like <code class="literal">/main/foo.txt</code>. This resolves
to <code class="literal">/main/foo.txt</code>.
</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
<code class="literal">$a = new foo();</code> or
<code class="literal">foo::staticmethod();</code>. If the current namespace is
<code class="literal">currentnamespace</code>, this resolves to
<code class="literal">currentnamespace\foo</code>. If
the code is global, non-namespaced code, this resolves to <code class="literal">foo</code>.
</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.php" 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
<code class="literal">$a = new subnamespace\foo();</code> or
<code class="literal">subnamespace\foo::staticmethod();</code>. If the current namespace is
<code class="literal">currentnamespace</code>, this resolves to
<code class="literal">currentnamespace\subnamespace\foo</code>. If
the code is global, non-namespaced code, this resolves to <code class="literal">subnamespace\foo</code>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Fully qualified name, or a prefixed name with global prefix operator like
<code class="literal">$a = new \currentnamespace\foo();</code> or
<code class="literal">\currentnamespace\foo::staticmethod();</code>. This always resolves
to the literal name specified in the code, <code class="literal">currentnamespace\foo</code>.
</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\Bar\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\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\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\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\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: #0000BB">\Foo\Bar\foo</span><span style="color: #007700">(); </span><span style="color: #FF8000">// resolves to function Foo\Bar\foo<br /></span><span style="color: #0000BB">\Foo\Bar\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\Bar\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"><a href="function.strlen.php" class="function">\strlen()</a></span> or <span class="classname"><a href="class.exception.php" class="classname">\Exception</a></span> or
\<strong><code><a href="info.constants.php#constant.ini-all">INI_ALL</a></code></strong>.
<div class="example" id="example-346">
<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><?php manual_footer($setup); ?>